add developer docs
This commit is contained in:
Osman Mehmood
68
docs-site/docs/system-design/layers.md
Normal file
68
docs-site/docs/system-design/layers.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Architectural layers
|
||||
|
||||
!!! warning "Recovered proprietary source"
|
||||
Descriptions are for **study** of the `src/` mirror only. This is not an open-source distribution of Claude Code.
|
||||
|
||||
The Claude Code CLI is organized as **downward dependencies**: the shell and UI call into the query core and services; core logic does not depend on React/Ink components for correctness (headless paths prove that).
|
||||
|
||||
## Layer stack (conceptual)
|
||||
|
||||
| Layer | Responsibility | Primary `src/` locations |
|
||||
| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
|
||||
| **CLI shell** | argv parsing, global flags, subcommands, `preAction` startup | `main.tsx`, `commands/`, `cli/handlers/` |
|
||||
| **Session host** | Interactive TUI vs structured print/SDK transport | `replLauncher.tsx`, `screens/REPL.tsx`, `cli/print.ts`, `cli/structuredIO.ts` |
|
||||
| **Query core** | Turn loop, streaming, tool round-trips, context assembly | `query.ts`, `QueryEngine.ts`, `utils/processUserInput/` |
|
||||
| **Transport** | Anthropic (and provider) HTTP/streaming | `services/api/` |
|
||||
| **Tooling** | Registry, execution, hooks | `tools.ts`, `Tool.ts`, `tools/*`, `services/tools/` |
|
||||
| **Integrations** | MCP, LSP, OAuth, IDE bridge | `services/mcp/`, `services/lsp/`, `services/oauth/`, `bridge/` |
|
||||
| **Policy & persistence** | Settings, compaction, session storage, telemetry | `utils/settings/`, `services/compact/`, `utils/sessionStorage.ts`, `services/analytics/` |
|
||||
|
||||
## Dependency direction
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph presentation [Presentation]
|
||||
Main[main.tsx]
|
||||
REPL[REPL.tsx]
|
||||
Print[cli/print.ts]
|
||||
end
|
||||
subgraph domain [Domain_core]
|
||||
Query[query.ts]
|
||||
QE[QueryEngine.ts]
|
||||
end
|
||||
subgraph ports [Ports]
|
||||
API[services/api]
|
||||
Tools[tools plus services/tools]
|
||||
MCP[services/mcp]
|
||||
end
|
||||
subgraph infra [Infrastructure]
|
||||
Settings[utils/settings]
|
||||
Compact[services/compact]
|
||||
Store[sessionStorage]
|
||||
end
|
||||
Main --> REPL
|
||||
Main --> Print
|
||||
REPL --> Query
|
||||
Print --> QE
|
||||
Query --> API
|
||||
Query --> Tools
|
||||
QE --> API
|
||||
QE --> Tools
|
||||
Tools --> MCP
|
||||
Query --> Compact
|
||||
QE --> Compact
|
||||
Query --> Settings
|
||||
Main --> Settings
|
||||
```
|
||||
|
||||
**Rule of thumb:** `components/` and `ink/` sit under the REPL branch; `cli/print.ts` bypasses most of that stack but still shares `QueryEngine`, tools, API, and compaction.
|
||||
|
||||
## Feature gates
|
||||
|
||||
Some “layers” exist only in certain shipping builds: `assistant/` (KAIROS), `coordinator/` (`COORDINATOR_MODE`), voice (`VOICE_MODE`). See [Bun bundle and feature flags](../developer/bun-bundle-and-feature-flags.md).
|
||||
|
||||
## See also
|
||||
|
||||
- [State and data flow](state-and-data-flow.md)
|
||||
- [Security and trust model](security-trust-model.md)
|
||||
- [Architecture overview](../architecture.md)
|
||||
60
docs-site/docs/system-design/security-trust-model.md
Normal file
60
docs-site/docs/system-design/security-trust-model.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Security and trust model
|
||||
|
||||
!!! warning "Recovered proprietary source"
|
||||
This page summarizes **code structure**, not a formal security audit. Follow [official Security](https://code.claude.com/docs/en/security) and [Permissions](https://code.claude.com/docs/en/permissions) guidance for the product.
|
||||
|
||||
## Trust and workspace
|
||||
|
||||
Before destructive work runs, startup paths in `main.tsx` consult trust and workspace state (global config helpers under `utils/config.ts`, managed env under `utils/managedEnv.ts`). The intent is to avoid applying repo-supplied config or hooks until the user has acknowledged risk—public discussion of past ordering bugs is summarized in vendor advisories; always run an **up-to-date** official Claude Code build for production use.
|
||||
|
||||
## Permission modes
|
||||
|
||||
`utils/permissions/` defines modes (manual approval, auto with classifiers, plan-only variants, etc.). `permissionSetup.ts` and related modules:
|
||||
|
||||
- Parse CLI flags (`--permission-mode`, internal aliases).
|
||||
- Strip or gate “dangerous” capabilities when using auto mode.
|
||||
- Feed **always-allow** tool lists into `toolPermissionContext`.
|
||||
|
||||
User-facing reference: [Permission modes](https://code.claude.com/docs/en/permission-modes).
|
||||
|
||||
## Bash and sandboxing
|
||||
|
||||
Shell execution flows through `utils/shell/` (bash and PowerShell providers, output limits, read-only validation) and `tools/BashTool/`. Enterprise and product docs describe [Sandboxing](https://code.claude.com/docs/en/sandboxing) behavior; the source tree implements isolation and validation at the tool layer.
|
||||
|
||||
## MCP and enterprise policy
|
||||
|
||||
- **Config** — `services/mcp/config.ts` parses MCP server lists, env expansion, deduplication, and enterprise allowlists.
|
||||
- **Channels** — `services/mcp/channelAllowlist.ts` and related modules gate inbound push notifications.
|
||||
|
||||
Official: [MCP](https://code.claude.com/docs/en/mcp), [Channels](https://code.claude.com/docs/en/channels).
|
||||
|
||||
## Hooks
|
||||
|
||||
User-defined hooks (session start, post-tool, etc.) are wired through `utils/sessionStart.ts` and related runners; they execute shell commands with the privileges of the CLI process. Treat untrusted projects as **untrusted code** until you understand hook content.
|
||||
|
||||
Official: [Hooks](https://code.claude.com/docs/en/hooks).
|
||||
|
||||
## Trust check order (conceptual)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
start[Process_start]
|
||||
config[Load_safe_config_order]
|
||||
trust[Workspace_trust]
|
||||
perms[Permission_mode_setup]
|
||||
hooks[Session_hooks]
|
||||
tools[Tool_execution]
|
||||
start --> config
|
||||
config --> trust
|
||||
trust --> perms
|
||||
perms --> hooks
|
||||
hooks --> tools
|
||||
```
|
||||
|
||||
Exact ordering evolves by version; correlate with `main.tsx` `preAction` and `entrypoints/init` when reading the mirror.
|
||||
|
||||
## See also
|
||||
|
||||
- [Permissions reference](../reference/permissions.md)
|
||||
- [MCP reference](../reference/mcp.md)
|
||||
- [Reproducibility and limits](../reproducibility.md)
|
||||
50
docs-site/docs/system-design/state-and-data-flow.md
Normal file
50
docs-site/docs/system-design/state-and-data-flow.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# State and data flow
|
||||
|
||||
!!! warning "Recovered proprietary source"
|
||||
For authoritative product behavior, use [official Claude Code docs](https://code.claude.com/docs/en/overview).
|
||||
|
||||
## End-to-end message path (interactive)
|
||||
|
||||
1. **Input** — User text, slash commands, teammate notifications, or task items reach `screens/REPL.tsx`.
|
||||
2. **Queue** — `utils/queueProcessor.ts` serializes or batches commands and calls `executeInput`.
|
||||
3. **Query** — `query.ts` `queryLoop` streams the model, surfaces `tool_use` blocks, and applies permission checks using `toolPermissionContext` from app state.
|
||||
4. **Execution** — `services/tools/` (e.g. `StreamingToolExecutor`, `toolExecution.ts`) dispatches to modules under `tools/*` or MCP-backed tools.
|
||||
5. **Persistence** — Transcript updates, session metadata, and compaction boundaries flow through `utils/sessionStorage.ts`, conversation recovery helpers, and related hooks.
|
||||
|
||||
## State ownership
|
||||
|
||||
| Concern | Typical modules |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| **Global app state** | `state/` (providers, stores such as `AppStateStore.ts`) |
|
||||
| **Context / stats** | `context/` |
|
||||
| **Messages** | `utils/messages.ts`, message types under `types/message` (and generated types) |
|
||||
| **Permissions** | `utils/permissions/`, fields on tool permission context updated from CLI and REPL |
|
||||
| **File / edit history** | Wired through process-user-input and tool hooks (see compaction and attribution utilities) |
|
||||
|
||||
## Simplified sequence (one turn)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as REPL_or_print
|
||||
participant Q as queryLoop
|
||||
participant API as services_api
|
||||
participant Exec as tool_executor
|
||||
participant Store as session_storage
|
||||
UI->>Q: user_or_control_messages
|
||||
Q->>API: stream_completion
|
||||
API-->>Q: assistant_tool_use
|
||||
Q->>Exec: run_tool
|
||||
Exec-->>Q: tool_result
|
||||
Q->>Store: persist_transcript_updates
|
||||
Q-->>UI: render_updates
|
||||
```
|
||||
|
||||
## Headless differences
|
||||
|
||||
In print/SDK paths: `QueryEngine.ts` builds a `processUserInputContext` with `isNonInteractiveSession: true`, streams SDK-style messages, and bridges permission prompts over structured I/O instead of Ink dialogs. The **same** underlying message and tool model is reused.
|
||||
|
||||
## See also
|
||||
|
||||
- [Workflows](../workflows.md)
|
||||
- [Query loop and streaming](../reference/query-engine.md)
|
||||
- [Compaction](../reference/compaction.md)
|
||||
Reference in New Issue
Block a user