# instructkr/clawd-code architecture

> Architecture diagram of the GitHub repository instructkr/clawd-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/instructkr/clawd-code
- Repository: https://github.com/instructkr/clawd-code

## Overview

1. **What this repository is**
   - This is a **Python-first porting workspace** for a harness/agent system, not a full production app.
   - The tracked source is centered on **describing and verifying a rewrite**: generating manifests, summaries, and parity checks against archived reference data.

2. **Primary execution path**
   - The main user-facing entrypoint is `src/main.py`.
   - It appears to expose CLI commands such as **summary**, **manifest**, **subsystems**, **commands**, **tools**, and **parity-audit**.
   - That makes the repository architecture “CLI-driven analysis/inspection” rather than a long-running server.

3. **Core data model layer**
   - `src/models.py` holds the main structured types for the porting workspace, including concepts like **subsystems**, **modules**, and **backlog/state**.
   - This is the shared schema layer used by the manifest/query tooling to describe the current workspace consistently.

4. **Workspace inventory and manifest generation**
   - `src/port_manifest.py` is the source of truth for the **current Python workspace structure**.
   - It likely scans or enumerates the active `src/` tree and produces the manifest consumed by CLI commands and tests.
   - This is the boundary between “actual code on disk” and “human-readable architecture inventory.”

5. **Query/rendering layer**
   - `src/query_engine.py` is responsible for turning the workspace inventory into **summaries and reports**.
   - `src/query.py` and `src/QueryEngine.py` suggest a compatibility/transition boundary around query functionality.
   - In architectural terms, this is the read-only analytics layer above the manifest/model layer.

6. **Command and tool cataloging**
   - `src/commands.py` and `src/tools.py` define the Python-side **command metadata** and **tool metadata**.
   - These mirror archived command/tool inventories and are exposed through the CLI for inspection.
   - The repo’s “behavior” is mostly represented as catalog data and summaries, not as many executable subsystems yet.

7. **Parity and comparison flow**
   - `src/parity_audit.py` is the validation boundary that compares the Python port against local reference snapshots.
   - `src/reference_data/` contains archived JSON snapshots for subsystems, commands, tools, and archive surfaces.
   - The flow is: **current workspace manifest → compare with reference snapshots → report parity gaps**.

8. **Package layout as architecture markers**
   - The many top-level packages under `src/` (`assistant`, `bridge`, `cli`, `coordinator`, `hooks`, `server`, `skills`, `state`, `voice`, etc.) mostly function as **namespace markers** for the porting effort.
   - Their presence mirrors the original system’s subsystem map, even though the Python implementation is still incomplete.
   - This matters for architecture diagrams because the project is organized around **subsystem boundaries**, not a single monolith.

9. **Runtime and interaction model**
   - The project is run as a **local Python module/CLI** (`python3 -m src.main ...`).
   - There is no evidence of a networked backend being the primary runtime; instead, the runtime is local and inspection-oriented.
   - `src/runtime.py`, `src/entrypoints/`, and `src/bootstrap/` indicate future or partial support for broader execution modes.

10. **Supporting state and workflow modules**
   - Modules like `history.py`, `context.py`, `task.py`, `tasks.py`, `coordinator/`, `buddy/`, and `assistant/` suggest the intended architecture of an **agent/task orchestration system**.
   - In the current repo state, these are better understood as **port targets** and architectural placeholders than as fully wired runtime paths.

11. **Tests and verification**
   - `tests/test_porting_workspace.py` verifies the current Python workspace behavior.
   - Testing appears focused on **structure/parity correctness** rather than end-to-end agent execution.

12. **Important architectural boundary**
   - The biggest boundary is between:
     - **active Python porting workspace** in `src/`
     - **reference snapshots** in `src/reference_data/`
   - The repo’s purpose is to keep those two views aligned enough to measure rewrite progress.

13. **What to draw in an architecture diagram**
   - Show a central **CLI entrypoint** feeding a **manifest/query layer**, which reads the **workspace tree** and the **reference snapshots**, then produces summaries, inventories, and parity reports.
   - Surround that with the named subsystem namespaces as the **intended modular architecture** of the larger harness.
   - Treat external services as absent from the current core architecture; the repo is mainly **local analysis, metadata, and parity tooling**.

