# manatunga/quilchoom architecture

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

- Interactive diagram: https://gitdiagram.com/manatunga/quilchoom
- Repository: https://github.com/manatunga/quilchoom

## Overview

Quilchoom is a local-first developer tool that captures Git activity as evidence, distills it into traceable knowledge claims, and generates versioned documentation. The principal workflow runs through the CLI and application services, with a local database for project state and an AI provider for interpretation and generation. The README establishes the domain pipeline; SOURCE INDEX references support the sampled service dependencies. Some subsystems are represented at directory level because their implementation excerpts were not provided.

Main entry points: [`src/quilchoom/cli.py`](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/cli.py) (CLI commands), [`src/quilchoom/application/interpret_history.py`](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/interpret_history.py) (Interpret evidence), [`src/quilchoom/application/generate_document.py`](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/generate_document.py) (Generate documents), [`src/quilchoom/infrastructure/database/repositories.py`](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/database/repositories.py) (Local database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and workflows"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_init["Initialize project"]
  node_capture["Capture commits"]
  node_history["Reconstruct history"]
  node_distill["Interpret evidence"]
  node_scribe["Generate documents"]
  node_status["Project status"]
end

subgraph group_domain["Knowledge lifecycle"]
  node_evidence["Development evidence<br/>[evidence.py]"]
  node_history_data["History entries<br/>[history.py]"]
  node_claims["Knowledge claims<br/>[knowledge_claim.py]"]
  node_documents["Document versions<br/>[document.py]"]
end

subgraph group_storage["Local infrastructure"]
  node_git["Git repository<br/>[repository.py]"]
  node_db[("Local database<br/>[repositories.py]")]
  node_workspace["Local workspace<br/>[workspace.py]"]
  node_terminal["Terminal output / export<br/>[terminal.py]"]
end

subgraph group_ai["AI generation"]
  node_interpreter["LLM interpreter"]
  node_generator["LLM document generator"]
  node_provider["LLM provider adapter<br/>[openai_provider.py]"]
end

node_developer(("Developer"))
node_openai{{"OpenAI service"}}

node_developer -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_init
node_cli -->|"dispatches"| node_capture
node_cli -->|"dispatches"| node_history
node_cli -->|"dispatches"| node_distill
node_cli -->|"dispatches"| node_scribe
node_cli -->|"dispatches"| node_status
node_init -->|"initializes"| node_workspace
node_init -->|"configures"| node_db
node_capture -->|"lists commits"| node_git
node_capture -->|"checks and saves"| node_db
node_capture -->|"records"| node_evidence
node_evidence -->|"reconstructs into"| node_history
node_history -->|"presents"| node_history_data
node_distill -->|"interprets"| node_history_data
node_distill -->|"requests interpretation"| node_interpreter
node_interpreter -->|"requests structured output"| node_provider
node_provider -->|"sends requests"| node_openai
node_distill -->|"loads and saves"| node_db
node_distill -->|"derives"| node_claims
node_claims -->|"trace to"| node_evidence
node_scribe -->|"uses active claims"| node_claims
node_scribe -->|"requests generation"| node_generator
node_generator -->|"requests structured output"| node_provider
node_scribe -->|"loads and versions"| node_db
node_scribe -->|"creates versions"| node_documents
node_cli -->|"shows and exports"| node_terminal
node_status -->|"checks workflow state"| node_db
node_status -->|"checks repository"| node_git

click node_cli "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/cli.py"
click node_init "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/initialize_project.py"
click node_capture "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/capture_repository.py"
click node_history "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/reconstruct_history.py"
click node_distill "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/interpret_history.py"
click node_scribe "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/generate_document.py"
click node_status "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/get_project_status.py"
click node_evidence "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/domain/evidence.py"
click node_history_data "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/domain/history.py"
click node_claims "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/domain/knowledge_claim.py"
click node_documents "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/domain/document.py"
click node_git "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/git/repository.py"
click node_db "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/database/repositories.py"
click node_workspace "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/filesystem/workspace.py"
click node_interpreter "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/ai/llm_knowledge_interpreter.py"
click node_generator "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/ai/llm_document_generator.py"
click node_provider "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/ai/openai_provider.py"
click node_terminal "https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/ui/terminal.py"

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_cli,node_init,node_capture,node_history,node_distill,node_scribe,node_status toneBlue
class node_evidence,node_history_data,node_claims,node_documents toneAmber
class node_git,node_db,node_workspace,node_terminal toneMint
class node_interpreter,node_generator,node_provider toneRose
class node_developer,node_openai toneIndigo
```

## Components

### CLI and workflows

- [CLI commands](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/cli.py): `src/quilchoom/cli.py`
- [Initialize project](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/initialize_project.py): `src/quilchoom/application/initialize_project.py`
- [Capture commits](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/capture_repository.py): `src/quilchoom/application/capture_repository.py`
- [Reconstruct history](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/reconstruct_history.py): `src/quilchoom/application/reconstruct_history.py`
- [Interpret evidence](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/interpret_history.py): `src/quilchoom/application/interpret_history.py`
- [Generate documents](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/generate_document.py): `src/quilchoom/application/generate_document.py`
- [Project status](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/application/get_project_status.py): `src/quilchoom/application/get_project_status.py`

### Knowledge lifecycle

- [Development evidence](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/domain/evidence.py): `src/quilchoom/domain/evidence.py`
- [History entries](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/domain/history.py): `src/quilchoom/domain/history.py`
- [Knowledge claims](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/domain/knowledge_claim.py): `src/quilchoom/domain/knowledge_claim.py`
- [Document versions](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/domain/document.py): `src/quilchoom/domain/document.py`

### Local infrastructure

- [Git repository](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/git/repository.py): `src/quilchoom/infrastructure/git/repository.py`
- [Local database](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/database/repositories.py): `src/quilchoom/infrastructure/database/repositories.py`
- [Local workspace](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/filesystem/workspace.py): `src/quilchoom/infrastructure/filesystem/workspace.py`
- [Terminal output / export](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/ui/terminal.py): `src/quilchoom/ui/terminal.py`

### AI generation

- [LLM interpreter](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/ai/llm_knowledge_interpreter.py): `src/quilchoom/infrastructure/ai/llm_knowledge_interpreter.py`
- [LLM document generator](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/ai/llm_document_generator.py): `src/quilchoom/infrastructure/ai/llm_document_generator.py`
- [LLM provider adapter](https://github.com/manatunga/quilchoom/blob/main/src/quilchoom/infrastructure/ai/openai_provider.py): `src/quilchoom/infrastructure/ai/openai_provider.py`

### Other components

- **Developer**
- **OpenAI service**

## Connections

- Developer → CLI commands: runs commands
- CLI commands → Initialize project: dispatches (evidence: `src/quilchoom/cli.py`)
- CLI commands → Capture commits: dispatches (evidence: `src/quilchoom/cli.py`)
- CLI commands → Reconstruct history: dispatches (evidence: `src/quilchoom/cli.py`)
- CLI commands → Interpret evidence: dispatches (evidence: `src/quilchoom/cli.py`)
- CLI commands → Generate documents: dispatches (evidence: `src/quilchoom/cli.py`)
- CLI commands → Project status: dispatches (evidence: `src/quilchoom/cli.py`)
- Initialize project → Local workspace: initializes (evidence: `src/quilchoom/application/initialize_project.py`)
- Initialize project → Local database: configures (evidence: `src/quilchoom/application/initialize_project.py`)
- Capture commits → Git repository: lists commits (evidence: `src/quilchoom/application/capture_repository.py`)
- Capture commits → Local database: checks and saves (evidence: `src/quilchoom/application/capture_repository.py`)
- Capture commits → Development evidence: records
- Development evidence → Reconstruct history: reconstructs into
- Reconstruct history → History entries: presents
- Interpret evidence → History entries: interprets (evidence: `src/quilchoom/application/interpret_history.py`)
- Interpret evidence → LLM interpreter: requests interpretation (evidence: `src/quilchoom/application/interpret_history.py`)
- LLM interpreter → LLM provider adapter: requests structured output (evidence: `src/quilchoom/infrastructure/ai/llm_knowledge_interpreter.py`)
- LLM provider adapter → OpenAI service: sends requests
- Interpret evidence → Local database: loads and saves (evidence: `src/quilchoom/application/interpret_history.py`)
- Interpret evidence → Knowledge claims: derives (evidence: `src/quilchoom/application/interpret_history.py`)
- Knowledge claims → Development evidence: trace to
- Generate documents → Knowledge claims: uses active claims (evidence: `src/quilchoom/application/generate_document.py`)
- Generate documents → LLM document generator: requests generation (evidence: `src/quilchoom/application/generate_document.py`)
- LLM document generator → LLM provider adapter: requests structured output (evidence: `src/quilchoom/infrastructure/ai/llm_document_generator.py`)
- Generate documents → Local database: loads and versions (evidence: `src/quilchoom/application/generate_document.py`)
- Generate documents → Document versions: creates versions (evidence: `src/quilchoom/application/generate_document.py`)
- CLI commands → Terminal output / export: shows and exports (evidence: `src/quilchoom/cli.py`)
- Project status → Local database: checks workflow state (evidence: `src/quilchoom/application/get_project_status.py`)
- Project status → Git repository: checks repository (evidence: `src/quilchoom/application/get_project_status.py`)
