# aashutosh-mahajan/prism architecture

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

- Interactive diagram: https://gitdiagram.com/aashutosh-mahajan/prism
- Repository: https://github.com/aashutosh-mahajan/prism

## Overview

PRISM is a local, deterministic codebase index and context service for coding agents. Its principal workflow scans and parses a repository, derives symbols, dependency graphs and health signals, writes persistent artifacts, then serves budgeted search, location, context and impact results through CLI or MCP. Separate product branches generate agent-facing narratives and audit plans, and provide a browser graph viewer with live updates. The README documents the major pipeline and capabilities; some subsystem links below are therefore documented flows rather than inspected call sites.

Main entry points: [`prism/pipeline.py`](https://github.com/aashutosh-mahajan/prism/blob/main/prism/pipeline.py) (Index pipeline), [`prism/writers/manifest.py`](https://github.com/aashutosh-mahajan/prism/blob/main/prism/writers/manifest.py) (Index artifacts), [`prism/navigator/api.py`](https://github.com/aashutosh-mahajan/prism/blob/main/prism/navigator/api.py) (Search and context), [`prism/cli.py`](https://github.com/aashutosh-mahajan/prism/blob/main/prism/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_indexing["Indexing"]
  node_scanner["Source discovery<br/>[scanner.py]"]
  node_parsing["Language parsing<br/>[treesitter.py]"]
  node_pipeline["Index pipeline<br/>[pipeline.py]"]
  node_models["Index data models<br/>[models.py]"]
  node_graphs["Symbols and graphs<br/>[ranking.py]"]
  node_extractors["Domain extractors"]
  node_health["Health and drift"]
  node_lifecycle["Scan and update<br/>[lifecycle.py]"]
end

subgraph group_artifacts["Persistent artifacts"]
  node_artifacts[("Index artifacts<br/>[manifest.py]")]
  node_writer["Stable file writer<br/>[json_writer.py]"]
end

subgraph group_navigation["Agent navigation"]
  node_cli["CLI<br/>[cli.py]"]
  node_mcp["MCP tools<br/>[server.py]"]
  node_store[("Index store<br/>[store.py]")]
  node_navigator["Search and context<br/>[api.py]"]
end

subgraph group_agent_support["Narrative and audit"]
  node_narrator["Brief and summaries<br/>[refresh.py]"]
  node_audit["Audit planning<br/>[plan.py]"]
end

subgraph group_visualization["Graph viewer"]
  node_viewer_server["Viewer HTTP service<br/>[server.py]"]
  node_viewer_app["Viewer state and UI<br/>[app.ts]"]
  node_viewer_data["Viewer data access<br/>[data.ts]"]
  node_viewer_encode["Graph encoding<br/>[encode.ts]"]
  node_viewer_ui["Viewer interactions<br/>[ui.ts]"]
end

node_agent(("Coding agent"))
node_source["Repository source"]

node_agent -->|"requests commands"| node_cli
node_agent -->|"uses tools"| node_mcp
node_source -->|"scans files"| node_scanner
node_scanner -->|"provides files"| node_pipeline
node_pipeline -->|"parses sources"| node_parsing
node_pipeline -->|"builds graphs"| node_graphs
node_pipeline -->|"runs extractors"| node_extractors
node_pipeline -->|"derives health"| node_health
node_pipeline -.->|"produces index"| node_models
node_lifecycle -->|"builds index"| node_pipeline
node_lifecycle -->|"writes artifacts"| node_artifacts
node_artifacts -->|"writes JSON"| node_writer
node_store -->|"reads index"| node_artifacts
node_cli -->|"runs navigation"| node_navigator
node_mcp -->|"calls navigation"| node_navigator
node_navigator -->|"queries index"| node_store
node_navigator -->|"returns context"| node_agent
node_artifacts -->|"supplies index facts"| node_narrator
node_artifacts -->|"supplies audit inputs"| node_audit
node_cli -->|"starts viewer"| node_viewer_server
node_viewer_server -->|"serves viewer data"| node_viewer_data
node_viewer_data -->|"loads graph"| node_viewer_app
node_viewer_app -->|"encodes graph"| node_viewer_encode
node_viewer_app -.->|"renders interactions"| node_viewer_ui

click node_cli "https://github.com/aashutosh-mahajan/prism/blob/main/prism/cli.py"
click node_mcp "https://github.com/aashutosh-mahajan/prism/blob/main/prism/mcp/server.py"
click node_scanner "https://github.com/aashutosh-mahajan/prism/blob/main/prism/discovery/scanner.py"
click node_parsing "https://github.com/aashutosh-mahajan/prism/blob/main/prism/parsing/treesitter.py"
click node_pipeline "https://github.com/aashutosh-mahajan/prism/blob/main/prism/pipeline.py"
click node_models "https://github.com/aashutosh-mahajan/prism/blob/main/prism/core/models.py"
click node_graphs "https://github.com/aashutosh-mahajan/prism/blob/main/prism/graph/ranking.py"
click node_extractors "https://github.com/aashutosh-mahajan/prism/tree/main/prism/extractors"
click node_health "https://github.com/aashutosh-mahajan/prism/tree/main/prism/health"
click node_lifecycle "https://github.com/aashutosh-mahajan/prism/blob/main/prism/lifecycle.py"
click node_artifacts "https://github.com/aashutosh-mahajan/prism/blob/main/prism/writers/manifest.py"
click node_writer "https://github.com/aashutosh-mahajan/prism/blob/main/prism/writers/json_writer.py"
click node_store "https://github.com/aashutosh-mahajan/prism/blob/main/prism/navigator/store.py"
click node_navigator "https://github.com/aashutosh-mahajan/prism/blob/main/prism/navigator/api.py"
click node_narrator "https://github.com/aashutosh-mahajan/prism/blob/main/prism/narrator/refresh.py"
click node_audit "https://github.com/aashutosh-mahajan/prism/blob/main/prism/audit/plan.py"
click node_viewer_server "https://github.com/aashutosh-mahajan/prism/blob/main/prism/viewer/server.py"
click node_viewer_app "https://github.com/aashutosh-mahajan/prism/blob/main/viewer/src/app.ts"
click node_viewer_data "https://github.com/aashutosh-mahajan/prism/blob/main/viewer/src/data.ts"
click node_viewer_encode "https://github.com/aashutosh-mahajan/prism/blob/main/viewer/src/encode.ts"
click node_viewer_ui "https://github.com/aashutosh-mahajan/prism/blob/main/viewer/src/ui.ts"

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_scanner,node_parsing,node_pipeline,node_models,node_graphs,node_extractors,node_health,node_lifecycle toneBlue
class node_artifacts,node_writer toneAmber
class node_cli,node_mcp,node_store,node_navigator toneMint
class node_narrator,node_audit toneRose
class node_viewer_server,node_viewer_app,node_viewer_data,node_viewer_encode,node_viewer_ui,node_agent,node_source toneIndigo
```

## Components

### Indexing

- [Source discovery](https://github.com/aashutosh-mahajan/prism/blob/main/prism/discovery/scanner.py): `prism/discovery/scanner.py`
- [Language parsing](https://github.com/aashutosh-mahajan/prism/blob/main/prism/parsing/treesitter.py): `prism/parsing/treesitter.py`
- [Index pipeline](https://github.com/aashutosh-mahajan/prism/blob/main/prism/pipeline.py): `prism/pipeline.py`
- [Index data models](https://github.com/aashutosh-mahajan/prism/blob/main/prism/core/models.py): `prism/core/models.py`
- [Symbols and graphs](https://github.com/aashutosh-mahajan/prism/blob/main/prism/graph/ranking.py): `prism/graph/ranking.py`
- [Domain extractors](https://github.com/aashutosh-mahajan/prism/tree/main/prism/extractors): `prism/extractors`
- [Health and drift](https://github.com/aashutosh-mahajan/prism/tree/main/prism/health): `prism/health`
- [Scan and update](https://github.com/aashutosh-mahajan/prism/blob/main/prism/lifecycle.py): `prism/lifecycle.py`

### Persistent artifacts

- [Index artifacts](https://github.com/aashutosh-mahajan/prism/blob/main/prism/writers/manifest.py): `prism/writers/manifest.py`
- [Stable file writer](https://github.com/aashutosh-mahajan/prism/blob/main/prism/writers/json_writer.py): `prism/writers/json_writer.py`

### Agent navigation

- [CLI](https://github.com/aashutosh-mahajan/prism/blob/main/prism/cli.py): `prism/cli.py`
- [MCP tools](https://github.com/aashutosh-mahajan/prism/blob/main/prism/mcp/server.py): `prism/mcp/server.py`
- [Index store](https://github.com/aashutosh-mahajan/prism/blob/main/prism/navigator/store.py): `prism/navigator/store.py`
- [Search and context](https://github.com/aashutosh-mahajan/prism/blob/main/prism/navigator/api.py): `prism/navigator/api.py`

### Narrative and audit

- [Brief and summaries](https://github.com/aashutosh-mahajan/prism/blob/main/prism/narrator/refresh.py): `prism/narrator/refresh.py`
- [Audit planning](https://github.com/aashutosh-mahajan/prism/blob/main/prism/audit/plan.py): `prism/audit/plan.py`

### Graph viewer

- [Viewer HTTP service](https://github.com/aashutosh-mahajan/prism/blob/main/prism/viewer/server.py): `prism/viewer/server.py`
- [Viewer state and UI](https://github.com/aashutosh-mahajan/prism/blob/main/viewer/src/app.ts): `viewer/src/app.ts`
- [Viewer data access](https://github.com/aashutosh-mahajan/prism/blob/main/viewer/src/data.ts): `viewer/src/data.ts`
- [Graph encoding](https://github.com/aashutosh-mahajan/prism/blob/main/viewer/src/encode.ts): `viewer/src/encode.ts`
- [Viewer interactions](https://github.com/aashutosh-mahajan/prism/blob/main/viewer/src/ui.ts): `viewer/src/ui.ts`

### Other components

- **Coding agent**
- **Repository source**

## Connections

- Coding agent → CLI: requests commands (evidence: `README.md`)
- Coding agent → MCP tools: uses tools (evidence: `README.md`)
- Repository source → Source discovery: scans files (evidence: `README.md`)
- Source discovery → Index pipeline: provides files (evidence: `README.md`)
- Index pipeline → Language parsing: parses sources (evidence: `README.md`)
- Index pipeline → Symbols and graphs: builds graphs (evidence: `README.md`)
- Index pipeline → Domain extractors: runs extractors (evidence: `prism/pipeline.py`)
- Index pipeline → Health and drift: derives health (evidence: `README.md`)
- Index pipeline → Index data models: produces index (evidence: `prism/pipeline.py`)
- Scan and update → Index pipeline: builds index (evidence: `prism/lifecycle.py`)
- Scan and update → Index artifacts: writes artifacts (evidence: `README.md`)
- Index artifacts → Stable file writer: writes JSON (evidence: `prism/writers/manifest.py`)
- Index store → Index artifacts: reads index (evidence: `prism/navigator/store.py`)
- CLI → Search and context: runs navigation (evidence: `prism/cli.py`)
- MCP tools → Search and context: calls navigation (evidence: `prism/mcp/server.py`)
- Search and context → Index store: queries index (evidence: `prism/navigator/api.py`)
- Search and context → Coding agent: returns context (evidence: `README.md`)
- Index artifacts → Brief and summaries: supplies index facts (evidence: `README.md`)
- Index artifacts → Audit planning: supplies audit inputs (evidence: `prism/audit/plan.py`)
- CLI → Viewer HTTP service: starts viewer (evidence: `prism/cli.py`)
- Viewer HTTP service → Viewer data access: serves viewer data (evidence: `prism/viewer/server.py`)
- Viewer data access → Viewer state and UI: loads graph (evidence: `viewer/src/app.ts`)
- Viewer state and UI → Graph encoding: encodes graph (evidence: `viewer/src/app.ts`)
- Viewer state and UI → Viewer interactions: renders interactions (evidence: `viewer/src/app.ts`)