Main entry points: [`src/main.py`](https://github.com/instructkr/clawd-code/blob/main/src/main.py) (Main CLI), [`src/query_engine.py`](https://github.com/instructkr/clawd-code/blob/main/src/query_engine.py) (Query engine), [`src/port_manifest.py`](https://github.com/instructkr/clawd-code/blob/main/src/port_manifest.py) (Manifest), [`src/models.py`](https://github.com/instructkr/clawd-code/blob/main/src/models.py) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli_reports["CLI & reports"]
  node_src_main["Main CLI<br/>entrypoint<br/>[main.py]"]
end

subgraph group_workspace_core["Workspace core"]
  node_src_port_manifest["Manifest<br/>inventory generator<br/>[port_manifest.py]"]
  node_src_query_engine["Query engine<br/>report engine<br/>[query_engine.py]"]
  node_src_query["Query API<br/>compat layer<br/>[query.py]"]
  node_src_queryengine_legacy["Legacy query<br/>compat layer<br/>[QueryEngine.py]"]
  node_src_models[("Models<br/>schema layer<br/>[models.py]")]
  node_src_commands["Commands<br/>catalog<br/>[commands.py]"]
  node_src_tools["Tools<br/>catalog<br/>[tools.py]"]
end

subgraph group_parity_refs["Parity refs"]
  node_src_parity_audit["Parity audit<br/>validator<br/>[parity_audit.py]"]
  node_src_reference_data[("Reference data<br/>snapshots")]
end

subgraph group_port_namespaces["Ported namespaces"]
  node_src_coordinator["Coordinator<br/>orchestration namespace"]
  node_src_assistant["Assistant<br/>agent namespace"]
  node_src_bridge["Bridge<br/>integration namespace"]
  node_src_server["Server<br/>service namespace"]
  node_src_skills["Skills<br/>capability namespace"]
  node_src_state["State"]
  node_src_voice["Voice<br/>interaction namespace"]
end

subgraph group_runtime_scaffold["Runtime scaffold"]
  node_src_runtime["Runtime<br/>execution scaffold<br/>[runtime.py]"]
end

node_src_main -->|"builds"| node_src_port_manifest
node_src_main -->|"reports"| node_src_query_engine
node_src_main -->|"audits"| node_src_parity_audit
node_src_main -->|"lists"| node_src_commands
node_src_main -->|"lists"| node_src_tools
node_src_main -->|"loads"| node_src_runtime
node_src_port_manifest -->|"uses"| node_src_models
node_src_query_engine -->|"reads"| node_src_models
node_src_query_engine -->|"analyzes"| node_src_port_manifest
node_src_query_engine -->|"compares"| node_src_reference_data
node_src_query -->|"wraps"| node_src_query_engine
node_src_queryengine_legacy -->|"aliases"| node_src_query_engine
node_src_parity_audit -->|"verifies"| node_src_port_manifest
node_src_parity_audit -->|"checks"| node_src_reference_data
node_src_commands -->|"serializes"| node_src_models
node_src_tools -->|"serializes"| node_src_models
node_src_runtime -->|"orchestrates"| node_src_coordinator
node_src_coordinator -->|"drives"| node_src_assistant
node_src_coordinator -->|"persists"| node_src_state
node_src_assistant -->|"invokes"| node_src_skills
node_src_assistant -->|"surfaces"| node_src_voice
node_src_bridge -->|"connects"| node_src_server

click node_src_main "https://github.com/instructkr/clawd-code/blob/main/src/main.py"
click node_src_port_manifest "https://github.com/instructkr/clawd-code/blob/main/src/port_manifest.py"
click node_src_query_engine "https://github.com/instructkr/clawd-code/blob/main/src/query_engine.py"
click node_src_query "https://github.com/instructkr/clawd-code/blob/main/src/query.py"
click node_src_queryengine_legacy "https://github.com/instructkr/clawd-code/blob/main/src/QueryEngine.py"
click node_src_models "https://github.com/instructkr/clawd-code/blob/main/src/models.py"
click node_src_commands "https://github.com/instructkr/clawd-code/blob/main/src/commands.py"
click node_src_tools "https://github.com/instructkr/clawd-code/blob/main/src/tools.py"
click node_src_parity_audit "https://github.com/instructkr/clawd-code/blob/main/src/parity_audit.py"
click node_src_reference_data "https://github.com/instructkr/clawd-code/tree/main/src/reference_data"
click node_src_runtime "https://github.com/instructkr/clawd-code/blob/main/src/runtime.py"
click node_src_coordinator "https://github.com/instructkr/clawd-code/tree/main/src/coordinator"
click node_src_assistant "https://github.com/instructkr/clawd-code/tree/main/src/assistant"
click node_src_bridge "https://github.com/instructkr/clawd-code/tree/main/src/bridge"
click node_src_server "https://github.com/instructkr/clawd-code/tree/main/src/server"
click node_src_skills "https://github.com/instructkr/clawd-code/tree/main/src/skills"
click node_src_state "https://github.com/instructkr/clawd-code/tree/main/src/state"
click node_src_voice "https://github.com/instructkr/clawd-code/tree/main/src/voice"

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 toneBlue
class node_src_port_manifest,node_src_query_engine,node_src_query,node_src_queryengine_legacy,node_src_models,node_src_commands,node_src_tools toneAmber
class node_src_parity_audit,node_src_reference_data toneMint
class node_src_coordinator,node_src_assistant,node_src_bridge,node_src_server,node_src_skills,node_src_state,node_src_voice toneRose
class node_src_runtime toneIndigo
```

## Components

### CLI & reports

Entry points and read-only inspection commands.

- [Main CLI](https://github.com/instructkr/clawd-code/blob/main/src/main.py): entrypoint · Primary command-line entrypoint for summaries, manifests, and audits. · `src/main.py`

### Workspace core

Shared models and inventory generation for the Python port.

- [Manifest](https://github.com/instructkr/clawd-code/blob/main/src/port_manifest.py): inventory generator · Builds the current workspace manifest from the active source tree. · `src/port_manifest.py`
- [Query engine](https://github.com/instructkr/clawd-code/blob/main/src/query_engine.py): report engine · Turns manifest and model data into summaries and inspection reports. · `src/query_engine.py`
- [Query API](https://github.com/instructkr/clawd-code/blob/main/src/query.py): compat layer · Compatibility boundary around query functionality. · `src/query.py`
- [Legacy query](https://github.com/instructkr/clawd-code/blob/main/src/QueryEngine.py): compat layer · Legacy module name kept during transition. · `src/QueryEngine.py`
- [Models](https://github.com/instructkr/clawd-code/blob/main/src/models.py): schema layer · Shared structured types for subsystems, modules, and workspace state. · `src/models.py`
- [Commands](https://github.com/instructkr/clawd-code/blob/main/src/commands.py): catalog · Command metadata exposed through the CLI and parity checks. · `src/commands.py`
- [Tools](https://github.com/instructkr/clawd-code/blob/main/src/tools.py): catalog · Tool metadata mirrored from archived inventories. · `src/tools.py`

### Parity refs

Archived snapshots used to compare rewrite progress.

- [Parity audit](https://github.com/instructkr/clawd-code/blob/main/src/parity_audit.py): validator · Compares the Python port against archived reference snapshots. · `src/parity_audit.py`
- [Reference data](https://github.com/instructkr/clawd-code/tree/main/src/reference_data): snapshots · Archived JSON snapshots for subsystems, commands, tools, and archive surfaces. · `src/reference_data`

### Ported namespaces

Major subsystem namespaces preserved as architectural boundaries.

- [Coordinator](https://github.com/instructkr/clawd-code/tree/main/src/coordinator): orchestration namespace · Port target for task and agent coordination logic. · `src/coordinator`
- [Assistant](https://github.com/instructkr/clawd-code/tree/main/src/assistant): agent namespace · Port target for assistant behavior and agent-facing flows. · `src/assistant`
- [Bridge](https://github.com/instructkr/clawd-code/tree/main/src/bridge): integration namespace · Namespace for integration and boundary-adapter logic. · `src/bridge`
- [Server](https://github.com/instructkr/clawd-code/tree/main/src/server): service namespace · Namespace marker for server-side components in the original system. · `src/server`
- [Skills](https://github.com/instructkr/clawd-code/tree/main/src/skills): capability namespace · Namespace for reusable agent capabilities and skill definitions. · `src/skills`
- [State](https://github.com/instructkr/clawd-code/tree/main/src/state): state namespace · Namespace for shared state and workflow context. · `src/state`
- [Voice](https://github.com/instructkr/clawd-code/tree/main/src/voice): interaction namespace · Namespace for voice or interactive surface support. · `src/voice`

### Runtime scaffold

Partial execution and orchestration layers for the broader agent system.

- [Runtime](https://github.com/instructkr/clawd-code/blob/main/src/runtime.py): execution scaffold · Local runtime and future execution-mode support. · `src/runtime.py`

## Connections

- Main CLI → Manifest: builds · CLI commands surface the current workspace inventory.
- Main CLI → Query engine: reports · Main CLI invokes summary and inspection queries.
- Main CLI → Parity audit: audits · CLI exposes parity checking against reference snapshots.
- Main CLI → Commands: lists · CLI can inspect command catalog metadata.
- Main CLI → Tools: lists · CLI can inspect tool catalog metadata.
- Main CLI → Runtime: loads · Main entrypoint sits above the local runtime scaffold.
- Manifest → Models: uses · Manifest generation is shaped by the shared workspace schema.
- Query engine → Models: reads · Reports are rendered from structured workspace models.
- Query engine → Manifest: analyzes · Query layer consumes the current manifest snapshot.
- Query engine → Reference data: compares · Query/reporting can be aligned with archived reference data.
- Query API → Query engine: wraps · Compatibility module forwards to the newer query engine.
- Legacy query → Query engine: aliases · Legacy module name points at the current query implementation.
- Parity audit → Manifest: verifies · Parity checks start from the current workspace manifest.
- Parity audit → Reference data: checks · Validator compares against archived snapshots.
- Commands → Models: serializes · Command inventory is represented through the shared schema.
- Tools → Models: serializes · Tool inventory is represented through the shared schema.
- Runtime → Coordinator: orchestrates · Runtime scaffold points toward coordination logic.
- Coordinator → Assistant: drives · Coordination boundary leads into assistant behavior.
- Coordinator → State: persists · Coordinator depends on shared state for workflow progress.
- Assistant → Skills: invokes · Assistant behavior is composed from skills/capabilities.
- Assistant → Voice: surfaces · Assistant may expose voice or interactive surfaces.
- Bridge → Server: connects · Bridge namespace marks integration to server-side surfaces.
