# styler-ai/projectatlas architecture

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

- Interactive diagram: https://gitdiagram.com/styler-ai/projectatlas
- Repository: https://github.com/styler-ai/projectatlas

## Overview

ProjectAtlas is a local repository-intelligence CLI and MCP server. Its main workflow binds an agent to a project, refreshes or queries the project atlas, then returns focused navigation and evidence—summaries, symbols, relationships, health, or source slices. The README documents these product stages; sampled source most clearly establishes the CLI/MCP entry points, symbol extraction, and optional-parser runtime. Some subsystem links below reflect documented behavior and module boundaries rather than inspected call sites.

Main entry points: [`crates/projectatlas-cli/src/runtime.rs`](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/runtime.rs) (Runtime orchestration), [`crates/projectatlas-cli/src/mcp.rs`](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/mcp.rs) (MCP server), [`crates/projectatlas-cli/src/main.rs`](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/main.rs) (CLI commands), [`crates/projectatlas-core/src/index_work.rs`](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/index_work.rs) (Index work)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Agent interfaces"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_mcp["MCP server<br/>[mcp.rs]"]
end

subgraph group_index["Indexing and analysis"]
  node_runtime["Runtime orchestration<br/>[runtime.rs]"]
  node_index_work["Index work<br/>[index_work.rs]"]
  node_filesystem["Worktree access<br/>[worktree.rs]"]
  node_symbols["Symbol extraction<br/>[lib.rs]"]
end

subgraph group_state["Project state"]
  node_db[("Atlas database<br/>[lib.rs]")]
  node_graph_store["Repository graph"]
  node_identity["Project identity"]
end

subgraph group_insight["Navigation and insight"]
  node_analysis["Analysis services<br/>[analysis.rs]"]
  node_relations["Relation services<br/>[relations.rs]"]
  node_core_graph["Graph model<br/>[graph.rs]"]
  node_health["Health findings<br/>[health.rs]"]
  node_toon["Compact output<br/>[toon.rs]"]
  node_token_tui["Token dashboard<br/>[token_tui.rs]"]
end

subgraph group_parser["Optional parsing"]
  node_parser_runtime["Parser coordinator"]
  node_parser_supervisor["Worker supervisor"]
  node_worker["Parser worker<br/>[parser_worker.rs]"]
  node_protocol["Worker protocol"]
end

node_agent(("Coding agent"))
node_human(("CLI user"))
node_mcp_host(("MCP host"))

node_human -->|"runs commands"| node_cli
node_agent -->|"requests tools"| node_mcp_host
node_mcp_host -->|"dispatches tools"| node_mcp
node_cli -->|"invokes operations"| node_runtime
node_mcp -->|"routes requests"| node_runtime
node_runtime -->|"coordinates indexing"| node_index_work
node_index_work -->|"scans worktree"| node_filesystem
node_index_work -->|"extracts symbols"| node_symbols
node_runtime -->|"reads and writes"| node_db
node_symbols -->|"produces graph"| node_core_graph
node_runtime -->|"persists graph"| node_graph_store
node_runtime -->|"binds project"| node_identity
node_mcp -->|"serves insight tools"| node_analysis
node_analysis -.->|"resolves relations"| node_relations
node_analysis -.->|"reports health"| node_health
node_mcp -.->|"formats responses"| node_toon
node_cli -->|"opens dashboard"| node_token_tui
node_token_tui -.->|"reads map data"| node_graph_store
node_runtime -.->|"parses optional jobs"| node_parser_runtime
node_parser_runtime -->|"supervises worker"| node_parser_supervisor
node_parser_supervisor -->|"sends requests"| node_worker
node_worker -->|"exchanges messages"| node_protocol

