clice/docs/en/architecture.md

# Server Architecture

clice uses a **multi-process architecture** where a single **Master Server** coordinates multiple **Worker** processes. This design isolates Clang AST operations (which are memory-heavy and may crash) from the main LSP event loop.

## Overview

```
┌──────────────┐   JSON/LSP    ┌────────────────┐   Bincode/IPC   ┌──────────────────┐
│   LSP Client │ ◄──────────► │  Master Server  │ ◄─────────────► │ Stateful Workers │
│   (Editor)   │    (stdio)    │                 │    (stdio)      │  (AST cache)     │
└──────────────┘               │  - Lifecycle    │                 └──────────────────┘
                               │  - Documents    │
                               │  - CDB          │   Bincode/IPC   ┌──────────────────┐
                               │  - Build drain  │ ◄─────────────► │ Stateless Workers│
                               │  - Indexing     │    (stdio)      │  (one-shot tasks)│
                               └────────────────┘                 └──────────────────┘
```

## Master Server

The master server (`src/server/master_server.cpp`) is the central coordinator. It runs a single-threaded async event loop and never touches Clang directly. Its responsibilities:

### LSP Lifecycle

The server progresses through these states:

1. **Uninitialized** — waiting for `initialize` request
2. **Initialized** — capabilities exchanged, waiting for `initialized` notification
3. **Ready** — workers spawned, workspace loaded, accepting requests
4. **ShuttingDown** — `shutdown` received, draining work
5. **Exited** — `exit` received, stopping the event loop

On `initialized`, the master:

- Loads configuration from `clice.toml` (or uses defaults)
- Starts the worker pool (spawns stateful + stateless processes)
- Loads `compile_commands.json` and builds an include graph
- Starts the background indexer coroutine (if enabled)

### Document Management

Each open document is tracked in a `DocumentState` with:

- Current `version` and `text` (kept in sync via `didOpen`/`didChange`)
- A `generation` counter to detect stale compile results
- Build state flags (`build_running`, `build_requested`, `drain_scheduled`)

When a document is opened or changed:

1. The include graph is re-scanned (via dependency directives)
2. The compile unit is registered/updated in the `CompileGraph`
3. A debounced build is scheduled

### Build Drain

The `run_build_drain` coroutine implements debounced compilation:

1. Wait for the debounce timer (default 200ms) to expire
2. Ensure PCH/PCM dependencies are ready via `CompileGraph`
3. Send a `compile` request to the assigned stateful worker
4. Publish diagnostics from the result (or clear them on failure)
5. If more edits arrived during compilation (`build_requested`), loop back to step 2

This ensures rapid typing doesn't trigger a compile per keystroke.

### Request Routing

Feature requests are split between two worker types:

**Stateful workers** (affinity-routed by file path):

- `textDocument/hover`
- `textDocument/semanticTokens/full`
- `textDocument/inlayHint`
- `textDocument/foldingRange`
- `textDocument/documentSymbol`
- `textDocument/documentLink`
- `textDocument/codeAction`
- `textDocument/definition`

**Stateless workers** (round-robin):

- `textDocument/completion`
- `textDocument/signatureHelp`

All feature responses use `RawValue` passthrough — the worker serializes the LSP result to JSON, and the master forwards the raw JSON bytes to the client without deserializing. This avoids bincode↔JSON conversion overhead and serde annotation conflicts.

## Worker Pool

The worker pool (`src/server/worker_pool.cpp`) manages spawning and communicating with worker processes. Each worker is a child process of the same `clice` binary, launched with `--mode stateful-worker` or `--mode stateless-worker`.

### Communication

Workers communicate with the master via **stdio pipes** using a **bincode** serialization format (via `kota::ipc::BincodePeer`). This is more compact and faster than JSON for internal IPC, while the master handles JSON for the external LSP protocol.

### Stateful Worker Routing

Stateful workers use **affinity routing**: each file is consistently assigned to the same worker so that the worker retains the cached AST. Assignment uses a **least-loaded** strategy for new files, with **LRU tracking** to manage ownership.

When a worker exceeds its document capacity (currently hardcoded at 16 documents), it evicts the least-recently-used document and notifies the master via an `evicted` notification.

### Stateless Worker Routing

Stateless workers use simple **round-robin** dispatch. Each request includes the full source text and compilation arguments, so any worker can handle it independently.

## Stateful Worker

The stateful worker (`src/server/stateful_worker.cpp`) caches compiled ASTs in memory. Key behavior:

- **Compile**: Parses source code into a `CompilationUnit`, caches the AST, and returns diagnostics as a `RawValue` (JSON bytes)
- **Feature queries**: Look up the cached AST and invoke the corresponding `feature::*` function (hover, semantic tokens, etc.), serializing the result to JSON
- **Document updates**: Received as notifications — the worker updates the stored text and marks the document as `dirty`, causing feature queries to return `null` until recompilation
- **Eviction**: LRU-based; evicts the oldest document when capacity is exceeded, notifying the master
- **Concurrency**: Each document has a per-document `kota::mutex` (strand) to serialize compilation and feature queries. Heavy work (compilation, feature extraction) runs on a thread pool via `kota::queue`.

## Stateless Worker

The stateless worker (`src/server/stateless_worker.cpp`) handles one-shot requests that don't benefit from cached ASTs:

- **Completion**: Creates a fresh compilation with `CompilationKind::Completion` and invokes `feature::code_complete`
- **Signature help**: Similar to completion, using `feature::signature_help`
- **Build PCH**: Compiles a precompiled header to a temporary file
- **Build PCM**: Compiles a C++20 module interface to a temporary file
- **Index**: Compiles a file for indexing (TUIndex generation — currently a stub)

All requests are dispatched to a thread pool via `kota::queue`.

## Compile Graph

The compile graph (`src/server/compile_graph.cpp`) tracks compilation unit dependencies as a DAG. It handles:

- **Registration**: Each file registers its included dependencies
- **Cascade invalidation**: When a file changes, all transitive dependents are marked dirty and their ongoing compilations are cancelled
- **Dependency compilation**: Before compiling a file, `compile_deps` ensures all dependencies (PCH, PCMs) are built first
- **Cancellation**: Uses `kota::cancellation_source` to abort in-flight compilations when files are invalidated

## Configuration

The server reads configuration from `clice.toml` (or `.clice/config.toml`) in the workspace root. If no config file exists, sensible defaults are computed from system resources:

| Setting                  | Default               | Description                                 |
| ------------------------ | --------------------- | ------------------------------------------- |
| `stateful_worker_count`  | CPU cores / 4         | Number of stateful worker processes         |
| `stateless_worker_count` | CPU cores / 4         | Number of stateless worker processes        |
| `worker_memory_limit`    | 4 GB                  | Memory limit per stateful worker            |
| `compile_commands_path`  | auto-detect           | Path to `compile_commands.json`             |
| `cache_dir`              | `<workspace>/.clice/` | Cache directory for PCH/PCM files           |
| `debounce_ms`            | 200                   | Debounce interval for recompilation         |
| `enable_indexing`        | true                  | Enable background indexing                  |
| `idle_timeout_ms`        | 3000                  | Idle time before background indexing starts |

String values support `${workspace}` substitution.

## IPC Protocol

The master and workers communicate using custom RPC messages defined in `src/server/protocol/`. Each message type has a `RequestTraits` or `NotificationTraits` specialization that defines the method name and result type.

### Stateful Worker Messages

| Method                        | Direction    | Purpose                               |
| ----------------------------- | ------------ | ------------------------------------- |
| `clice/worker/compile`        | Request      | Compile source and return diagnostics |
| `clice/worker/hover`          | Request      | Get hover info at position            |
| `clice/worker/semanticTokens` | Request      | Get semantic tokens for file          |
| `clice/worker/inlayHints`     | Request      | Get inlay hints for range             |
| `clice/worker/foldingRange`   | Request      | Get folding ranges                    |
| `clice/worker/documentSymbol` | Request      | Get document symbols                  |
| `clice/worker/documentLink`   | Request      | Get document links                    |
| `clice/worker/codeAction`     | Request      | Get code actions for range            |
| `clice/worker/goToDefinition` | Request      | Go to definition at position          |
| `clice/worker/documentUpdate` | Notification | Update document text (marks dirty)    |
| `clice/worker/evict`          | Notification | Master → Worker: evict a document     |
| `clice/worker/evicted`        | Notification | Worker → Master: document was evicted |

### Stateless Worker Messages

| Method                       | Direction | Purpose                      |
| ---------------------------- | --------- | ---------------------------- |
| `clice/worker/completion`    | Request   | Code completion at position  |
| `clice/worker/signatureHelp` | Request   | Signature help at position   |
| `clice/worker/buildPCH`      | Request   | Build precompiled header     |
| `clice/worker/buildPCM`      | Request   | Build C++20 module interface |
| `clice/worker/index`         | Request   | Index a translation unit     |