# ganeshreddy-nxtwave/academic-intelligence- architecture

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

- Interactive diagram: https://gitdiagram.com/ganeshreddy-nxtwave/academic-intelligence-
- Repository: https://github.com/ganeshreddy-nxtwave/academic-intelligence-

## Overview

AIP is a Streamlit academic-data intelligence product: users explore linked university, planning, delivery, content, feedback, and instructor data, or ask questions answered by an SQL-generating chat agent. Canonical domain tables are assembled into DuckDB tables and join-ready views; the app also exposes GRIT readiness analytics and a data-pipeline overview, with an MCP server as another database-backed interface. The excerpts establish the app routing, agent safeguards, and parts of the data/UI wiring; other domain relationships below rely on README documentation.

Main entry points: [`app.py`](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/app.py) (Page router), [`data/canonical`](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical) (Canonical tables), [`scripts/load_duckdb.py`](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/scripts/load_duckdb.py) (Store builder), [`views/chat.py`](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/views/chat.py) (Chat page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Dashboard experience"]
  node_router["Page router<br/>[app.py]"]
  node_shared["Shared dashboard<br/>[dashboard.py]"]
  node_chat["Chat page<br/>[chat.py]"]
  node_knowledge["Knowledge explorer<br/>[knowledge_base.py]"]
  node_grit["GRIT analytics<br/>[grit.py]"]
  node_pipeline["Pipeline overview<br/>[pipeline.py]"]
end

subgraph group_query["Query and storage"]
  node_agent["SQL chat agent<br/>[agent.py]"]
  node_guard["Read-only SQL<br/>[db.py]"]
  node_store[("DuckDB store")]
  node_loader["Store builder<br/>[load_duckdb.py]"]
end

subgraph group_domains["Academic data"]
  node_canonical[("Canonical tables")]
  node_derived["Join-ready views<br/>[load_duckdb.py]"]
  node_planning["Academic planning"]
  node_delivery["Session delivery"]
  node_learning["Subjects and content"]
  node_outcomes["Feedback and instructors"]
  node_gritdata["GRIT attempts"]
end

subgraph group_integrations["Interfaces"]
  node_openrouter["OpenRouter API"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_export["Answer export<br/>[export.py]"]
end

node_user(("Academic user"))

node_user -->|"opens app"| node_router
node_router -->|"checks login"| node_shared
node_router -->|"routes to"| node_chat
node_router -->|"routes to"| node_knowledge
node_router -->|"routes to"| node_grit
node_router -->|"routes to"| node_pipeline
node_chat -->|"asks questions"| node_agent
node_agent -->|"runs SQL"| node_guard
node_guard -->|"queries read-only"| node_store
node_agent -->|"calls model"| node_openrouter
node_chat -->|"exports answers"| node_export
node_shared -->|"builds store"| node_loader
node_loader -->|"loads tables"| node_canonical
node_loader -->|"assembles"| node_store
node_loader -->|"creates views"| node_derived
node_knowledge -->|"explores joins"| node_derived
node_grit -->|"reads analytics"| node_derived
node_pipeline -->|"gets counts"| node_shared
node_canonical -->|"includes plans"| node_planning
node_canonical -->|"includes sessions"| node_delivery
node_canonical -->|"includes taxonomy"| node_learning
node_canonical -->|"includes feedback"| node_outcomes
node_canonical -->|"includes attempts"| node_gritdata
node_mcp -->|"queries through"| node_guard

click node_router "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/app.py"
click node_shared "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/aip/dashboard.py"
click node_chat "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/views/chat.py"
click node_knowledge "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/views/knowledge_base.py"
click node_grit "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/views/grit.py"
click node_pipeline "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/views/pipeline.py"
click node_agent "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/aip/agent.py"
click node_guard "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/aip/db.py"
click node_loader "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/scripts/load_duckdb.py"
click node_canonical "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical"
click node_derived "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/scripts/load_duckdb.py"
click node_planning "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/planning"
click node_delivery "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/delivery"
click node_learning "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/content"
click node_outcomes "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/feedback"
click node_gritdata "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/grit"
click node_mcp "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/mcp_server.py"
click node_export "https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/aip/export.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_router,node_shared,node_chat,node_knowledge,node_grit,node_pipeline,node_user toneBlue
class node_agent,node_guard,node_store,node_loader toneAmber
class node_canonical,node_derived,node_planning,node_delivery,node_learning,node_outcomes,node_gritdata toneMint
class node_openrouter,node_mcp,node_export toneRose
```

## Components

### Dashboard experience

- [Page router](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/app.py): `app.py`
- [Shared dashboard](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/aip/dashboard.py): `aip/dashboard.py`
- [Chat page](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/views/chat.py): `views/chat.py`
- [Knowledge explorer](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/views/knowledge_base.py): `views/knowledge_base.py`
- [GRIT analytics](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/views/grit.py): `views/grit.py`
- [Pipeline overview](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/views/pipeline.py): `views/pipeline.py`

### Query and storage

- [SQL chat agent](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/aip/agent.py): `aip/agent.py`
- [Read-only SQL](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/aip/db.py): `aip/db.py`
- **DuckDB store**
- [Store builder](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/scripts/load_duckdb.py): `scripts/load_duckdb.py`

### Academic data

- [Canonical tables](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical): `data/canonical`
- [Join-ready views](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/scripts/load_duckdb.py): `scripts/load_duckdb.py`
- [Academic planning](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/planning): `data/canonical/planning`
- [Session delivery](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/delivery): `data/canonical/delivery`
- [Subjects and content](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/content): `data/canonical/content`
- [Feedback and instructors](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/feedback): `data/canonical/feedback`
- [GRIT attempts](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/tree/main/data/canonical/grit): `data/canonical/grit`

### Interfaces

- **OpenRouter API**
- [MCP server](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/mcp_server.py): `mcp_server.py`
- [Answer export](https://github.com/ganeshreddy-nxtwave/academic-intelligence-/blob/main/aip/export.py): `aip/export.py`

### Other components

- **Academic user**

## Connections

- Academic user → Page router: opens app (evidence: `README.md`)
- Page router → Shared dashboard: checks login (evidence: `app.py`)
- Page router → Chat page: routes to (evidence: `app.py`)
- Page router → Knowledge explorer: routes to (evidence: `app.py`)
- Page router → GRIT analytics: routes to (evidence: `app.py`)
- Page router → Pipeline overview: routes to (evidence: `app.py`)
- Chat page → SQL chat agent: asks questions (evidence: `views/chat.py`)
- SQL chat agent → Read-only SQL: runs SQL (evidence: `aip/agent.py`)
- Read-only SQL → DuckDB store: queries read-only (evidence: `aip/db.py`)
- SQL chat agent → OpenRouter API: calls model (evidence: `README.md`)
- Chat page → Answer export: exports answers (evidence: `views/chat.py`)
- Shared dashboard → Store builder: builds store (evidence: `aip/dashboard.py`)
- Store builder → Canonical tables: loads tables (evidence: `README.md`)
- Store builder → DuckDB store: assembles (evidence: `README.md`)
- Store builder → Join-ready views: creates views (evidence: `scripts/load_duckdb.py`)
- Knowledge explorer → Join-ready views: explores joins (evidence: `views/knowledge_base.py`)
- GRIT analytics → Join-ready views: reads analytics (evidence: `views/grit.py`)
- Pipeline overview → Shared dashboard: gets counts (evidence: `views/pipeline.py`)
- Canonical tables → Academic planning: includes plans (evidence: `README.md`)
- Canonical tables → Session delivery: includes sessions (evidence: `README.md`)
- Canonical tables → Subjects and content: includes taxonomy (evidence: `README.md`)
- Canonical tables → Feedback and instructors: includes feedback (evidence: `README.md`)
- Canonical tables → GRIT attempts: includes attempts (evidence: `README.md`)
- MCP server → Read-only SQL: queries through (evidence: `mcp_server.py`)