# ashik-manjunath/graphify architecture

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

- Interactive diagram: https://gitdiagram.com/ashik-manjunath/graphify
- Repository: https://github.com/ashik-manjunath/graphify

## Overview

#### Purpose and entry points
Graphify is a Python 3.10+ CLI that converts a repository or mixed corpus (code, docs, media, workspace exports, schemas) into a queryable knowledge graph. Primary entry points are `graphify/__main__.py` for the `graphify` command and `python -m graphify`, and `graphify/serve.py` for MCP serving. It produces `graphify-out/graph.json`, `GRAPH_REPORT.md`, and optional browser/call-flow visualizations.

#### Orchestration and graph build
The build flow is coordinated by `graphify/build.py`: discover input, extract nodes and relationships, merge with existing state when requested, cluster the graph, and emit artifacts. `graphify/extract.py` is the headless extraction entry point; `graphify/analyze.py` and `graphify/detect.py` classify files and drive content-specific handling. The important boundary is local structural extraction versus semantic extraction that may invoke an LLM.

#### Local source extraction and resolution
Code is parsed locally, primarily through AST/language extraction, then normalized into graph entities and edges. `graphify/extract.py` owns broad extraction; `graphify/symbol_resolution.py` resolves cross-file/import symbol references; `graphify/semantic_cleanup.py` and `graphify/dedup.py` reconcile duplicate or ambiguous entities. This stage creates the canonical graph vocabulary before reporting, querying, or export.

#### Non-code and external ingestion
Specialized adapters add sources beyond repository code: MCP configurations (`graphify/mcp_ingest.py`), SCIP indexes (`graphify/scip_ingest.py`), PostgreSQL schema introspection (`graphify/pg_introspect.py`), Cargo workspaces (`graphify/cargo_introspect.py`), and Google Workspace shortcuts/content (`graphify/google_workspace.py`). Optional runtimes/services include LLM providers, Ollama, AWS Bedrock, Google Workspace `gws`, PostgreSQL, and graph targets such as Neo4j or FalkorDB.

#### Persistence, incremental updates, and graph composition
`graphify/manifest.py` tracks corpus state for portable/incremental rebuilds, while `graphify/cache.py` stores reusable extraction results. `graphify/affected.py` identifies impact from changes, and `graphify/watch.py` supports continuous synchronization. `graphify/global_graph.py` registers and traverses graphs across projects. These components separate raw extraction state from the generated graph artifact.

#### Enrichment, clustering, and deliverables
`graphify/cluster.py` detects graph communities and supports labeling; `graphify/report.py` generates architecture-oriented findings such as highly connected nodes, cross-cutting relationships, confidence, and suggested questions. `graphify/export.py` produces alternate formats and graph database exports, while `graphify/callflow_html.py` generates the call-flow architecture HTML. Visualization is downstream of graph construction and can be skipped without changing extraction.

#### Consumption and assistant integration
Graph consumers query graph artifacts through CLI-oriented analysis and retrieval in `graphify/querylog.py`, `graphify/analyze.py`, and the MCP server in `graphify/serve.py`, which supports stdio and HTTP with optional API-key protection. `graphify/hooks.py` installs Git hooks for rebuild/merge behavior. Assistant-specific skill and persistent-instruction assets under `graphify/skills/` and `graphify/always_on/` are generated/maintained by `tools/skillgen/gen.py`, enabling query-first behavior across coding-agent platforms.

