# gdogg371/chatgpt-agent-ai architecture

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

- Interactive diagram: https://gitdiagram.com/gdogg371/chatgpt-agent-ai
- Repository: https://github.com/gdogg371/chatgpt-agent-ai

## Overview

This repository provides a Python code-maintenance backend, with a documented CLI workflow for scanning Python docstrings, building prompts, and injecting them into a code bundle. Its capability-based Spine routes runtime work; the prompt engine describes broader fetch-to-patch stages, and patch components handle generated updates. A separate packager builds bundle artifacts and guides. The README is empty, so product scope and relationships below rely on the file tree and the sampled source/SOURCE INDEX; some subsystems are represented without asserted call links where implementation was not shown.

Main entry points: [`v2/cli/docstring.py`](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/cli/docstring.py) (Docstring CLI), [`v2/backend/core/spine/bootstrap.py`](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/spine/bootstrap.py) (Spine Bootstrap), [`v2/backend/core/prompt_pipeline/executor/orchestrator.py`](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/executor/orchestrator.py) (Capability Orchestrator), [`v2/backend/core/db/writers/docstring_writer.py`](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/db/writers/docstring_writer.py) (Docstring Persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry And Runtime"]
  node_doc_cli["Docstring CLI<br/>[docstring.py]"]
  node_spine["Spine Bootstrap<br/>[bootstrap.py]"]
  node_contracts["Capability Contracts<br/>[contracts.py]"]
  node_loader["Capability Loader<br/>[loader.py]"]
  node_registry["Capability Registry<br/>[registry.py]"]
  node_configuration["Runtime Configuration<br/>[config.py]"]
end

subgraph group_docs["Docstring Workflow"]
  node_scanner["Docstring Scanning<br/>[read_docstrings.py]"]
  node_prompt_context["Prompt Context<br/>[context.py]"]
  node_pipeline_engine["Pipeline Engine<br/>[engine.py]"]
  node_pipeline_orchestrator["Capability Orchestrator<br/>[orchestrator.py]"]
  node_llm_router["LLM Router<br/>[router.py]"]
  node_response_parser["Response Parser<br/>[response_parser.py]"]
  node_response_schema["Response Schema<br/>[schema.py]"]
  node_budget["Prompt Budget<br/>[budget.py]"]
end

subgraph group_patch["Patch Processing"]
  node_patch_engine["Patch Provider<br/>[providers.py]"]
  node_rewrite["Docstring Rewrite<br/>[rewrite.py]"]
  node_patch_ops["Patch Operations<br/>[patch_ops.py]"]
end

subgraph group_bundle["Bundle Packaging"]
  node_packager["Packager Orchestrator<br/>[orchestrator.py]"]
  node_bundle_writer["Bundle Writer<br/>[writer.py]"]
  node_guide_writer["Guide Writer<br/>[guide_writer.py]"]
  node_bundle_loader["Bundle Config Loader<br/>[loader.py]"]
end

subgraph group_state["Persistence And Utilities"]
  node_db_init["Database Setup<br/>[db_init.py]"]
  node_docstring_writer["Docstring Persistence"]
  node_introspection_index[("Symbol Index")]
  node_sqlite_dev["SQLite Setup Utility<br/>[init_sqlite_dev.py]"]
  node_file_ops["File Operations<br/>[file_ops.py]"]
end

node_developer(("Developer"))

node_developer -->|"runs workflow"| node_doc_cli
node_doc_cli -->|"dispatches scan"| node_scanner
node_doc_cli -->|"dispatches prompts"| node_pipeline_orchestrator
node_doc_cli -->|"dispatches capability"| node_spine
node_pipeline_orchestrator -->|"resolves runner"| node_registry
node_pipeline_orchestrator -->|"loads capabilities"| node_loader
node_spine -->|"uses loader"| node_loader
node_spine -->|"uses registry"| node_registry
node_spine -->|"uses contracts"| node_contracts
node_pipeline_engine -->|"runs capabilities"| node_pipeline_orchestrator
node_llm_router -->|"parses response"| node_response_parser
node_llm_router -->|"selects schema"| node_response_schema
node_response_parser -->|"uses schema"| node_response_schema
node_scanner -->|"writes records"| node_docstring_writer
node_docstring_writer -->|"initializes storage"| node_db_init
node_docstring_writer -->|"persists symbols"| node_introspection_index
node_patch_engine -->|"rewrites docstrings"| node_rewrite
node_patch_engine -->|"reads files"| node_file_ops
node_patch_ops -->|"uses file operations"| node_file_ops
node_packager -->|"writes artifacts"| node_bundle_writer
node_packager -->|"creates guide"| node_guide_writer
node_doc_cli -->|"initializes SQLite"| node_sqlite_dev

click node_doc_cli "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/cli/docstring.py"
click node_spine "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/spine/bootstrap.py"
click node_contracts "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/spine/contracts.py"
click node_loader "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/spine/loader.py"
click node_registry "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/spine/registry.py"
click node_configuration "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/configuration/config.py"
click node_scanner "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/introspect/read_docstrings.py"
click node_prompt_context "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/docstrings/context.py"
click node_pipeline_engine "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/executor/engine.py"
click node_pipeline_orchestrator "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/executor/orchestrator.py"
click node_llm_router "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/llm/router.py"
click node_response_parser "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/llm/response_parser.py"
click node_response_schema "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/llm/schema.py"
click node_budget "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/preflight/budget.py"
click node_patch_engine "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/patch_engine/providers.py"
click node_rewrite "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/patches/core/rewrite.py"
click node_patch_ops "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/patches/core/patch_ops.py"
click node_packager "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/code_bundles/code_bundles/src/packager/core/orchestrator.py"
click node_bundle_writer "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/code_bundles/code_bundles/src/packager/core/writer.py"
click node_guide_writer "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/code_bundles/code_bundles/src/packager/io/guide_writer.py"
click node_bundle_loader "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/code_bundles/code_bundles/execute/loader.py"
click node_db_init "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/db/access/db_init.py"
click node_docstring_writer "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/db/writers/docstring_writer.py"
click node_introspection_index "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/models/introspection_index.py"
click node_sqlite_dev "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/db/init_sqlite_dev.py"
click node_file_ops "https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/io/file_ops.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_doc_cli,node_spine,node_contracts,node_loader,node_registry,node_configuration toneBlue
class node_scanner,node_prompt_context,node_pipeline_engine,node_pipeline_orchestrator,node_llm_router,node_response_parser,node_response_schema,node_budget toneAmber
class node_patch_engine,node_rewrite,node_patch_ops toneMint
class node_packager,node_bundle_writer,node_guide_writer,node_bundle_loader toneRose
class node_db_init,node_docstring_writer,node_introspection_index,node_sqlite_dev,node_file_ops,node_developer toneIndigo
```

## Components

### Entry And Runtime

- [Docstring CLI](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/cli/docstring.py): `v2/cli/docstring.py`
- [Spine Bootstrap](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/spine/bootstrap.py): `v2/backend/core/spine/bootstrap.py`
- [Capability Contracts](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/spine/contracts.py): `v2/backend/core/spine/contracts.py`
- [Capability Loader](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/spine/loader.py): `v2/backend/core/spine/loader.py`
- [Capability Registry](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/spine/registry.py): `v2/backend/core/spine/registry.py`
- [Runtime Configuration](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/configuration/config.py): `v2/backend/core/configuration/config.py`

### Docstring Workflow

- [Docstring Scanning](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/introspect/read_docstrings.py): `v2/backend/core/introspect/read_docstrings.py`
- [Prompt Context](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/docstrings/context.py): `v2/backend/core/docstrings/context.py`
- [Pipeline Engine](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/executor/engine.py): `v2/backend/core/prompt_pipeline/executor/engine.py`
- [Capability Orchestrator](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/executor/orchestrator.py): `v2/backend/core/prompt_pipeline/executor/orchestrator.py`
- [LLM Router](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/llm/router.py): `v2/backend/core/prompt_pipeline/llm/router.py`
- [Response Parser](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/llm/response_parser.py): `v2/backend/core/prompt_pipeline/llm/response_parser.py`
- [Response Schema](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/llm/schema.py): `v2/backend/core/prompt_pipeline/llm/schema.py`
- [Prompt Budget](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/prompt_pipeline/preflight/budget.py): `v2/backend/core/prompt_pipeline/preflight/budget.py`

### Patch Processing

- [Patch Provider](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/patch_engine/providers.py): `v2/backend/core/patch_engine/providers.py`
- [Docstring Rewrite](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/patches/core/rewrite.py): `v2/patches/core/rewrite.py`
- [Patch Operations](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/patches/core/patch_ops.py): `v2/patches/core/patch_ops.py`

### Bundle Packaging

- [Packager Orchestrator](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/code_bundles/code_bundles/src/packager/core/orchestrator.py): `v2/backend/core/utils/code_bundles/code_bundles/src/packager/core/orchestrator.py`
- [Bundle Writer](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/code_bundles/code_bundles/src/packager/core/writer.py): `v2/backend/core/utils/code_bundles/code_bundles/src/packager/core/writer.py`
- [Guide Writer](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/code_bundles/code_bundles/src/packager/io/guide_writer.py): `v2/backend/core/utils/code_bundles/code_bundles/src/packager/io/guide_writer.py`
- [Bundle Config Loader](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/code_bundles/code_bundles/execute/loader.py): `v2/backend/core/utils/code_bundles/code_bundles/execute/loader.py`

### Persistence And Utilities

- [Database Setup](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/db/access/db_init.py): `v2/backend/core/db/access/db_init.py`
- [Docstring Persistence](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/db/writers/docstring_writer.py): `v2/backend/core/db/writers/docstring_writer.py`
- [Symbol Index](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/models/introspection_index.py): `v2/models/introspection_index.py`
- [SQLite Setup Utility](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/db/init_sqlite_dev.py): `v2/backend/core/utils/db/init_sqlite_dev.py`
- [File Operations](https://github.com/gdogg371/chatgpt-agent-ai/blob/main/v2/backend/core/utils/io/file_ops.py): `v2/backend/core/utils/io/file_ops.py`

### Other components

- **Developer**

## Connections

- Developer → Docstring CLI: runs workflow (evidence: `v2/cli/docstring.py`)
- Docstring CLI → Docstring Scanning: dispatches scan (evidence: `v2/cli/docstring.py`)
- Docstring CLI → Capability Orchestrator: dispatches prompts (evidence: `v2/cli/docstring.py`)
- Docstring CLI → Spine Bootstrap: dispatches capability (evidence: `v2/cli/docstring.py`)
- Capability Orchestrator → Capability Registry: resolves runner (evidence: `v2/backend/core/prompt_pipeline/executor/orchestrator.py`)
- Capability Orchestrator → Capability Loader: loads capabilities (evidence: `v2/backend/core/prompt_pipeline/executor/orchestrator.py`)
- Spine Bootstrap → Capability Loader: uses loader (evidence: `v2/backend/core/spine/bootstrap.py`)
- Spine Bootstrap → Capability Registry: uses registry (evidence: `v2/backend/core/spine/bootstrap.py`)
- Spine Bootstrap → Capability Contracts: uses contracts (evidence: `v2/backend/core/spine/bootstrap.py`)
- Pipeline Engine → Capability Orchestrator: runs capabilities (evidence: `v2/backend/core/prompt_pipeline/executor/engine.py`)
- LLM Router → Response Parser: parses response (evidence: `v2/backend/core/prompt_pipeline/llm/router.py`)
- LLM Router → Response Schema: selects schema (evidence: `v2/backend/core/prompt_pipeline/llm/router.py`)
- Response Parser → Response Schema: uses schema (evidence: `v2/backend/core/prompt_pipeline/llm/response_parser.py`)
- Docstring Scanning → Docstring Persistence: writes records (evidence: `v2/backend/core/introspect/read_docstrings.py`)
- Docstring Persistence → Database Setup: initializes storage (evidence: `v2/backend/core/db/writers/docstring_writer.py`)
- Docstring Persistence → Symbol Index: persists symbols (evidence: `v2/backend/core/db/writers/docstring_writer.py`)
- Patch Provider → Docstring Rewrite: rewrites docstrings (evidence: `v2/backend/core/patch_engine/providers.py`)
- Patch Provider → File Operations: reads files (evidence: `v2/backend/core/patch_engine/providers.py`)
- Patch Operations → File Operations: uses file operations (evidence: `v2/patches/core/patch_ops.py`)
- Packager Orchestrator → Bundle Writer: writes artifacts (evidence: `v2/backend/core/utils/code_bundles/code_bundles/src/packager/core/orchestrator.py`)
- Packager Orchestrator → Guide Writer: creates guide (evidence: `v2/backend/core/utils/code_bundles/code_bundles/src/packager/core/orchestrator.py`)
- Docstring CLI → SQLite Setup Utility: initializes SQLite (evidence: `v2/cli/docstring.py`)
