# Architecture Overview

DotCraft is a .NET 10 / C# Agent Harness. Its modular design lets CLI, editors, bots, automations, and GitHub workflows share one workspace and reuse the same sessions, memory, skills, and tools. This page targets **integrators and contributors** — it explains the code-level boundaries that matter for extension and troubleshooting.

## Top-Level Modules

```mermaid
flowchart TB
  subgraph Hosts[" Hosts (interactive entry points) "]
    direction LR
    CLI["DotCraft.App<br/>(CLI host, priority 0)"]
    Gateway["DotCraft.Gateway<br/>(default, runs Channels)"]
  end

  subgraph Channels[" Channels (managed by Gateway) "]
    direction LR
    Acp["DotCraft.Acp"]
    Auto["DotCraft.Automations"]
    Ext["External channels<br/>(qq · wecom · feishu · telegram · weixin)"]
  end

  subgraph Core[" DotCraft.Core "]
    direction TB
    Session["Session Core<br/>(Thread/Turn/Item, ISessionService)"]
    Agents["Agents<br/>(MS Extensions.AI · subagents · compaction)"]
    Tools["Tools<br/>(File · Shell · Web · LSP · Plan/Todo)"]
    Memory["Memory<br/>(MEMORY.md · HISTORY.md · Dreams)"]
    SkillsCore["Skills · Plugins · MCP"]
  end

  subgraph Workspace[" Workspace state "]
    Craft[".craft/<br/>(threads · sessions · skills · plugins · automations · memory · dreams)"]
  end

  CLI --> Core
  Gateway --> Channels
  Channels --> Core
  Core --> Workspace

  AppServer["AppServer<br/>(JSON-RPC over stdio/WebSocket)"]
  Core -.projects.- AppServer
  AppServer --> Desktop["Desktop / TUI / external clients"]
  AppServer --> SDKs["SDKs (Python, TypeScript)"]
```

## Module Types & Discovery

Every interaction mode implements `IDotCraftModule` and is discovered by the `DotCraft.Gen` source generator. Three module kinds:

| Type | Description | Examples |
|---|---|---|
| **Host** | Standalone entry that owns the process | CLI (`DotCraft.App`, priority `0`) |
| **Channel** | Managed by Gateway | ACP, Automations, QQ / WeCom / Feishu / Telegram / WeChat |
| **Tool-only** | Provides tools without an entry point | Auxiliary toolsets |

> **Host priority**: When multiple Hosts are enabled, the lower-priority Host owns the process; if none are enabled, Gateway owns the process and loads enabled Channels.

## Session Core

`specs/session-core.md` is the authoritative spec: `Thread → Turn → Item` and `ISessionService` as the central API:

- Thread lifecycle (`thread/start`, `thread/resume`, `thread/list`, `thread/read`, `thread/archive`, `thread/delete`, `thread/pause`, `thread/setMode`)
- Input submission (`turn/start`, `turn/interrupt`)
- Streaming event subscription (`item/agentMessage/delta`, `turn/completed`, ...)
- Approval flow (`item/approval/request` ↔ JSON-RPC responses)

| Entry | Uses ISessionService |
|---|---|
| CLI, ACP, Automations, external channel adapters | Yes (persistent threads + cross-entry sharing) |

## AppServer

`specs/appserver-protocol.md` projects `ISessionService` as JSON-RPC 2.0:

- **Transport**: stdio (JSONL, one message per line) and WebSocket (one message per frame)
- **Clients**: TUI, Desktop, ACP, external channel adapters, SDKs (Python / TypeScript)
- **Auth**: WebSocket `?token=` query string ([details](./appserver.md))

See [AppServer Protocol](./appserver-protocol.md) and [AppServer Mode](./appserver.md).

## Hub

Each user has one [Hub](./hub.md) on the machine. Hub starts/reuses one AppServer per workspace and maintains discovery info and locks under `~/.craft/hub/`. Desktop and TUI use Hub by default. Bypass Hub for remote, CI, bots, or protocol debugging — use [AppServer Mode](./appserver.md).

## Agents

`DotCraft.Core.Agents` builds on `Microsoft.Extensions.AI`:

- Agent factories and runners
- Tool injection and filtering (`EnabledTools`, SubAgent role allow/deny list, Hook interception)
- SubAgents: `native` and `cli-oneshot` runtimes (see [SubAgents](../features/subagents.md))
- Context compaction pipeline (auto + reactive + microcompaction, via `Compaction.*`)

## Configuration

DotCraft layers two configs:

| Layer | Path | Purpose |
|---|---|---|
| Global | `~/.craft/config.json` | Provider credentials, endpoints, personal preferences |
| Workspace | `<workspace>/.craft/config.json` | Model selection, entry switches, automations, security |

Modules declare config sections via `[ConfigSection("Key")]` inside their assembly. The source generator collects them. Adding a new module integrates it into the merged schema automatically.

Full field reference: [Configuration Reference](./configuration.md). How fields take effect (immediate / subsystem restart / AppServer restart): [Settings Lifecycle](./settings-lifecycle.md).

## Repository Layout

- Core and app: `src/DotCraft.Core/`, `src/DotCraft.App/`, `src/DotCraft.Gen/`
- Feature modules: `src/DotCraft.{Unity,Automations,...}/`
- TypeScript channels: `sdk/typescript/packages/channel-{qq,wecom,feishu,weixin,telegram}/`
- Specs and tests: `specs/`, `tests/`
- SDKs and clients: `sdk/`, `tui/`, `desktop/`
- Docs and examples: `docs/` (English root, Chinese under `docs/zh/`), `samples/`

## Protocol Specs

| Spec | Description |
|---|---|
| [Session Core](https://github.com/DotHarness/dotcraft/blob/master/specs/session-core.md) | Thread/Turn/Item model and ISessionService |
| [AppServer Protocol](https://github.com/DotHarness/dotcraft/blob/master/specs/appserver-protocol.md) | JSON-RPC over stdio/WebSocket |
| [Hub Architecture](https://github.com/DotHarness/dotcraft/blob/master/specs/hub-architecture.md) | Local Hub design |
| [External Channel Adapter](https://github.com/DotHarness/dotcraft/blob/master/specs/external-channel-adapter.md) | External channel adapter protocol |
| [Plugin Architecture](https://github.com/DotHarness/dotcraft/blob/master/specs/plugin-architecture.md) | Plugin manifest and lifecycle |

## Related

- [Configuration Reference](./configuration.md)
- [AppServer Protocol](./appserver-protocol.md) / [AppServer Mode](./appserver.md)
- [Hub Protocol](./hub-protocol.md) / [Hub Local Coordination](./hub.md)
- [Python SDK](./sdk-python.md) · [TypeScript SDK](./sdk-typescript.md)
