# issahammoud/codiff architecture

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

- Interactive diagram: https://gitdiagram.com/issahammoud/codiff
- Repository: https://github.com/issahammoud/codiff

## Overview

codiff is an offline structural call-graph diff tool for Python and TypeScript repositories. A user runs the CLI, which ensures a persistent index, builds base and head snapshots, computes and analyzes their graph delta, then renders terminal, Mermaid, or JSON output. Parsing dispatches through language-specific parsers and resolvers. The product also documents GitHub Action and coding-agent/MCP integrations. Relationships below are based on the README and SOURCE INDEX references; unsampled implementation details are represented only where documented.

Main entry points: [`codiff/cli.py`](https://github.com/issahammoud/codiff/blob/main/codiff/cli.py) (CLI), [`codiff/diff/engine.py`](https://github.com/issahammoud/codiff/blob/main/codiff/diff/engine.py) (Diff orchestration), [`codiff/languages/repository.py`](https://github.com/issahammoud/codiff/blob/main/codiff/languages/repository.py) (Repository parser), [`codiff/diff/indexer.py`](https://github.com/issahammoud/codiff/blob/main/codiff/diff/indexer.py) (Indexing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[cli.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_setup["Agent setup<br/>[setup.py]"]
end

subgraph group_index["Index and snapshots"]
  node_indexer["Indexing<br/>[indexer.py]"]
  node_snapshot["Snapshots<br/>[snapshot.py]"]
  node_dbops["Index operations<br/>[operations.py]"]
  node_dbengine["SQLite engine<br/>[engine.py]"]
  node_dbmodels["Database models<br/>[models.py]"]
  node_gitutils["Git utilities<br/>[git.py]"]
  node_files["File utilities<br/>[files.py]"]
end

subgraph group_parse["Language analysis"]
  node_repository["Repository parser<br/>[repository.py]"]
  node_languageparser["Parser framework<br/>[parser.py]"]
  node_pythonparser["Python parser<br/>[parser.py]"]
  node_pythonresolver["Python resolver<br/>[resolver.py]"]
  node_typescriptparser["TypeScript parser<br/>[parser.py]"]
  node_typescriptresolver["TypeScript resolver<br/>[resolver.py]"]
  node_resolver["Shared resolver<br/>[resolver.py]"]
  node_parsing_schema["Parse structures<br/>[parsing.py]"]
end

subgraph group_diff["Graph diff"]
  node_diffengine["Diff orchestration<br/>[engine.py]"]
  node_diffschema["Graph snapshots and deltas<br/>[diff.py]"]
  node_differ["Snapshot differ<br/>[differ.py]"]
  node_analysis["Change analysis<br/>[analysis.py]"]
end

subgraph group_integrations["Integrations and output"]
  node_json["JSON export<br/>[json.py]"]
  node_mermaid["Mermaid export<br/>[mermaid.py]"]
  node_terminal["Terminal export<br/>[terminal.py]"]
end

node_developer(("Developer"))
node_github(("GitHub Action"))
node_agent(("Coding agent"))

node_developer -->|"runs"| node_cli
node_github -.->|"invokes diff"| node_cli
node_agent -.->|"requests diffs"| node_mcp
node_cli -->|"computes diff"| node_diffengine
node_cli -->|"indexes repository"| node_indexer
node_cli -->|"configures agent"| node_setup
node_mcp -->|"computes diff"| node_diffengine
node_indexer -->|"builds snapshots"| node_snapshot
node_indexer -->|"updates index"| node_dbops
node_indexer -->|"checks refs"| node_gitutils
node_snapshot -->|"parses repository"| node_repository
node_snapshot -->|"loads snapshot"| node_dbops
node_dbops -->|"creates sessions"| node_dbengine
node_dbengine -->|"creates tables"| node_dbmodels
node_repository -->|"dispatches parsing"| node_languageparser
node_repository -->|"dispatches Python"| node_pythonparser
node_repository -->|"dispatches TypeScript"| node_typescriptparser
node_repository -->|"resolves calls"| node_pythonresolver
node_repository -->|"resolves calls"| node_typescriptresolver
node_languageparser -->|"emits chunks"| node_parsing_schema
node_pythonparser -->|"emits chunks"| node_parsing_schema
node_typescriptparser -->|"emits chunks"| node_parsing_schema
node_pythonresolver -->|"uses base resolver"| node_resolver
node_typescriptresolver -->|"uses base resolver"| node_resolver
node_diffengine -->|"ensures indexed"| node_indexer
node_diffengine -->|"builds snapshots"| node_snapshot
node_diffengine -->|"compares snapshots"| node_differ
node_diffengine -->|"analyzes delta"| node_analysis
node_diffengine -->|"filters tests"| node_files
node_differ -->|"produces graph delta"| node_diffschema
node_analysis -->|"consumes graph delta"| node_diffschema
node_cli -->|"exports JSON"| node_json
node_cli -->|"exports Mermaid"| node_mermaid
node_cli -->|"renders terminal"| node_terminal
node_json -->|"serializes results"| node_diffschema
node_mermaid -->|"renders results"| node_diffschema
node_terminal -->|"renders results"| node_diffschema

click node_cli "https://github.com/issahammoud/codiff/blob/main/codiff/cli.py"
click node_mcp "https://github.com/issahammoud/codiff/blob/main/codiff/mcp_server.py"
click node_setup "https://github.com/issahammoud/codiff/blob/main/codiff/setup.py"
click node_indexer "https://github.com/issahammoud/codiff/blob/main/codiff/diff/indexer.py"
click node_snapshot "https://github.com/issahammoud/codiff/blob/main/codiff/diff/snapshot.py"
click node_dbops "https://github.com/issahammoud/codiff/blob/main/codiff/db/operations.py"
click node_dbengine "https://github.com/issahammoud/codiff/blob/main/codiff/db/engine.py"
click node_dbmodels "https://github.com/issahammoud/codiff/blob/main/codiff/db/models.py"
click node_repository "https://github.com/issahammoud/codiff/blob/main/codiff/languages/repository.py"
click node_languageparser "https://github.com/issahammoud/codiff/blob/main/codiff/languages/parser.py"
click node_pythonparser "https://github.com/issahammoud/codiff/blob/main/codiff/languages/python/parser.py"
click node_pythonresolver "https://github.com/issahammoud/codiff/blob/main/codiff/languages/python/resolver.py"
click node_typescriptparser "https://github.com/issahammoud/codiff/blob/main/codiff/languages/typescript/parser.py"
click node_typescriptresolver "https://github.com/issahammoud/codiff/blob/main/codiff/languages/typescript/resolver.py"
click node_resolver "https://github.com/issahammoud/codiff/blob/main/codiff/languages/resolver.py"
click node_parsing_schema "https://github.com/issahammoud/codiff/blob/main/codiff/schema/parsing.py"
click node_gitutils "https://github.com/issahammoud/codiff/blob/main/codiff/utils/git.py"
click node_files "https://github.com/issahammoud/codiff/blob/main/codiff/utils/files.py"
click node_diffengine "https://github.com/issahammoud/codiff/blob/main/codiff/diff/engine.py"
click node_diffschema "https://github.com/issahammoud/codiff/blob/main/codiff/schema/diff.py"
click node_differ "https://github.com/issahammoud/codiff/blob/main/codiff/diff/differ.py"
click node_analysis "https://github.com/issahammoud/codiff/blob/main/codiff/diff/analysis.py"
click node_json "https://github.com/issahammoud/codiff/blob/main/codiff/export/json.py"
click node_mermaid "https://github.com/issahammoud/codiff/blob/main/codiff/export/mermaid.py"
click node_terminal "https://github.com/issahammoud/codiff/blob/main/codiff/export/terminal.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_cli,node_mcp,node_setup toneBlue
class node_indexer,node_snapshot,node_dbops,node_dbengine,node_dbmodels,node_gitutils,node_files toneAmber
class node_repository,node_languageparser,node_pythonparser,node_pythonresolver,node_typescriptparser,node_typescriptresolver,node_resolver,node_parsing_schema toneMint
class node_diffengine,node_diffschema,node_differ,node_analysis toneRose
class node_json,node_mermaid,node_terminal,node_developer,node_github,node_agent toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/issahammoud/codiff/blob/main/codiff/cli.py): `codiff/cli.py`
- [MCP server](https://github.com/issahammoud/codiff/blob/main/codiff/mcp_server.py): `codiff/mcp_server.py`
- [Agent setup](https://github.com/issahammoud/codiff/blob/main/codiff/setup.py): `codiff/setup.py`

### Index and snapshots

- [Indexing](https://github.com/issahammoud/codiff/blob/main/codiff/diff/indexer.py): `codiff/diff/indexer.py`
- [Snapshots](https://github.com/issahammoud/codiff/blob/main/codiff/diff/snapshot.py): `codiff/diff/snapshot.py`
- [Index operations](https://github.com/issahammoud/codiff/blob/main/codiff/db/operations.py): `codiff/db/operations.py`
- [SQLite engine](https://github.com/issahammoud/codiff/blob/main/codiff/db/engine.py): `codiff/db/engine.py`
- [Database models](https://github.com/issahammoud/codiff/blob/main/codiff/db/models.py): `codiff/db/models.py`
- [Git utilities](https://github.com/issahammoud/codiff/blob/main/codiff/utils/git.py): `codiff/utils/git.py`
- [File utilities](https://github.com/issahammoud/codiff/blob/main/codiff/utils/files.py): `codiff/utils/files.py`

### Language analysis

- [Repository parser](https://github.com/issahammoud/codiff/blob/main/codiff/languages/repository.py): `codiff/languages/repository.py`
- [Parser framework](https://github.com/issahammoud/codiff/blob/main/codiff/languages/parser.py): `codiff/languages/parser.py`
- [Python parser](https://github.com/issahammoud/codiff/blob/main/codiff/languages/python/parser.py): `codiff/languages/python/parser.py`
- [Python resolver](https://github.com/issahammoud/codiff/blob/main/codiff/languages/python/resolver.py): `codiff/languages/python/resolver.py`
- [TypeScript parser](https://github.com/issahammoud/codiff/blob/main/codiff/languages/typescript/parser.py): `codiff/languages/typescript/parser.py`
- [TypeScript resolver](https://github.com/issahammoud/codiff/blob/main/codiff/languages/typescript/resolver.py): `codiff/languages/typescript/resolver.py`
- [Shared resolver](https://github.com/issahammoud/codiff/blob/main/codiff/languages/resolver.py): `codiff/languages/resolver.py`
- [Parse structures](https://github.com/issahammoud/codiff/blob/main/codiff/schema/parsing.py): `codiff/schema/parsing.py`

### Graph diff

- [Diff orchestration](https://github.com/issahammoud/codiff/blob/main/codiff/diff/engine.py): `codiff/diff/engine.py`
- [Graph snapshots and deltas](https://github.com/issahammoud/codiff/blob/main/codiff/schema/diff.py): `codiff/schema/diff.py`
- [Snapshot differ](https://github.com/issahammoud/codiff/blob/main/codiff/diff/differ.py): `codiff/diff/differ.py`
- [Change analysis](https://github.com/issahammoud/codiff/blob/main/codiff/diff/analysis.py): `codiff/diff/analysis.py`

### Integrations and output

- [JSON export](https://github.com/issahammoud/codiff/blob/main/codiff/export/json.py): `codiff/export/json.py`
- [Mermaid export](https://github.com/issahammoud/codiff/blob/main/codiff/export/mermaid.py): `codiff/export/mermaid.py`
- [Terminal export](https://github.com/issahammoud/codiff/blob/main/codiff/export/terminal.py): `codiff/export/terminal.py`

### Other components

- **Developer**
- **GitHub Action**
- **Coding agent**

## Connections

- Developer → CLI: runs (evidence: `README.md`)
- GitHub Action → CLI: invokes diff (evidence: `README.md`)
- Coding agent → MCP server: requests diffs (evidence: `README.md`)
- CLI → Diff orchestration: computes diff (evidence: `codiff/cli.py`)
- CLI → Indexing: indexes repository (evidence: `codiff/cli.py`)
- CLI → Agent setup: configures agent (evidence: `codiff/cli.py`)
- MCP server → Diff orchestration: computes diff (evidence: `codiff/mcp_server.py`)
- Indexing → Snapshots: builds snapshots (evidence: `codiff/diff/indexer.py`)
- Indexing → Index operations: updates index (evidence: `codiff/diff/indexer.py`)
- Indexing → Git utilities: checks refs (evidence: `codiff/diff/indexer.py`)
- Snapshots → Repository parser: parses repository (evidence: `codiff/diff/snapshot.py`)
- Snapshots → Index operations: loads snapshot (evidence: `codiff/diff/snapshot.py`)
- Index operations → SQLite engine: creates sessions (evidence: `codiff/db/operations.py`)
- SQLite engine → Database models: creates tables (evidence: `codiff/db/engine.py`)
- Repository parser → Parser framework: dispatches parsing (evidence: `codiff/languages/repository.py`)
- Repository parser → Python parser: dispatches Python (evidence: `codiff/languages/repository.py`)
- Repository parser → TypeScript parser: dispatches TypeScript (evidence: `codiff/languages/repository.py`)
- Repository parser → Python resolver: resolves calls (evidence: `codiff/languages/repository.py`)
- Repository parser → TypeScript resolver: resolves calls (evidence: `codiff/languages/repository.py`)
- Parser framework → Parse structures: emits chunks (evidence: `codiff/languages/parser.py`)
- Python parser → Parse structures: emits chunks (evidence: `codiff/languages/python/parser.py`)
- TypeScript parser → Parse structures: emits chunks (evidence: `codiff/languages/typescript/parser.py`)
- Python resolver → Shared resolver: uses base resolver (evidence: `codiff/languages/python/resolver.py`)
- TypeScript resolver → Shared resolver: uses base resolver (evidence: `codiff/languages/typescript/resolver.py`)
- Diff orchestration → Indexing: ensures indexed (evidence: `codiff/diff/engine.py`)
- Diff orchestration → Snapshots: builds snapshots (evidence: `codiff/diff/engine.py`)
- Diff orchestration → Snapshot differ: compares snapshots (evidence: `codiff/diff/engine.py`)
- Diff orchestration → Change analysis: analyzes delta (evidence: `codiff/diff/engine.py`)
- Diff orchestration → File utilities: filters tests (evidence: `codiff/diff/engine.py`)
- Snapshot differ → Graph snapshots and deltas: produces graph delta (evidence: `codiff/diff/differ.py`)
- Change analysis → Graph snapshots and deltas: consumes graph delta (evidence: `codiff/diff/analysis.py`)
- CLI → JSON export: exports JSON (evidence: `codiff/cli.py`)
- CLI → Mermaid export: exports Mermaid
- CLI → Terminal export: renders terminal
- JSON export → Graph snapshots and deltas: serializes results (evidence: `codiff/export/json.py`)
- Mermaid export → Graph snapshots and deltas: renders results (evidence: `codiff/export/mermaid.py`)
- Terminal export → Graph snapshots and deltas: renders results (evidence: `codiff/export/terminal.py`)
