77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
# Architecture overview
|
|
|
|
!!! warning "Recovered source"
|
|
Paths refer to `src/` in this repository. Line-level accuracy is best-effort from the source map reconstruction.
|
|
|
|
## High-level flow
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph entry [Entry]
|
|
mainTsx[main.tsx]
|
|
end
|
|
subgraph modes [Modes]
|
|
repl[REPL.tsx]
|
|
print[cli/print.ts]
|
|
assistant[assistant KAIROS gate]
|
|
end
|
|
subgraph core [Core loop]
|
|
queryLoop[query.ts queryLoop]
|
|
qe[QueryEngine.ts]
|
|
toolsReg[tools.ts getTools]
|
|
end
|
|
subgraph services [Services]
|
|
api[services/api]
|
|
mcp[services/mcp]
|
|
compact[services/compact]
|
|
end
|
|
mainTsx --> repl
|
|
mainTsx --> print
|
|
mainTsx -.-> assistant
|
|
repl --> queryLoop
|
|
print --> qe
|
|
queryLoop --> api
|
|
qe --> api
|
|
toolsReg --> mcp
|
|
queryLoop --> compact
|
|
qe --> compact
|
|
```
|
|
|
|
## System design (deeper dives)
|
|
|
|
| Topic | Page |
|
|
| --------------------------------- | ----------------------------------------------------------------- |
|
|
| Layering and dependency direction | [Architectural layers](system-design/layers.md) |
|
|
| State, messages, and persistence | [State and data flow](system-design/state-and-data-flow.md) |
|
|
| Trust, permissions, MCP policy | [Security and trust model](system-design/security-trust-model.md) |
|
|
|
|
## Short orientation
|
|
|
|
- **Entry** — `main.tsx`: Commander CLI, `preAction` (trust, settings, telemetry gates), side-effect imports (profiler, MDM, keychain prefetch).
|
|
- **Interactive host** — `replLauncher.tsx`, `screens/REPL.tsx`, `utils/queueProcessor.ts`.
|
|
- **Headless host** — `cli/print.ts`, `QueryEngine.ts`, `cli/structuredIO.ts`.
|
|
- **Tools & MCP** — `tools.ts`, `tools/*`, `services/mcp/`, `services/tools/`.
|
|
- **IDE / OS** — `bridge/`, `utils/deepLink/`, `utils/claudeInChrome/`.
|
|
|
|
## Key files (quick index)
|
|
|
|
| Path | Role |
|
|
| -------------------------------------------------- | ------------------------------------------- |
|
|
| `main.tsx` | CLI entry, global options, `preAction` |
|
|
| `screens/REPL.tsx` | Interactive session core |
|
|
| `query.ts` | Streaming query loop, tool round-trips |
|
|
| `QueryEngine.ts` | Headless query submission |
|
|
| `cli/print.ts` | Print / stream-json / SDK control transport |
|
|
| `tools.ts` / `Tool.ts` | Tool registry and types |
|
|
| `services/api/client.ts`, `services/api/claude.ts` | HTTP / streaming API |
|
|
| `utils/permissions/` | Permission modes and prompts |
|
|
| `services/compact/` | Compaction pipeline |
|
|
| `utils/sessionStart.ts` | Session / setup hooks |
|
|
|
|
## Further reading
|
|
|
|
- [Workflows](workflows.md) — end-to-end sequences.
|
|
- [Official docs map](official-docs-map.md) — product docs ↔ `src/`.
|
|
- [Reference](reference/cli-entry.md) — subsystem reference pages.
|
|
- [Glossary](appendix/glossary.md).
|