# singhcoder/claude-code architecture

> Architecture diagram of the GitHub repository singhcoder/claude-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/singhcoder/claude-code
- Repository: https://github.com/singhcoder/claude-code

## Overview

1. **What this repository is**
   This is a Python-first porting workspace, not a finished product runtime. The active code in `src/` exists to model, inspect, and compare a rewritten Claude Code-style harness against archived snapshots and a remembered subsystem map.

2. **Top-level execution boundary**
   The main user-facing entrypoint is `src/main.py`, which exposes a small CLI for reporting on the workspace: `summary`, `manifest`, `subsystems`, `commands`, `tools`, and `parity-audit`. That CLI is the primary boundary between the repository’s internal metadata model and human/operator inspection.

3. **Core data model layer**
   `src/models.py` holds the structured representation of the porting workspace, including subsystem, module, and backlog/state concepts. `src/port_manifest.py` is the authoritative view of the current Python tree shape, and the query layer renders that into human-readable output.

4. **Query and reporting flow**
   `src/query_engine.py` and the legacy-named `src/QueryEngine.py` provide the summary/rendering side of the system. They consume the manifest/model data and produce the status views used by the CLI, so the data flow is: workspace metadata → manifest/models → query engine → CLI output.

5. **Command and tool inventories**
   `src/commands.py` and `src/tools.py` capture the ported inventories for command and tool surfaces. These are not just helpers; they are first-class architectural artifacts because the repo is tracking parity of agent-facing capabilities, not only source files.

6. **Subsystem namespace mirroring**
   The many packages under `src/`—for example `assistant`, `bootstrap`, `bridge`, `coordinator`, `hooks`, `keybindings`, `remote`, `server`, `skills`, `state`, `upstreamproxy`, `vim`, and `voice`—represent the archived system’s major subsystems. In the current repository they function primarily as a structural mirror and future implementation surface, with the important architectural point being that the tree is organized by subsystem boundaries rather than by a single monolithic app layer.

7. **Reference and parity data**
   `src/reference_data/` is the static snapshot layer used to compare the current Python workspace against the archived source shape. It contains subsystem inventories, command/tool snapshots, and archive-surface snapshots, which makes parity checking a data-driven operation rather than a manual inspection task.

8. **Verification and audit path**
   `tests/test_porting_workspace.py` validates the workspace shape, while `python3 -m src.main parity-audit` checks the current tree against the stored reference data. This creates a second control plane: runtime code for reporting, and test/audit code for parity verification.

9. **Support modules around the core**
   Modules such as `task.py`, `tasks.py`, `history.py`, `context.py`, `runtime.py`, `cost_tracker.py`, `costHook.py`, `dialogLaunchers.py`, and `interactiveHelpers.py` suggest the repository is also preparing agent-session state, execution context, and interaction utilities. These are support boundaries around the core metadata/query system rather than a conventional application service stack.

10. **Overall architecture**
   The repository is organized as a porting harness: a small Python CLI and query layer sit on top of structured manifests, inventories, and snapshots, while a wide set of subsystem packages preserves the original system’s architectural partitioning. For a diagram, the key boxes are: CLI entrypoint, manifest/model/query core, reference-data parity store, subsystem namespace, and test/audit verification loop.

