# kesavaai/modus-ai-intelligence-graph architecture

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

- Interactive diagram: https://gitdiagram.com/kesavaai/modus-ai-intelligence-graph
- Repository: https://github.com/kesavaai/modus-ai-intelligence-graph

## Overview

This is a workforce-impact intelligence application: users explore process-to-activity-to-role-to-skill relationships, inspect automation and payroll exposure, and review reskilling pathways; they can also submit business text for extraction and graph persistence. The frontend includes local JSON-backed serverless routes alongside a FastAPI/Neo4j backend, so these are shown as separate paths rather than assumed to be wired together. Backend pipeline details are based on sampled excerpts; other capabilities are included where documented.

Main entry points: [`frontend/src/app/page.tsx`](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/page.tsx) (Dashboard), [`backend/app/api/routes.py`](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/api/routes.py) (Backend API routes), [`backend/app/main.py`](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/main.py) (FastAPI application), [`backend/app/core/neo4j_client.py`](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/core/neo4j_client.py) (Graph client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["User experience"]
  node_app["Dashboard<br/>[page.tsx]"]
  node_canvas["Graph canvas<br/>[GraphCanvas.tsx]"]
  node_analytics["BI analytics"]
  node_ingest_modal["Ingestion modal"]
  node_impact_drawer["Impact drawer"]
end

subgraph group_frontend_api["Frontend routes"]
  node_graph_route["Graph route<br/>[route.ts]"]
  node_graph_json["Bundled graph data<br/>[graph_db.json]"]
  node_cascade_route["Cascade route<br/>[route.ts]"]
  node_ingest_route["Ingest route<br/>[route.ts]"]
  node_health_route["Health route<br/>[route.ts]"]
end

subgraph group_backend_api["Backend services"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_api_routes["Backend API routes<br/>[routes.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_graph_engine["Graph and extraction"]
  node_pipeline["Extraction pipeline"]
  node_graph_client["Graph client<br/>[neo4j_client.py]"]
  node_neo4j[("Neo4j graph store")]
  node_seed_data["Seed processes<br/>[seed_data.json]"]
end

node_user(("Enterprise user"))
node_groq{{"Groq language model"}}

node_user -->|"uses"| node_app
node_app -->|"requests graph"| node_graph_route
node_graph_route -->|"reads"| node_graph_json
node_graph_route -->|"returns graph"| node_app
node_app -->|"renders graph"| node_canvas
node_app -->|"shows analytics"| node_analytics
node_app -->|"opens impact"| node_impact_drawer
node_impact_drawer -->|"requests impact"| node_cascade_route
node_cascade_route -->|"reads"| node_graph_json
node_user -->|"submits text"| node_ingest_modal
node_ingest_modal -->|"posts process"| node_ingest_route
node_app -->|"checks status"| node_health_route
node_user -->|"API requests"| node_fastapi
node_fastapi -->|"dispatches"| node_api_routes
node_api_routes -->|"validates"| node_schemas
node_api_routes -->|"runs extraction"| node_pipeline
node_pipeline -.->|"extracts entities"| node_groq
node_pipeline -->|"persists result"| node_graph_client
node_api_routes -->|"queries graph"| node_graph_client
node_fastapi -->|"connects and closes"| node_graph_client
node_fastapi -->|"loads on startup"| node_seed_data
node_api_routes -->|"loads on seed request"| node_seed_data
node_graph_client -->|"reads and writes"| node_neo4j

click node_app "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/page.tsx"
click node_canvas "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/components/GraphCanvas.tsx"
click node_analytics "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/components/BiAnalyticsDashboard.tsx"
click node_ingest_modal "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/components/SurpriseRecordModal.tsx"
click node_impact_drawer "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/components/CascadeImpactDrawer.tsx"
click node_graph_route "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/api/v1/graph/all/route.ts"
click node_graph_json "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/data/graph_db.json"
click node_cascade_route "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/api/v1/intelligence/cascade/route.ts"
click node_ingest_route "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/api/v1/process/ingest/route.ts"
click node_health_route "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/api/v1/health/route.ts"
click node_fastapi "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/main.py"
click node_api_routes "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/api/routes.py"
click node_schemas "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/models/schemas.py"
click node_pipeline "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/workflows/extraction_pipeline.py"
click node_graph_client "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/core/neo4j_client.py"
click node_seed_data "https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/seed_data.json"

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_app,node_canvas,node_analytics,node_ingest_modal,node_impact_drawer,node_user toneBlue
class node_graph_route,node_graph_json,node_cascade_route,node_ingest_route,node_health_route toneAmber
class node_fastapi,node_api_routes,node_schemas toneMint
class node_pipeline,node_graph_client,node_neo4j,node_seed_data toneRose
class node_groq toneIndigo
```

## Components

### User experience

- [Dashboard](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Graph canvas](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/components/GraphCanvas.tsx): `frontend/src/components/GraphCanvas.tsx`
- [BI analytics](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/components/BiAnalyticsDashboard.tsx): `frontend/src/components/BiAnalyticsDashboard.tsx`
- [Ingestion modal](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/components/SurpriseRecordModal.tsx): `frontend/src/components/SurpriseRecordModal.tsx`
- [Impact drawer](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/components/CascadeImpactDrawer.tsx): `frontend/src/components/CascadeImpactDrawer.tsx`

### Frontend routes

- [Graph route](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/api/v1/graph/all/route.ts): `frontend/src/app/api/v1/graph/all/route.ts`
- [Bundled graph data](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/data/graph_db.json): `frontend/src/data/graph_db.json`
- [Cascade route](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/api/v1/intelligence/cascade/route.ts): `frontend/src/app/api/v1/intelligence/cascade/route.ts`
- [Ingest route](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/api/v1/process/ingest/route.ts): `frontend/src/app/api/v1/process/ingest/route.ts`
- [Health route](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/frontend/src/app/api/v1/health/route.ts): `frontend/src/app/api/v1/health/route.ts`

### Backend services

- [FastAPI application](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/main.py): `backend/app/main.py`
- [Backend API routes](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/api/routes.py): `backend/app/api/routes.py`
- [API schemas](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/models/schemas.py): `backend/app/models/schemas.py`

### Graph and extraction

- [Extraction pipeline](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/workflows/extraction_pipeline.py): `backend/app/workflows/extraction_pipeline.py`
- [Graph client](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/app/core/neo4j_client.py): `backend/app/core/neo4j_client.py`
- **Neo4j graph store**
- [Seed processes](https://github.com/kesavaai/modus-ai-intelligence-graph/blob/master/backend/seed_data.json): `backend/seed_data.json`

### Other components

- **Enterprise user**
- **Groq language model**

## Connections

- Enterprise user → Dashboard: uses
- Dashboard → Graph route: requests graph
- Graph route → Bundled graph data: reads
- Graph route → Dashboard: returns graph
- Dashboard → Graph canvas: renders graph
- Dashboard → BI analytics: shows analytics
- Dashboard → Impact drawer: opens impact
- Impact drawer → Cascade route: requests impact
- Cascade route → Bundled graph data: reads
- Enterprise user → Ingestion modal: submits text
- Ingestion modal → Ingest route: posts process
- Dashboard → Health route: checks status
- Enterprise user → FastAPI application: API requests
- FastAPI application → Backend API routes: dispatches
- Backend API routes → API schemas: validates
- Backend API routes → Extraction pipeline: runs extraction
- Extraction pipeline → Groq language model: extracts entities
- Extraction pipeline → Graph client: persists result
- Backend API routes → Graph client: queries graph
- FastAPI application → Graph client: connects and closes
- FastAPI application → Seed processes: loads on startup
- Backend API routes → Seed processes: loads on seed request
- Graph client → Neo4j graph store: reads and writes