Main entry points: [`graphify/global_graph.py`](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/global_graph.py) (Cross-project graph), [`graphify/build.py`](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/build.py) (Build orchestrator), [`graphify/extract.py`](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/extract.py) (Structural extraction), [`graphify/analyze.py`](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/analyze.py) (File analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & Control"]
  node_cli["CLI command<br/>Python CLI<br/>[__main__.py]"]
  node_build["Build orchestrator<br/>build pipeline<br/>[build.py]"]
end

subgraph group_extraction["Extraction &amp; Ingestion"]
  node_file_analysis["File analysis<br/>classification<br/>[analyze.py]"]
  node_detection["Content detection<br/>detector<br/>[detect.py]"]
  node_extract["Structural extraction<br/>extractor<br/>[extract.py]"]
  node_symbol_resolution["Symbol resolution<br/>resolver"]
  node_cleanup["Entity reconciliation<br/>normalizer"]
  node_external_ingest["External adapters<br/>ingestion adapters<br/>[mcp_ingest.py]"]
end

subgraph group_state["Graph State"]
  node_manifest["Corpus manifest<br/>incremental state<br/>[manifest.py]"]
  node_cache[("Extraction cache<br/>[cache.py]")]
  node_affected["Change impact<br/>impact analysis<br/>[affected.py]"]
  node_watch["Continuous sync<br/>watcher<br/>[watch.py]"]
  node_global_graph[("Cross-project graph<br/>graph registry<br/>[global_graph.py]")]
end

subgraph group_delivery["Delivery &amp; Consumers"]
  node_cluster["Graph clustering<br/>community detection<br/>[cluster.py]"]
  node_report["Architecture report<br/>report generator<br/>[report.py]"]
  node_export["Graph export<br/>exporter<br/>[export.py]"]
  node_callflow["Call-flow visualization<br/>HTML generator<br/>[callflow_html.py]"]
  node_serve["MCP server<br/>MCP service<br/>[serve.py]"]
end

subgraph group_automation["Agent Automation"]
  node_hooks["Git hooks<br/>Git integration<br/>[hooks.py]"]
  node_skillgen["Skill asset generator<br/>[gen.py]"]
end

node_cli -->|"starts build"| node_build
node_build -->|"discovers and classifies"| node_file_analysis
node_file_analysis -->|"uses"| node_detection
node_file_analysis -->|"routes inputs"| node_extract
node_build -->|"runs"| node_extract
node_external_ingest -->|"adds source entities"| node_extract
node_extract -->|"normalizes references"| node_symbol_resolution
node_symbol_resolution -->|"resolved entities"| node_cleanup
node_cleanup -->|"canonical graph"| node_global_graph
node_manifest -.->|"incremental state"| node_build
node_cache -.->|"reuses results"| node_extract
node_affected -.->|"scopes rebuilds"| node_build
node_watch -->|"change events"| node_affected
node_global_graph -->|"graph topology"| node_cluster
node_cluster -->|"communities"| node_report
node_global_graph -->|"relationships"| node_report
node_global_graph -->|"exports"| node_export
node_global_graph -->|"visualizes"| node_callflow
node_global_graph -->|"queryable artifact"| node_serve
node_hooks -.->|"triggers rebuild behavior"| node_build
node_skillgen -.->|"supports query-first agents"| node_serve

click node_cli "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/__main__.py"
click node_build "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/build.py"
click node_file_analysis "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/analyze.py"
click node_detection "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/detect.py"
click node_extract "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/extract.py"
click node_symbol_resolution "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/symbol_resolution.py"
click node_cleanup "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/semantic_cleanup.py"
click node_external_ingest "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/mcp_ingest.py"
click node_manifest "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/manifest.py"
click node_cache "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/cache.py"
click node_affected "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/affected.py"
click node_watch "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/watch.py"
click node_global_graph "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/global_graph.py"
click node_cluster "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/cluster.py"
click node_report "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/report.py"
click node_export "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/export.py"
click node_callflow "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/callflow_html.py"
click node_serve "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/serve.py"
click node_hooks "https://github.com/ashik-manjunath/graphify/blob/v8/graphify/hooks.py"
click node_skillgen "https://github.com/ashik-manjunath/graphify/blob/v8/tools/skillgen/gen.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_build toneBlue
class node_file_analysis,node_detection,node_extract,node_symbol_resolution,node_cleanup,node_external_ingest toneAmber
class node_manifest,node_cache,node_affected,node_watch,node_global_graph toneMint
class node_cluster,node_report,node_export,node_callflow,node_serve toneRose
class node_hooks,node_skillgen toneIndigo
```

## Components

### Entry & Control

- [CLI command](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/__main__.py): Python CLI · Runs graphify builds and analysis commands. · `graphify/__main__.py`
- [Build orchestrator](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/build.py): build pipeline · Coordinates discovery, extraction, composition, clustering, and artifact emission. · `graphify/build.py`

### Extraction & Ingestion

- [File analysis](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/analyze.py): classification · Classifies inputs and selects content-specific handling. · `graphify/analyze.py`
- [Content detection](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/detect.py): detector · `graphify/detect.py`
- [Structural extraction](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/extract.py): extractor · Headless, local extraction into normalized graph entities and relationships. · `graphify/extract.py`
- [Symbol resolution](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/symbol_resolution.py): resolver · Resolves cross-file and import references. · `graphify/symbol_resolution.py`
- [Entity reconciliation](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/semantic_cleanup.py): normalizer · Cleans semantic ambiguity and deduplicates entities. · `graphify/semantic_cleanup.py`
- [External adapters](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/mcp_ingest.py): ingestion adapters · Imports MCP, SCIP, PostgreSQL, Cargo, and Google Workspace sources. · `graphify/mcp_ingest.py`

### Graph State

- [Corpus manifest](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/manifest.py): incremental state · Tracks portable corpus state for incremental rebuilds. · `graphify/manifest.py`
- [Extraction cache](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/cache.py): cache · Stores reusable extraction results. · `graphify/cache.py`
- [Change impact](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/affected.py): impact analysis · Determines affected graph regions after changes. · `graphify/affected.py`
- [Continuous sync](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/watch.py): watcher · Watches changes and triggers synchronized rebuilds. · `graphify/watch.py`
- [Cross-project graph](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/global_graph.py): graph registry · Registers and traverses graphs across projects. · `graphify/global_graph.py`

### Delivery & Consumers

- [Graph clustering](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/cluster.py): community detection · Finds and labels graph communities. · `graphify/cluster.py`
- [Architecture report](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/report.py): report generator · Produces findings, confidence, and suggested questions. · `graphify/report.py`
- [Graph export](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/export.py): exporter · Writes graph artifacts and graph-database formats. · `graphify/export.py`
- [Call-flow visualization](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/callflow_html.py): HTML generator · Optional downstream call-flow architecture visualization. · `graphify/callflow_html.py`
- [MCP server](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/serve.py): MCP service · Serves graph queries over stdio or HTTP with optional API-key protection. · `graphify/serve.py`

### Agent Automation

- [Git hooks](https://github.com/ashik-manjunath/graphify/blob/v8/graphify/hooks.py): Git integration · Installs rebuild and merge behavior. · `graphify/hooks.py`
- [Skill asset generator](https://github.com/ashik-manjunath/graphify/blob/v8/tools/skillgen/gen.py): generator · Maintains assistant skills and persistent query-first instructions. · `tools/skillgen/gen.py`

## Connections

- CLI command → Build orchestrator: starts build
- Build orchestrator → File analysis: discovers and classifies
- File analysis → Content detection: uses
- File analysis → Structural extraction: routes inputs
- Build orchestrator → Structural extraction: runs
- External adapters → Structural extraction: adds source entities
- Structural extraction → Symbol resolution: normalizes references
- Symbol resolution → Entity reconciliation: resolved entities
- Entity reconciliation → Cross-project graph: canonical graph
- Corpus manifest → Build orchestrator: incremental state
- Extraction cache → Structural extraction: reuses results
- Change impact → Build orchestrator: scopes rebuilds
- Continuous sync → Change impact: change events
- Cross-project graph → Graph clustering: graph topology
- Graph clustering → Architecture report: communities
- Cross-project graph → Architecture report: relationships
- Cross-project graph → Graph export: exports
- Cross-project graph → Call-flow visualization: visualizes
- Cross-project graph → MCP server: queryable artifact
- Git hooks → Build orchestrator: triggers rebuild behavior
- Skill asset generator → MCP server: supports query-first agents