# omeryasirkucuk/amx architecture

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

- Interactive diagram: https://gitdiagram.com/omeryasirkucuk/amx
- Repository: https://github.com/omeryasirkucuk/amx

## Overview

AMX drafts database comments by combining live schema/profile evidence, retrieved documentation, and code references; an orchestrator ranks suggestions for human review before approved text is applied as native database comments. Users can run this workflow through the CLI or Studio. The repository also includes search/Ask, lineage, generated documentation pages, scheduling, and IDE integrations. Edges follow README-described behavior or relationships visible in the supplied source index and excerpts; unsampled subsystem wiring is not inferred.

Main entry points: [`amx/agents/orchestrator.py`](https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/orchestrator.py) (Run orchestrator), [`amx/llm/provider.py`](https://github.com/omeryasirkucuk/amx/blob/main/amx/llm/provider.py) (LLM provider), [`amx/agents/code_agent.py`](https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/code_agent.py) (Code agent), [`amx/cli.py`](https://github.com/omeryasirkucuk/amx/blob/main/amx/cli.py) (CLI session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Comment generation"]
  node_orchestrator["Run orchestrator<br/>[orchestrator.py]"]
  node_profile["Profile agent<br/>[profile_agent.py]"]
  node_ragagent["RAG agent<br/>[rag_agent.py]"]
  node_codeagent["Code agent<br/>[code_agent.py]"]
  node_agentbase["Agent types<br/>[base.py]"]
  node_llm["LLM provider<br/>[provider.py]"]
  node_batch["LLM batch<br/>[batch.py]"]
end

subgraph group_data["Data and retrieval"]
  node_config["Configuration<br/>[config.py]"]
  node_db["Database connector<br/>[connector.py]"]
  node_dbadapters["Database adapters<br/>[base.py]"]
  node_codeanalysis["Code analysis<br/>[analyzer.py]"]
  node_coderag["Code retrieval<br/>[code_rag.py]"]
  node_catalog[("Search catalog<br/>[catalog.py]")]
  node_searchindex["Search index<br/>[index.py]"]
  node_docs["Documentation retrieval<br/>[rag_agent.py]"]
  node_optional["Optional dependencies<br/>[optional_deps.py]"]
end

subgraph group_review["Review and history"]
  node_sqlite[("Local history store<br/>[sqlite_store.py]")]
  node_pending["Pending review<br/>[pending_review.py]"]
  node_reviewflow["Human review<br/>[review.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI session<br/>[cli.py]"]
  node_studio["Studio server<br/>[server.py]"]
  node_frontend["Studio UI<br/>[App.tsx]"]
  node_console["Console output<br/>[console.py]"]
  node_display["Live display<br/>[live_display.py]"]
  node_logging["Structured logging<br/>[logging.py]"]
end

subgraph group_extensions["Additional capabilities"]
  node_lineage["Lineage service<br/>[service.py]"]
  node_pages["Page generation<br/>[service.py]"]
  node_scheduler["Scheduled runs<br/>[tick.py]"]
  node_worker["Scheduled worker<br/>[worker.py]"]
  node_vscode["VS Code extension<br/>[extension.ts]"]
  node_mcp["MCP server<br/>[server.py]"]
end

node_user(("User"))

node_user -->|"starts run"| node_cli
node_user -->|"opens Studio"| node_studio
node_frontend -.->|"calls API"| node_studio
node_cli -->|"starts generation"| node_orchestrator
node_studio -.->|"generates suggestions"| node_orchestrator
node_orchestrator -->|"gathers evidence"| node_profile
node_orchestrator -->|"gathers evidence"| node_ragagent
node_orchestrator -->|"gathers evidence"| node_codeagent
node_orchestrator -->|"profiles assets"| node_db
node_orchestrator -->|"uses suggestion types"| node_agentbase
node_profile -.->|"requests completion"| node_llm
node_ragagent -.->|"requests completion"| node_llm
node_codeagent -->|"requests completion"| node_llm
node_codeagent -->|"finds references"| node_codeanalysis
node_codeagent -->|"retrieves code context"| node_coderag
node_db -->|"uses backend adapter"| node_dbadapters
node_orchestrator -->|"ranks and reviews"| node_reviewflow
node_reviewflow -->|"presents suggestions"| node_user
node_user -->|"accepts or edits"| node_reviewflow
node_reviewflow -->|"applies approved comments"| node_db
node_orchestrator -->|"records run history"| node_sqlite
node_pending -->|"reads and updates history"| node_sqlite
node_cli -.->|"renders prompts"| node_console
node_cli -.->|"shows progress"| node_display
node_orchestrator -->|"reads configuration"| node_config
node_llm -->|"uses provider settings"| node_config
node_catalog -->|"opens history store"| node_sqlite
node_catalog -->|"uses index"| node_searchindex
node_user -.->|"searches catalog"| node_catalog
node_user -.->|"explores lineage"| node_lineage
node_user -.->|"creates documentation pages"| node_pages
node_scheduler -->|"spawns scheduled run"| node_worker
node_worker -->|"executes scheduled run"| node_orchestrator
node_user -.->|"uses IDE integration"| node_vscode
node_user -.->|"connects MCP client"| node_mcp
node_llm -->|"submits batch requests"| node_batch
node_orchestrator -.->|"logs run activity"| node_logging
node_codeanalysis -->|"checks optional packages"| node_optional

click node_cli "https://github.com/omeryasirkucuk/amx/blob/main/amx/cli.py"
click node_studio "https://github.com/omeryasirkucuk/amx/blob/main/amx/web/server.py"
click node_frontend "https://github.com/omeryasirkucuk/amx/blob/main/frontend/src/App.tsx"
click node_orchestrator "https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/orchestrator.py"
click node_profile "https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/profile_agent.py"
click node_ragagent "https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/rag_agent.py"
click node_codeagent "https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/code_agent.py"
click node_agentbase "https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/base.py"
click node_llm "https://github.com/omeryasirkucuk/amx/blob/main/amx/llm/provider.py"
click node_config "https://github.com/omeryasirkucuk/amx/blob/main/amx/config.py"
click node_db "https://github.com/omeryasirkucuk/amx/blob/main/amx/db/connector.py"
click node_dbadapters "https://github.com/omeryasirkucuk/amx/blob/main/amx/db/adapters/base.py"
click node_codeanalysis "https://github.com/omeryasirkucuk/amx/blob/main/amx/codebase/analyzer.py"
click node_coderag "https://github.com/omeryasirkucuk/amx/blob/main/amx/codebase/code_rag.py"
click node_catalog "https://github.com/omeryasirkucuk/amx/blob/main/amx/search/catalog.py"
click node_searchindex "https://github.com/omeryasirkucuk/amx/blob/main/amx/search/index.py"
click node_sqlite "https://github.com/omeryasirkucuk/amx/blob/main/amx/storage/sqlite_store.py"
click node_pending "https://github.com/omeryasirkucuk/amx/blob/main/amx/pending_review.py"
click node_reviewflow "https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/_orchestrator/review.py"
click node_docs "https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/rag_agent.py"
click node_lineage "https://github.com/omeryasirkucuk/amx/blob/main/amx/lineage/service.py"
click node_pages "https://github.com/omeryasirkucuk/amx/blob/main/amx/pages/service.py"
click node_scheduler "https://github.com/omeryasirkucuk/amx/blob/main/amx/scheduler/tick.py"
click node_worker "https://github.com/omeryasirkucuk/amx/blob/main/amx/runtime/worker.py"
click node_vscode "https://github.com/omeryasirkucuk/amx/blob/main/vscode-extension/src/extension.ts"
click node_mcp "https://github.com/omeryasirkucuk/amx/blob/main/amx/mcp/server.py"
click node_batch "https://github.com/omeryasirkucuk/amx/blob/main/amx/llm/batch.py"
click node_console "https://github.com/omeryasirkucuk/amx/blob/main/amx/utils/console.py"
click node_display "https://github.com/omeryasirkucuk/amx/blob/main/amx/utils/live_display.py"
click node_logging "https://github.com/omeryasirkucuk/amx/blob/main/amx/utils/logging.py"
click node_optional "https://github.com/omeryasirkucuk/amx/blob/main/amx/utils/optional_deps.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_orchestrator,node_profile,node_ragagent,node_codeagent,node_agentbase,node_llm,node_batch,node_user toneBlue
class node_config,node_db,node_dbadapters,node_codeanalysis,node_coderag,node_catalog,node_searchindex,node_docs,node_optional toneAmber
class node_sqlite,node_pending,node_reviewflow toneMint
class node_cli,node_studio,node_frontend,node_console,node_display,node_logging toneRose
class node_lineage,node_pages,node_scheduler,node_worker,node_vscode,node_mcp toneIndigo
```

## Components

### Comment generation

- [Run orchestrator](https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/orchestrator.py): `amx/agents/orchestrator.py`
- [Profile agent](https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/profile_agent.py): `amx/agents/profile_agent.py`
- [RAG agent](https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/rag_agent.py): `amx/agents/rag_agent.py`
- [Code agent](https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/code_agent.py): `amx/agents/code_agent.py`
- [Agent types](https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/base.py): `amx/agents/base.py`
- [LLM provider](https://github.com/omeryasirkucuk/amx/blob/main/amx/llm/provider.py): `amx/llm/provider.py`
- [LLM batch](https://github.com/omeryasirkucuk/amx/blob/main/amx/llm/batch.py): `amx/llm/batch.py`

### Data and retrieval

- [Configuration](https://github.com/omeryasirkucuk/amx/blob/main/amx/config.py): `amx/config.py`
- [Database connector](https://github.com/omeryasirkucuk/amx/blob/main/amx/db/connector.py): `amx/db/connector.py`
- [Database adapters](https://github.com/omeryasirkucuk/amx/blob/main/amx/db/adapters/base.py): `amx/db/adapters/base.py`
- [Code analysis](https://github.com/omeryasirkucuk/amx/blob/main/amx/codebase/analyzer.py): `amx/codebase/analyzer.py`
- [Code retrieval](https://github.com/omeryasirkucuk/amx/blob/main/amx/codebase/code_rag.py): `amx/codebase/code_rag.py`
- [Search catalog](https://github.com/omeryasirkucuk/amx/blob/main/amx/search/catalog.py): `amx/search/catalog.py`
- [Search index](https://github.com/omeryasirkucuk/amx/blob/main/amx/search/index.py): `amx/search/index.py`
- [Documentation retrieval](https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/rag_agent.py): `amx/agents/rag_agent.py`
- [Optional dependencies](https://github.com/omeryasirkucuk/amx/blob/main/amx/utils/optional_deps.py): `amx/utils/optional_deps.py`

### Review and history

- [Local history store](https://github.com/omeryasirkucuk/amx/blob/main/amx/storage/sqlite_store.py): `amx/storage/sqlite_store.py`
- [Pending review](https://github.com/omeryasirkucuk/amx/blob/main/amx/pending_review.py): `amx/pending_review.py`
- [Human review](https://github.com/omeryasirkucuk/amx/blob/main/amx/agents/_orchestrator/review.py): `amx/agents/_orchestrator/review.py`

### User interfaces

- [CLI session](https://github.com/omeryasirkucuk/amx/blob/main/amx/cli.py): `amx/cli.py`
- [Studio server](https://github.com/omeryasirkucuk/amx/blob/main/amx/web/server.py): `amx/web/server.py`
- [Studio UI](https://github.com/omeryasirkucuk/amx/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Console output](https://github.com/omeryasirkucuk/amx/blob/main/amx/utils/console.py): `amx/utils/console.py`
- [Live display](https://github.com/omeryasirkucuk/amx/blob/main/amx/utils/live_display.py): `amx/utils/live_display.py`
- [Structured logging](https://github.com/omeryasirkucuk/amx/blob/main/amx/utils/logging.py): `amx/utils/logging.py`

### Additional capabilities

- [Lineage service](https://github.com/omeryasirkucuk/amx/blob/main/amx/lineage/service.py): `amx/lineage/service.py`
- [Page generation](https://github.com/omeryasirkucuk/amx/blob/main/amx/pages/service.py): `amx/pages/service.py`
- [Scheduled runs](https://github.com/omeryasirkucuk/amx/blob/main/amx/scheduler/tick.py): `amx/scheduler/tick.py`
- [Scheduled worker](https://github.com/omeryasirkucuk/amx/blob/main/amx/runtime/worker.py): `amx/runtime/worker.py`
- [VS Code extension](https://github.com/omeryasirkucuk/amx/blob/main/vscode-extension/src/extension.ts): `vscode-extension/src/extension.ts`
- [MCP server](https://github.com/omeryasirkucuk/amx/blob/main/amx/mcp/server.py): `amx/mcp/server.py`

### Other components

- **User**

## Connections

- User → CLI session: starts run (evidence: `README.md`)
- User → Studio server: opens Studio (evidence: `README.md`)
- Studio UI → Studio server: calls API
- CLI session → Run orchestrator: starts generation (evidence: `README.md`)
- Studio server → Run orchestrator: generates suggestions
- Run orchestrator → Profile agent: gathers evidence (evidence: `README.md`)
- Run orchestrator → RAG agent: gathers evidence (evidence: `README.md`)
- Run orchestrator → Code agent: gathers evidence (evidence: `README.md`)
- Run orchestrator → Database connector: profiles assets (evidence: `amx/agents/orchestrator.py`)
- Run orchestrator → Agent types: uses suggestion types (evidence: `amx/agents/orchestrator.py`)
- Profile agent → LLM provider: requests completion
- RAG agent → LLM provider: requests completion
- Code agent → LLM provider: requests completion (evidence: `amx/agents/code_agent.py`)
- Code agent → Code analysis: finds references (evidence: `amx/agents/code_agent.py`)
- Code agent → Code retrieval: retrieves code context (evidence: `amx/agents/code_agent.py`)
- Database connector → Database adapters: uses backend adapter (evidence: `amx/db/connector.py`)
- Run orchestrator → Human review: ranks and reviews (evidence: `README.md`)
- Human review → User: presents suggestions (evidence: `README.md`)
- User → Human review: accepts or edits (evidence: `README.md`)
- Human review → Database connector: applies approved comments (evidence: `README.md`)
- Run orchestrator → Local history store: records run history (evidence: `README.md`)
- Pending review → Local history store: reads and updates history (evidence: `amx/pending_review.py`)
- CLI session → Console output: renders prompts
- CLI session → Live display: shows progress
- Run orchestrator → Configuration: reads configuration (evidence: `amx/agents/orchestrator.py`)
- LLM provider → Configuration: uses provider settings (evidence: `amx/llm/provider.py`)
- Search catalog → Local history store: opens history store (evidence: `amx/search/catalog.py`)
- Search catalog → Search index: uses index (evidence: `amx/search/catalog.py`)
- User → Search catalog: searches catalog
- User → Lineage service: explores lineage
- User → Page generation: creates documentation pages
- Scheduled runs → Scheduled worker: spawns scheduled run (evidence: `amx/runtime/worker.py`)
- Scheduled worker → Run orchestrator: executes scheduled run (evidence: `amx/runtime/worker.py`)
- User → VS Code extension: uses IDE integration
- User → MCP server: connects MCP client
- LLM provider → LLM batch: submits batch requests (evidence: `amx/llm/provider.py`)
- Run orchestrator → Structured logging: logs run activity (evidence: `amx/agents/orchestrator.py`)
- Code analysis → Optional dependencies: checks optional packages (evidence: `amx/codebase/analyzer.py`)