# aoci-spec/aoci-code architecture

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

- Interactive diagram: https://gitdiagram.com/aoci-spec/aoci-code
- Repository: https://github.com/aoci-spec/aoci-code

## Overview

AOCI-CODE is a local-first CLI and MCP service for building and maintaining a Git-versioned code-and-database cognition index for coding agents. The main workflow initializes host integration, scans the repository, then lets an agent use MCP tools to read, author, validate, and apply index updates; the maintained index is reused across tasks and sessions. Database metadata indexing and the read-only status panel are separate capabilities. Some subsystem wiring is based on README documentation and tree paths because their source was not sampled.

Main entry points: [`internal/cli/root.go`](https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/root.go) (CLI commands), [`internal/workflow/entries_worker.go`](https://github.com/aoci-spec/aoci-code/blob/main/internal/workflow/entries_worker.go) (Entry authoring), [`internal/mcptools/tools_write.go`](https://github.com/aoci-spec/aoci-code/blob/main/internal/mcptools/tools_write.go) (MCP tools), [`internal/cli/database.go`](https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/database.go) (Database commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and setup"]
  node_aoci["aoci command<br/>[main.go]"]
  node_cli["CLI commands<br/>[root.go]"]
  node_init["Initialize host<br/>[init.go]"]
end

subgraph group_indexing["Index workflow"]
  node_scan["Repository scan<br/>[scan.go]"]
  node_index["Index model<br/>[types.go]"]
  node_workflow["Entry authoring<br/>[entries_worker.go]"]
  node_prompt["Prompt assembly<br/>[entry.go]"]
  node_assets["Project index"]
end

subgraph group_agent["Agent interface"]
  node_mcp["MCP server<br/>[server.go]"]
  node_tools["MCP tools<br/>[tools_write.go]"]
  node_cognition["Index cognition<br/>[loader.go]"]
  node_search["Search and query<br/>[query.go]"]
end

subgraph group_database["Database cognition"]
  node_database_cli["Database commands<br/>[database.go]"]
  node_collector["Schema collector<br/>[collector.go]"]
  node_evidence[("Schema evidence<br/>[store.go]")]
  node_dbcognition["Database index<br/>[state.go]"]
end

subgraph group_visibility["Status panel"]
  node_ui_cli["Panel commands<br/>[ui.go]"]
  node_ui_server["Read-only panel<br/>[server.go]"]
end

node_user(("User or agent"))
node_llm(("Model endpoint"))
node_dbdrivers(("Database engines"))

node_user -->|"runs"| node_aoci
node_aoci -->|"executes"| node_cli
node_cli -->|"dispatches"| node_init
node_cli -->|"dispatches"| node_scan
node_cli -->|"dispatches"| node_database_cli
node_cli -->|"dispatches"| node_ui_cli
node_scan -->|"builds inventory"| node_index
node_index -->|"persists index"| node_assets
node_user -->|"connects agent"| node_mcp
node_mcp -->|"dispatches tools"| node_tools
node_tools -->|"loads index"| node_cognition
node_cognition -->|"reads index"| node_assets
node_tools -->|"queries entries"| node_search
node_workflow -->|"prepares input"| node_prompt
node_prompt -->|"returns prompt"| node_workflow
node_workflow -->|"requests completion"| node_llm
node_workflow -->|"writes drafts"| node_assets
node_database_cli -->|"collects metadata"| node_collector
node_collector -->|"queries catalogs"| node_dbdrivers
node_collector -->|"stores snapshots"| node_evidence
node_database_cli -->|"builds database index"| node_dbcognition
node_ui_cli -->|"starts panel"| node_ui_server
node_ui_server -->|"reads index"| node_assets

click node_aoci "https://github.com/aoci-spec/aoci-code/blob/main/cmd/aoci/main.go"
click node_cli "https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/root.go"
click node_init "https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/init.go"
click node_scan "https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/scan.go"
click node_index "https://github.com/aoci-spec/aoci-code/blob/main/internal/index/types.go"
click node_workflow "https://github.com/aoci-spec/aoci-code/blob/main/internal/workflow/entries_worker.go"
click node_prompt "https://github.com/aoci-spec/aoci-code/blob/main/internal/prompt/entry.go"
click node_mcp "https://github.com/aoci-spec/aoci-code/blob/main/internal/mcptools/server.go"
click node_tools "https://github.com/aoci-spec/aoci-code/blob/main/internal/mcptools/tools_write.go"
click node_cognition "https://github.com/aoci-spec/aoci-code/blob/main/internal/cognition/loader.go"
click node_search "https://github.com/aoci-spec/aoci-code/blob/main/internal/index/query.go"
click node_database_cli "https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/database.go"
click node_collector "https://github.com/aoci-spec/aoci-code/blob/main/internal/dbevidence/collector.go"
click node_evidence "https://github.com/aoci-spec/aoci-code/blob/main/internal/dbevidence/store.go"
click node_dbcognition "https://github.com/aoci-spec/aoci-code/blob/main/internal/dbcognition/state.go"
click node_ui_cli "https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/ui.go"
click node_ui_server "https://github.com/aoci-spec/aoci-code/blob/main/internal/ui/server.go"

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_aoci,node_cli,node_init,node_user toneBlue
class node_scan,node_index,node_workflow,node_prompt,node_assets,node_dbdrivers toneAmber
class node_mcp,node_tools,node_cognition,node_search toneMint
class node_database_cli,node_collector,node_evidence,node_dbcognition toneRose
class node_ui_cli,node_ui_server,node_llm toneIndigo
```

## Components

### CLI and setup

- [aoci command](https://github.com/aoci-spec/aoci-code/blob/main/cmd/aoci/main.go): `cmd/aoci/main.go`
- [CLI commands](https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [Initialize host](https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/init.go): `internal/cli/init.go`

### Index workflow

- [Repository scan](https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/scan.go): `internal/cli/scan.go`
- [Index model](https://github.com/aoci-spec/aoci-code/blob/main/internal/index/types.go): `internal/index/types.go`
- [Entry authoring](https://github.com/aoci-spec/aoci-code/blob/main/internal/workflow/entries_worker.go): `internal/workflow/entries_worker.go`
- [Prompt assembly](https://github.com/aoci-spec/aoci-code/blob/main/internal/prompt/entry.go): `internal/prompt/entry.go`
- **Project index**

### Agent interface

- [MCP server](https://github.com/aoci-spec/aoci-code/blob/main/internal/mcptools/server.go): `internal/mcptools/server.go`
- [MCP tools](https://github.com/aoci-spec/aoci-code/blob/main/internal/mcptools/tools_write.go): `internal/mcptools/tools_write.go`
- [Index cognition](https://github.com/aoci-spec/aoci-code/blob/main/internal/cognition/loader.go): `internal/cognition/loader.go`
- [Search and query](https://github.com/aoci-spec/aoci-code/blob/main/internal/index/query.go): `internal/index/query.go`

### Database cognition

- [Database commands](https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/database.go): `internal/cli/database.go`
- [Schema collector](https://github.com/aoci-spec/aoci-code/blob/main/internal/dbevidence/collector.go): `internal/dbevidence/collector.go`
- [Schema evidence](https://github.com/aoci-spec/aoci-code/blob/main/internal/dbevidence/store.go): `internal/dbevidence/store.go`
- [Database index](https://github.com/aoci-spec/aoci-code/blob/main/internal/dbcognition/state.go): `internal/dbcognition/state.go`

### Status panel

- [Panel commands](https://github.com/aoci-spec/aoci-code/blob/main/internal/cli/ui.go): `internal/cli/ui.go`
- [Read-only panel](https://github.com/aoci-spec/aoci-code/blob/main/internal/ui/server.go): `internal/ui/server.go`

### Other components

- **User or agent**
- **Model endpoint**
- **Database engines**

## Connections

- User or agent → aoci command: runs
- aoci command → CLI commands: executes
- CLI commands → Initialize host: dispatches
- CLI commands → Repository scan: dispatches
- CLI commands → Database commands: dispatches
- CLI commands → Panel commands: dispatches
- Repository scan → Index model: builds inventory
- Index model → Project index: persists index
- User or agent → MCP server: connects agent
- MCP server → MCP tools: dispatches tools
- MCP tools → Index cognition: loads index
- Index cognition → Project index: reads index
- MCP tools → Search and query: queries entries
- Entry authoring → Prompt assembly: prepares input
- Prompt assembly → Entry authoring: returns prompt
- Entry authoring → Model endpoint: requests completion
- Entry authoring → Project index: writes drafts
- Database commands → Schema collector: collects metadata
- Schema collector → Database engines: queries catalogs
- Schema collector → Schema evidence: stores snapshots
- Database commands → Database index: builds database index
- Panel commands → Read-only panel: starts panel
- Read-only panel → Project index: reads index