Main entry points: [`src/port_manifest.py`](https://github.com/singhcoder/claude-code/blob/main/src/port_manifest.py) (Manifest), [`src/reference_data`](https://github.com/singhcoder/claude-code/tree/main/src/reference_data) (Snapshots), [`src/main.py`](https://github.com/singhcoder/claude-code/blob/main/src/main.py) (CLI), [`src/parity_audit.py`](https://github.com/singhcoder/claude-code/blob/main/src/parity_audit.py) (Parity audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core reporting"]
  node_src_main["CLI<br/>entrypoint<br/>[main.py]"]
  node_src_query_engine["Query engine<br/>reporting-core<br/>[query_engine.py]"]
  node_src_query_engine_legacy["Legacy engine<br/>compat alias<br/>[QueryEngine.py]"]
  node_src_models["Models<br/>workspace-model<br/>[models.py]"]
  node_src_port_manifest["Manifest<br/>[port_manifest.py]"]
  node_src_commands["Commands<br/>inventory<br/>[commands.py]"]
  node_src_tools["Tools<br/>inventory<br/>[tools.py]"]
end

subgraph group_parity["Parity data"]
  node_src_reference_data[("Snapshots<br/>snapshot-store")]
end

subgraph group_mirror["Subsystem mirror"]
  node_src_assistant["assistant<br/>subsystem pkg"]
  node_src_bootstrap["bootstrap<br/>subsystem pkg"]
  node_src_bridge["bridge<br/>subsystem pkg"]
  node_src_coordinator["coordinator<br/>subsystem pkg"]
  node_src_hooks["hooks<br/>subsystem pkg"]
  node_src_server["server<br/>subsystem pkg"]
  node_src_skills["skills<br/>subsystem pkg"]
  node_src_state["state<br/>subsystem pkg"]
  node_src_upstreamproxy["upstreamproxy<br/>subsystem pkg"]
end

subgraph group_verify["Verification"]
  node_src_parity_audit["Parity audit<br/>[parity_audit.py]"]
  node_tests_porting_workspace["Workspace test"]
end

node_src_main -->|"uses"| node_src_query_engine
node_src_main -->|"reads"| node_src_port_manifest
node_src_main -->|"reports"| node_src_commands
node_src_main -->|"reports"| node_src_tools
node_src_main -->|"invokes"| node_src_parity_audit
node_src_query_engine -->|"consumes"| node_src_models
node_src_query_engine -->|"consumes"| node_src_port_manifest
node_src_query_engine -.->|"mirrors"| node_src_query_engine_legacy
node_src_port_manifest -->|"includes"| node_src_assistant
node_src_port_manifest -->|"includes"| node_src_bootstrap
node_src_port_manifest -->|"includes"| node_src_bridge
node_src_port_manifest -->|"includes"| node_src_coordinator
node_src_port_manifest -->|"includes"| node_src_hooks
node_src_port_manifest -->|"includes"| node_src_server
node_src_port_manifest -->|"includes"| node_src_skills
node_src_port_manifest -->|"includes"| node_src_state
node_src_port_manifest -->|"includes"| node_src_upstreamproxy
node_src_reference_data -->|"snapshots"| node_src_commands
node_src_reference_data -->|"snapshots"| node_src_tools
node_src_reference_data -->|"drives"| node_src_parity_audit
node_src_parity_audit -->|"compares"| node_src_port_manifest
node_src_parity_audit -->|"compares"| node_src_models
node_tests_porting_workspace -->|"validates"| node_src_port_manifest
node_tests_porting_workspace -->|"covers"| node_src_parity_audit
node_src_reference_data -.->|"maps"| node_src_assistant
node_src_reference_data -.->|"maps"| node_src_bootstrap
node_src_reference_data -.->|"maps"| node_src_bridge
node_src_reference_data -.->|"maps"| node_src_coordinator
node_src_reference_data -.->|"maps"| node_src_hooks
node_src_reference_data -.->|"maps"| node_src_server
node_src_reference_data -.->|"maps"| node_src_skills
node_src_reference_data -.->|"maps"| node_src_state
node_src_reference_data -.->|"maps"| node_src_upstreamproxy

click node_src_main "https://github.com/singhcoder/claude-code/blob/main/src/main.py"
click node_src_query_engine "https://github.com/singhcoder/claude-code/blob/main/src/query_engine.py"
click node_src_query_engine_legacy "https://github.com/singhcoder/claude-code/blob/main/src/QueryEngine.py"
click node_src_models "https://github.com/singhcoder/claude-code/blob/main/src/models.py"
click node_src_port_manifest "https://github.com/singhcoder/claude-code/blob/main/src/port_manifest.py"
click node_src_commands "https://github.com/singhcoder/claude-code/blob/main/src/commands.py"
click node_src_tools "https://github.com/singhcoder/claude-code/blob/main/src/tools.py"
click node_src_parity_audit "https://github.com/singhcoder/claude-code/blob/main/src/parity_audit.py"
click node_src_reference_data "https://github.com/singhcoder/claude-code/tree/main/src/reference_data"
click node_tests_porting_workspace "https://github.com/singhcoder/claude-code/blob/main/tests/test_porting_workspace.py"
click node_src_assistant "https://github.com/singhcoder/claude-code/tree/main/src/assistant"
click node_src_bootstrap "https://github.com/singhcoder/claude-code/tree/main/src/bootstrap"
click node_src_bridge "https://github.com/singhcoder/claude-code/tree/main/src/bridge"
click node_src_coordinator "https://github.com/singhcoder/claude-code/tree/main/src/coordinator"
click node_src_hooks "https://github.com/singhcoder/claude-code/tree/main/src/hooks"
click node_src_server "https://github.com/singhcoder/claude-code/tree/main/src/server"
click node_src_skills "https://github.com/singhcoder/claude-code/tree/main/src/skills"
click node_src_state "https://github.com/singhcoder/claude-code/tree/main/src/state"
click node_src_upstreamproxy "https://github.com/singhcoder/claude-code/tree/main/src/upstreamproxy"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_main,node_src_query_engine,node_src_query_engine_legacy,node_src_models,node_src_port_manifest,node_src_commands,node_src_tools toneBlue
class node_src_reference_data toneAmber
class node_src_assistant,node_src_bootstrap,node_src_bridge,node_src_coordinator,node_src_hooks,node_src_server,node_src_skills,node_src_state,node_src_upstreamproxy toneMint
class node_src_parity_audit,node_tests_porting_workspace toneRose
```

## Components

### Core reporting

CLI, manifest, models, and query/reporting pipeline.

- [CLI](https://github.com/singhcoder/claude-code/blob/main/src/main.py): entrypoint · User-facing reporting entrypoint with summary and audit commands. · `src/main.py`
- [Query engine](https://github.com/singhcoder/claude-code/blob/main/src/query_engine.py): reporting-core · Renders workspace metadata into status and inspection views. · `src/query_engine.py`
- [Legacy engine](https://github.com/singhcoder/claude-code/blob/main/src/QueryEngine.py): compat alias · Legacy-named query engine kept alongside the modern module. · `src/QueryEngine.py`
- [Models](https://github.com/singhcoder/claude-code/blob/main/src/models.py): workspace-model · Structured representation of subsystems, modules, and state. · `src/models.py`
- [Manifest](https://github.com/singhcoder/claude-code/blob/main/src/port_manifest.py): tree-manifest · Authoritative shape of the current Python workspace. · `src/port_manifest.py`
- [Commands](https://github.com/singhcoder/claude-code/blob/main/src/commands.py): inventory · Ported command surface inventory used for parity reporting. · `src/commands.py`
- [Tools](https://github.com/singhcoder/claude-code/blob/main/src/tools.py): inventory · Ported tool surface inventory used for parity reporting. · `src/tools.py`

### Parity data

Static snapshots used for comparison against the current workspace.

- [Snapshots](https://github.com/singhcoder/claude-code/tree/main/src/reference_data): snapshot-store · Static reference data for subsystem, command, and surface comparison. · `src/reference_data`

### Subsystem mirror

Representative subsystem packages that preserve the archived boundary map.

- [assistant](https://github.com/singhcoder/claude-code/tree/main/src/assistant): subsystem pkg · Representative mirrored subsystem package. · `src/assistant`
- [bootstrap](https://github.com/singhcoder/claude-code/tree/main/src/bootstrap): subsystem pkg · Representative mirrored subsystem package. · `src/bootstrap`
- [bridge](https://github.com/singhcoder/claude-code/tree/main/src/bridge): subsystem pkg · Representative mirrored subsystem package. · `src/bridge`
- [coordinator](https://github.com/singhcoder/claude-code/tree/main/src/coordinator): subsystem pkg · Representative mirrored subsystem package. · `src/coordinator`
- [hooks](https://github.com/singhcoder/claude-code/tree/main/src/hooks): subsystem pkg · Representative mirrored subsystem package. · `src/hooks`
- [server](https://github.com/singhcoder/claude-code/tree/main/src/server): subsystem pkg · Representative mirrored subsystem package. · `src/server`
- [skills](https://github.com/singhcoder/claude-code/tree/main/src/skills): subsystem pkg · Representative mirrored subsystem package. · `src/skills`
- [state](https://github.com/singhcoder/claude-code/tree/main/src/state): subsystem pkg · Representative mirrored subsystem package. · `src/state`
- [upstreamproxy](https://github.com/singhcoder/claude-code/tree/main/src/upstreamproxy): subsystem pkg · Representative mirrored subsystem package. · `src/upstreamproxy`

### Verification

Tests and audit path for workspace shape and parity checks.

- [Parity audit](https://github.com/singhcoder/claude-code/blob/main/src/parity_audit.py): audit · Checks the current tree against stored reference data. · `src/parity_audit.py`
- [Workspace test](https://github.com/singhcoder/claude-code/blob/main/tests/test_porting_workspace.py): test · Validates the workspace shape and reporting assumptions. · `tests/test_porting_workspace.py`

## Connections

- CLI → Query engine: uses · CLI renders reporting output through the query layer.
- CLI → Manifest: reads · CLI can report on the workspace manifest.
- CLI → Commands: reports · CLI exposes command inventory views.
- CLI → Tools: reports · CLI exposes tool inventory views.
- CLI → Parity audit: invokes · CLI exposes the parity-audit boundary.
- Query engine → Models: consumes · Reporting is driven by the structured workspace model.
- Query engine → Manifest: consumes · Reporting uses the manifest as the source tree shape.
- Query engine → Legacy engine: mirrors · Legacy and current query engine modules coexist.
- Manifest → assistant: includes · Manifest reflects major subsystem packages.
- Manifest → bootstrap: includes · Manifest reflects major subsystem packages.
- Manifest → bridge: includes · Manifest reflects major subsystem packages.
- Manifest → coordinator: includes · Manifest reflects major subsystem packages.
- Manifest → hooks: includes · Manifest reflects major subsystem packages.
- Manifest → server: includes · Manifest reflects major subsystem packages.
- Manifest → skills: includes · Manifest reflects major subsystem packages.
- Manifest → state: includes · Manifest reflects major subsystem packages.
- Manifest → upstreamproxy: includes · Manifest reflects major subsystem packages.
- Snapshots → Commands: snapshots · Stored snapshots support command parity checks.
- Snapshots → Tools: snapshots · Stored snapshots support tool parity checks.
- Snapshots → Parity audit: drives · Audit logic compares the current tree against snapshots.
- Parity audit → Manifest: compares · Audit checks current tree shape against the manifest.
- Parity audit → Models: compares · Audit uses modeled workspace structure.
- Workspace test → Manifest: validates · Tests verify workspace shape and manifest assumptions.
- Workspace test → Parity audit: covers · Tests cover the parity audit control path.
- Snapshots → assistant: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → bootstrap: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → bridge: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → coordinator: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → hooks: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → server: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → skills: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → state: maps · Subsystem snapshots mirror archived boundaries.
- Snapshots → upstreamproxy: maps · Subsystem snapshots mirror archived boundaries.