click node_cli "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/main.rs"
click node_mcp "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/mcp.rs"
click node_runtime "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/runtime.rs"
click node_index_work "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/index_work.rs"
click node_filesystem "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-fs/src/worktree.rs"
click node_symbols "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-symbols/src/lib.rs"
click node_db "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-db/src/lib.rs"
click node_graph_store "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-db/src/repository_graph.rs"
click node_identity "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-db/src/project_identity.rs"
click node_analysis "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-service/src/analysis.rs"
click node_relations "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-service/src/relations.rs"
click node_core_graph "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/graph.rs"
click node_health "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/health.rs"
click node_toon "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/toon.rs"
click node_token_tui "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/token_tui.rs"
click node_parser_runtime "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/runtime/optional_parser_runtime.rs"
click node_parser_supervisor "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/parser_supervisor.rs"
click node_worker "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/parser_worker.rs"
click node_protocol "https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/optional_parser_protocol.rs"

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_mcp,node_human toneBlue
class node_runtime,node_index_work,node_filesystem,node_symbols toneAmber
class node_db,node_graph_store,node_identity toneMint
class node_analysis,node_relations,node_core_graph,node_health,node_toon,node_token_tui toneRose
class node_parser_runtime,node_parser_supervisor,node_worker,node_protocol,node_agent,node_mcp_host toneIndigo
```

## Components

### Agent interfaces

- [CLI commands](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/main.rs): `crates/projectatlas-cli/src/main.rs`
- [MCP server](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/mcp.rs): `crates/projectatlas-cli/src/mcp.rs`

### Indexing and analysis

- [Runtime orchestration](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/runtime.rs): `crates/projectatlas-cli/src/runtime.rs`
- [Index work](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/index_work.rs): `crates/projectatlas-core/src/index_work.rs`
- [Worktree access](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-fs/src/worktree.rs): `crates/projectatlas-fs/src/worktree.rs`
- [Symbol extraction](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-symbols/src/lib.rs): `crates/projectatlas-symbols/src/lib.rs`

### Project state

- [Atlas database](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-db/src/lib.rs): `crates/projectatlas-db/src/lib.rs`
- [Repository graph](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-db/src/repository_graph.rs): `crates/projectatlas-db/src/repository_graph.rs`
- [Project identity](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-db/src/project_identity.rs): `crates/projectatlas-db/src/project_identity.rs`

### Navigation and insight

- [Analysis services](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-service/src/analysis.rs): `crates/projectatlas-service/src/analysis.rs`
- [Relation services](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-service/src/relations.rs): `crates/projectatlas-service/src/relations.rs`
- [Graph model](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/graph.rs): `crates/projectatlas-core/src/graph.rs`
- [Health findings](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/health.rs): `crates/projectatlas-core/src/health.rs`
- [Compact output](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/toon.rs): `crates/projectatlas-core/src/toon.rs`
- [Token dashboard](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/token_tui.rs): `crates/projectatlas-cli/src/token_tui.rs`

### Optional parsing

- [Parser coordinator](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/runtime/optional_parser_runtime.rs): `crates/projectatlas-cli/src/runtime/optional_parser_runtime.rs`
- [Worker supervisor](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/parser_supervisor.rs): `crates/projectatlas-cli/src/parser_supervisor.rs`
- [Parser worker](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-cli/src/parser_worker.rs): `crates/projectatlas-cli/src/parser_worker.rs`
- [Worker protocol](https://github.com/styler-ai/projectatlas/blob/main/crates/projectatlas-core/src/optional_parser_protocol.rs): `crates/projectatlas-core/src/optional_parser_protocol.rs`

### Other components

- **Coding agent**
- **CLI user**
- **MCP host**

## Connections

- CLI user → CLI commands: runs commands
- Coding agent → MCP host: requests tools
- MCP host → MCP server: dispatches tools
- CLI commands → Runtime orchestration: invokes operations
- MCP server → Runtime orchestration: routes requests
- Runtime orchestration → Index work: coordinates indexing
- Index work → Worktree access: scans worktree
- Index work → Symbol extraction: extracts symbols
- Runtime orchestration → Atlas database: reads and writes
- Symbol extraction → Graph model: produces graph
- Runtime orchestration → Repository graph: persists graph
- Runtime orchestration → Project identity: binds project
- MCP server → Analysis services: serves insight tools
- Analysis services → Relation services: resolves relations
- Analysis services → Health findings: reports health
- MCP server → Compact output: formats responses
- CLI commands → Token dashboard: opens dashboard
- Token dashboard → Repository graph: reads map data
- Runtime orchestration → Parser coordinator: parses optional jobs
- Parser coordinator → Worker supervisor: supervises worker
- Worker supervisor → Parser worker: sends requests
- Parser worker → Worker protocol: exchanges messages