# bodsink/loci architecture

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

- Interactive diagram: https://gitdiagram.com/bodsink/loci
- Repository: https://github.com/bodsink/loci

## Overview

Loci indexes local repositories into a persistent symbol-and-relationship graph, then exposes structural discovery to coding agents through MCP and to people through a local web UI. The main workflow is CLI or MCP indexing → file walking and parsing → cross-file resolution (optionally aided by LSP) → graph storage → graph queries and snippets. The README also documents freshness, coverage, change detection, runtime traces, ADRs, and UI views. Several subsystem links reflect explicit README descriptions because their implementation excerpts were not provided.

Main entry points: [`crates/loci-index/src/lib.rs`](https://github.com/bodsink/loci/blob/master/crates/loci-index/src/lib.rs) (Index orchestration), [`crates/loci-mcp/src/handlers.rs`](https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/handlers.rs) (Tool handlers), [`crates/loci-parse/src/extract.rs`](https://github.com/bodsink/loci/blob/master/crates/loci-parse/src/extract.rs) (Language parsing), [`crates/loci-cli/src/main.rs`](https://github.com/bodsink/loci/blob/master/crates/loci-cli/src/main.rs) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Indexing"]
  node_walker["Repository walker<br/>[walk.rs]"]
  node_parser["Language parsing<br/>[extract.rs]"]
  node_grammars["Grammar registry<br/>[registry.rs]"]
  node_dialect["Dialect adaptations<br/>[dialect.rs]"]
  node_spec["Language specifications<br/>[spec.rs]"]
  node_resolver["Edge resolution<br/>[resolve.rs]"]
  node_imports["Import resolution<br/>[imports.rs]"]
  node_indexer["Index orchestration<br/>[lib.rs]"]
  node_changes["Change detection<br/>[changes.rs]"]
  node_hybrid["Hybrid indexing<br/>[hybrid.rs]"]
  node_lsp["LSP client<br/>[client.rs]"]
end

subgraph group_model["Graph engine"]
  node_graph["Graph schema<br/>[schema.rs]"]
  node_store[("Persistent graph store<br/>[store.rs]")]
  node_query["Graph queries<br/>[query.rs]"]
  node_catalog["Project catalog<br/>[catalog.rs]"]
  node_coverage["Index coverage<br/>[coverage.rs]"]
end

subgraph group_agent["Agent interface"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_mcp["MCP server<br/>[lib.rs]"]
  node_handlers["Tool handlers<br/>[handlers.rs]"]
  node_tools["Tool definitions<br/>[tools.rs]"]
  node_freshness["Freshness checks<br/>[freshness.rs]"]
  node_journal["Usage journal<br/>[journal.rs]"]
end

subgraph group_ui["Local web UI"]
  node_ui_service["UI service<br/>[ui.rs]"]
  node_ui_graph["Graph views<br/>[ui_graph.rs]"]
  node_web["Browser UI<br/>[app.js]"]
end

node_user(("Engineer or agent"))
node_repository["Source repository"]
node_cursor(("Cursor / MCP client"))
node_browser(("Web browser"))
node_language_server["Language server"]

node_user -->|"runs commands"| node_cli
node_user -->|"asks questions"| node_cursor
node_cursor -->|"starts stdio server"| node_mcp
node_mcp -.->|"registers tools"| node_tools
node_mcp -.->|"dispatches calls"| node_handlers
node_handlers -->|"indexes projects"| node_indexer
node_cli -->|"indexes projects"| node_indexer
node_indexer -->|"walks files"| node_walker
node_indexer -->|"parses changed files"| node_parser
node_parser -->|"selects grammar"| node_grammars
node_parser -.->|"adapts syntax"| node_dialect
node_parser -->|"uses language rules"| node_spec
node_indexer -->|"rebuilds edges"| node_resolver
node_resolver -.->|"resolves imports"| node_imports
node_indexer -.->|"detects changes"| node_changes
node_indexer -.->|"adds LSP evidence"| node_hybrid
node_hybrid -.->|"requests definitions"| node_lsp
node_lsp -->|"sends LSP requests"| node_language_server
node_indexer -.->|"writes graph"| node_store
node_store -->|"stores schema records"| node_graph
node_handlers -->|"runs graph queries"| node_query
node_query -->|"reads graph"| node_store
node_handlers -.->|"reports coverage"| node_coverage
node_handlers -.->|"checks freshness"| node_freshness
node_handlers -.->|"records tool calls"| node_journal
node_cli -->|"summarizes usage"| node_journal
node_cli -->|"starts UI"| node_ui_service
node_ui_service -->|"serves graph views"| node_ui_graph
node_ui_service -.->|"serves browser assets"| node_web
node_web -->|"renders interface"| node_browser
node_ui_graph -.->|"reads graph"| node_store
node_repository -->|"provides source"| node_indexer
node_handlers -.->|"uses project catalog"| node_catalog

click node_cli "https://github.com/bodsink/loci/blob/master/crates/loci-cli/src/main.rs"
click node_mcp "https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/lib.rs"
click node_handlers "https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/handlers.rs"
click node_tools "https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/tools.rs"
click node_freshness "https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/freshness.rs"
click node_journal "https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/journal.rs"
click node_walker "https://github.com/bodsink/loci/blob/master/crates/loci-index/src/walk.rs"
click node_parser "https://github.com/bodsink/loci/blob/master/crates/loci-parse/src/extract.rs"
click node_grammars "https://github.com/bodsink/loci/blob/master/crates/loci-parse/src/registry.rs"
click node_dialect "https://github.com/bodsink/loci/blob/master/crates/loci-parse/src/dialect.rs"
click node_spec "https://github.com/bodsink/loci/blob/master/crates/loci-parse/src/spec.rs"
click node_resolver "https://github.com/bodsink/loci/blob/master/crates/loci-index/src/resolve.rs"
click node_imports "https://github.com/bodsink/loci/blob/master/crates/loci-index/src/imports.rs"
click node_indexer "https://github.com/bodsink/loci/blob/master/crates/loci-index/src/lib.rs"
click node_changes "https://github.com/bodsink/loci/blob/master/crates/loci-index/src/changes.rs"
click node_hybrid "https://github.com/bodsink/loci/blob/master/crates/loci-index/src/hybrid.rs"
click node_lsp "https://github.com/bodsink/loci/blob/master/crates/loci-lsp/src/client.rs"
click node_graph "https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/schema.rs"
click node_store "https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/store.rs"
click node_query "https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/query.rs"
click node_catalog "https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/catalog.rs"
click node_coverage "https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/coverage.rs"
click node_ui_service "https://github.com/bodsink/loci/blob/master/crates/loci-cli/src/ui.rs"
click node_ui_graph "https://github.com/bodsink/loci/blob/master/crates/loci-cli/src/ui/ui_graph.rs"
click node_web "https://github.com/bodsink/loci/blob/master/crates/loci-cli/web/app.js"

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_walker,node_parser,node_grammars,node_dialect,node_spec,node_resolver,node_imports,node_indexer,node_changes,node_hybrid,node_lsp,node_cursor,node_browser toneBlue
class node_graph,node_store,node_query,node_catalog,node_coverage toneAmber
class node_cli,node_mcp,node_handlers,node_tools,node_freshness,node_journal,node_language_server toneMint
class node_ui_service,node_ui_graph,node_web toneRose
class node_user,node_repository toneIndigo
```

## Components

### Indexing

- [Repository walker](https://github.com/bodsink/loci/blob/master/crates/loci-index/src/walk.rs): `crates/loci-index/src/walk.rs`
- [Language parsing](https://github.com/bodsink/loci/blob/master/crates/loci-parse/src/extract.rs): `crates/loci-parse/src/extract.rs`
- [Grammar registry](https://github.com/bodsink/loci/blob/master/crates/loci-parse/src/registry.rs): `crates/loci-parse/src/registry.rs`
- [Dialect adaptations](https://github.com/bodsink/loci/blob/master/crates/loci-parse/src/dialect.rs): `crates/loci-parse/src/dialect.rs`
- [Language specifications](https://github.com/bodsink/loci/blob/master/crates/loci-parse/src/spec.rs): `crates/loci-parse/src/spec.rs`
- [Edge resolution](https://github.com/bodsink/loci/blob/master/crates/loci-index/src/resolve.rs): `crates/loci-index/src/resolve.rs`
- [Import resolution](https://github.com/bodsink/loci/blob/master/crates/loci-index/src/imports.rs): `crates/loci-index/src/imports.rs`
- [Index orchestration](https://github.com/bodsink/loci/blob/master/crates/loci-index/src/lib.rs): `crates/loci-index/src/lib.rs`
- [Change detection](https://github.com/bodsink/loci/blob/master/crates/loci-index/src/changes.rs): `crates/loci-index/src/changes.rs`
- [Hybrid indexing](https://github.com/bodsink/loci/blob/master/crates/loci-index/src/hybrid.rs): `crates/loci-index/src/hybrid.rs`
- [LSP client](https://github.com/bodsink/loci/blob/master/crates/loci-lsp/src/client.rs): `crates/loci-lsp/src/client.rs`

### Graph engine

- [Graph schema](https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/schema.rs): `crates/loci-graph/src/schema.rs`
- [Persistent graph store](https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/store.rs): `crates/loci-graph/src/store.rs`
- [Graph queries](https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/query.rs): `crates/loci-graph/src/query.rs`
- [Project catalog](https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/catalog.rs): `crates/loci-graph/src/catalog.rs`
- [Index coverage](https://github.com/bodsink/loci/blob/master/crates/loci-graph/src/coverage.rs): `crates/loci-graph/src/coverage.rs`

### Agent interface

- [CLI commands](https://github.com/bodsink/loci/blob/master/crates/loci-cli/src/main.rs): `crates/loci-cli/src/main.rs`
- [MCP server](https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/lib.rs): `crates/loci-mcp/src/lib.rs`
- [Tool handlers](https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/handlers.rs): `crates/loci-mcp/src/handlers.rs`
- [Tool definitions](https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/tools.rs): `crates/loci-mcp/src/tools.rs`
- [Freshness checks](https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/freshness.rs): `crates/loci-mcp/src/freshness.rs`
- [Usage journal](https://github.com/bodsink/loci/blob/master/crates/loci-mcp/src/journal.rs): `crates/loci-mcp/src/journal.rs`

### Local web UI

- [UI service](https://github.com/bodsink/loci/blob/master/crates/loci-cli/src/ui.rs): `crates/loci-cli/src/ui.rs`
- [Graph views](https://github.com/bodsink/loci/blob/master/crates/loci-cli/src/ui/ui_graph.rs): `crates/loci-cli/src/ui/ui_graph.rs`
- [Browser UI](https://github.com/bodsink/loci/blob/master/crates/loci-cli/web/app.js): `crates/loci-cli/web/app.js`

### Other components

- **Engineer or agent**
- **Source repository**
- **Cursor / MCP client**
- **Web browser**
- **Language server**

## Connections

- Engineer or agent → CLI commands: runs commands
- Engineer or agent → Cursor / MCP client: asks questions
- Cursor / MCP client → MCP server: starts stdio server
- MCP server → Tool definitions: registers tools (evidence: `crates/loci-mcp/src/lib.rs`)
- MCP server → Tool handlers: dispatches calls (evidence: `crates/loci-mcp/src/lib.rs`)
- Tool handlers → Index orchestration: indexes projects (evidence: `crates/loci-mcp/src/handlers.rs`)
- CLI commands → Index orchestration: indexes projects (evidence: `crates/loci-cli/src/main.rs`)
- Index orchestration → Repository walker: walks files (evidence: `crates/loci-index/src/lib.rs`)
- Index orchestration → Language parsing: parses changed files (evidence: `crates/loci-index/src/lib.rs`)
- Language parsing → Grammar registry: selects grammar (evidence: `crates/loci-parse/src/extract.rs`)
- Language parsing → Dialect adaptations: adapts syntax (evidence: `crates/loci-parse/src/dialect.rs`)
- Language parsing → Language specifications: uses language rules (evidence: `crates/loci-parse/src/extract.rs`)
- Index orchestration → Edge resolution: rebuilds edges (evidence: `crates/loci-index/src/lib.rs`)
- Edge resolution → Import resolution: resolves imports
- Index orchestration → Change detection: detects changes (evidence: `crates/loci-index/src/lib.rs`)
- Index orchestration → Hybrid indexing: adds LSP evidence (evidence: `crates/loci-index/src/lib.rs`)
- Hybrid indexing → LSP client: requests definitions
- LSP client → Language server: sends LSP requests (evidence: `crates/loci-lsp/src/client.rs`)
- Index orchestration → Persistent graph store: writes graph
- Persistent graph store → Graph schema: stores schema records (evidence: `crates/loci-graph/src/store.rs`)
- Tool handlers → Graph queries: runs graph queries (evidence: `crates/loci-mcp/src/handlers.rs`)
- Graph queries → Persistent graph store: reads graph (evidence: `crates/loci-graph/src/query.rs`)
- Tool handlers → Index coverage: reports coverage
- Tool handlers → Freshness checks: checks freshness
- Tool handlers → Usage journal: records tool calls
- CLI commands → Usage journal: summarizes usage (evidence: `crates/loci-cli/src/main.rs`)
- CLI commands → UI service: starts UI (evidence: `crates/loci-cli/src/main.rs`)
- UI service → Graph views: serves graph views (evidence: `crates/loci-cli/src/ui.rs`)
- UI service → Browser UI: serves browser assets
- Browser UI → Web browser: renders interface
- Graph views → Persistent graph store: reads graph
- Source repository → Index orchestration: provides source
- Tool handlers → Project catalog: uses project catalog
