# devabdotolba/univai architecture

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

- Interactive diagram: https://gitdiagram.com/devabdotolba/univai
- Repository: https://github.com/devabdotolba/univai

## Overview

UnivAI turns uploaded textbooks into a scheduled, interactive semester: learners get voiced lectures grounded in book citations, lecture-linked quizzes, proctored exams, and dashboard results. The README documents the main service flow; the sampled Python code confirms the MCP RAG bridge and shared generation contracts, but the application and its major submodules are not sampled here. Their connections are therefore shown only where the README explicitly describes them.

Main entry points: [`UnivAI-Agent`](https://github.com/devabdotolba/univai/tree/main/UnivAI-Agent) (RAG and course generation), [`services/common/rag_client.py`](https://github.com/devabdotolba/univai/blob/main/services/common/rag_client.py) (MCP RAG client), [`services/common/llm.py`](https://github.com/devabdotolba/univai/blob/main/services/common/llm.py) (LLM adapter), [`UnivAI-app`](https://github.com/devabdotolba/univai/tree/main/UnivAI-app) (Web app and API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning experience"]
  node_app["Web app and API"]
  node_dashboard["Learner dashboard"]
  node_admin["Admin controls"]
end

subgraph group_python["Shared services"]
  node_upload["Book indexing bridge<br/>[rag_ingest.py]"]
  node_ragclient["MCP RAG client<br/>[rag_client.py]"]
  node_contracts["Plan contracts<br/>[programme_plan.py]"]
  node_collections["Source contracts"]
  node_orchestrator["Generation state machine"]
  node_llm["LLM adapter<br/>[llm.py]"]
  node_clock["Virtual clock<br/>[clock.py]"]
  node_trace["Tracing and redaction<br/>[tracing.py]"]
  node_inputguard["AI input guard<br/>[input_guard.py]"]
end

subgraph group_brain["Knowledge and generation"]
  node_agent["RAG and course generation"]
end

subgraph group_delivery["Live class and assessment"]
  node_live["Live lecture rooms"]
  node_exam["Exam system"]
  node_proctor["Proctoring reports"]
end

subgraph group_state["Persistent state"]
  node_postgres[("PostgreSQL<br/>[schema.sql]")]
end

node_learner(("Learner"))
node_actor(("Student"))
node_model["Model providers"]

node_actor -->|"uploads book"| node_app
node_app -->|"spawns indexing"| node_upload
node_upload -->|"calls ingest"| node_ragclient
node_ragclient -->|"calls MCP"| node_agent
node_agent -->|"stores course"| node_postgres
node_agent -->|"publishes lectures"| node_live
node_live -->|"hands off course"| node_exam
node_exam -->|"produces reports"| node_proctor
node_exam -->|"returns grades"| node_dashboard
node_dashboard -->|"shows results"| node_actor
node_app -->|"provides controls"| node_admin
node_admin -->|"drives time"| node_clock
node_agent -->|"uses plan contract"| node_contracts
node_agent -->|"uses source contract"| node_collections
node_orchestrator -->|"validates plans"| node_contracts
node_orchestrator -->|"validates collections"| node_collections
node_agent -.->|"generates with"| node_llm
node_llm -->|"requests completion"| node_model
node_ragclient -->|"guards inputs"| node_inputguard
node_llm -->|"guards inputs"| node_inputguard
node_llm -->|"propagates trace"| node_trace
node_ragclient -->|"propagates trace"| node_trace

click node_app "https://github.com/devabdotolba/univai/tree/main/UnivAI-app"
click node_upload "https://github.com/devabdotolba/univai/blob/main/services/rag-tools/rag_ingest.py"
click node_ragclient "https://github.com/devabdotolba/univai/blob/main/services/common/rag_client.py"
click node_agent "https://github.com/devabdotolba/univai/tree/main/UnivAI-Agent"
click node_contracts "https://github.com/devabdotolba/univai/blob/main/services/contracts/programme_plan.py"
click node_collections "https://github.com/devabdotolba/univai/blob/main/services/contracts/source_collection.py"
click node_orchestrator "https://github.com/devabdotolba/univai/blob/main/services/orchestrator/programme_generation.py"
click node_llm "https://github.com/devabdotolba/univai/blob/main/services/common/llm.py"
click node_postgres "https://github.com/devabdotolba/univai/blob/main/infra/schema.sql"
click node_live "https://github.com/devabdotolba/univai/tree/main/UnivAI-live"
click node_exam "https://github.com/devabdotolba/univai/tree/main/UnivAI-exam_system"
click node_proctor "https://github.com/devabdotolba/univai/tree/main/UnivAI-exam_system"
click node_dashboard "https://github.com/devabdotolba/univai/tree/main/UnivAI-app"
click node_admin "https://github.com/devabdotolba/univai/tree/main/UnivAI-app"
click node_clock "https://github.com/devabdotolba/univai/blob/main/services/common/clock.py"
click node_trace "https://github.com/devabdotolba/univai/blob/main/services/observability/tracing.py"
click node_inputguard "https://github.com/devabdotolba/univai/blob/main/services/security/input_guard.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_app,node_dashboard,node_admin toneBlue
class node_upload,node_ragclient,node_contracts,node_collections,node_orchestrator,node_llm,node_clock,node_trace,node_inputguard toneAmber
class node_agent toneMint
class node_live,node_exam,node_proctor toneRose
class node_postgres,node_learner,node_actor,node_model toneIndigo
```

## Components

### Learning experience

- [Web app and API](https://github.com/devabdotolba/univai/tree/main/UnivAI-app): `UnivAI-app`
- [Learner dashboard](https://github.com/devabdotolba/univai/tree/main/UnivAI-app): `UnivAI-app`
- [Admin controls](https://github.com/devabdotolba/univai/tree/main/UnivAI-app): `UnivAI-app`

### Shared services

- [Book indexing bridge](https://github.com/devabdotolba/univai/blob/main/services/rag-tools/rag_ingest.py): `services/rag-tools/rag_ingest.py`
- [MCP RAG client](https://github.com/devabdotolba/univai/blob/main/services/common/rag_client.py): `services/common/rag_client.py`
- [Plan contracts](https://github.com/devabdotolba/univai/blob/main/services/contracts/programme_plan.py): `services/contracts/programme_plan.py`
- [Source contracts](https://github.com/devabdotolba/univai/blob/main/services/contracts/source_collection.py): `services/contracts/source_collection.py`
- [Generation state machine](https://github.com/devabdotolba/univai/blob/main/services/orchestrator/programme_generation.py): `services/orchestrator/programme_generation.py`
- [LLM adapter](https://github.com/devabdotolba/univai/blob/main/services/common/llm.py): `services/common/llm.py`
- [Virtual clock](https://github.com/devabdotolba/univai/blob/main/services/common/clock.py): `services/common/clock.py`
- [Tracing and redaction](https://github.com/devabdotolba/univai/blob/main/services/observability/tracing.py): `services/observability/tracing.py`
- [AI input guard](https://github.com/devabdotolba/univai/blob/main/services/security/input_guard.py): `services/security/input_guard.py`

### Knowledge and generation

- [RAG and course generation](https://github.com/devabdotolba/univai/tree/main/UnivAI-Agent): `UnivAI-Agent`

### Live class and assessment

- [Live lecture rooms](https://github.com/devabdotolba/univai/tree/main/UnivAI-live): `UnivAI-live`
- [Exam system](https://github.com/devabdotolba/univai/tree/main/UnivAI-exam_system): `UnivAI-exam_system`
- [Proctoring reports](https://github.com/devabdotolba/univai/tree/main/UnivAI-exam_system): `UnivAI-exam_system`

### Persistent state

- [PostgreSQL](https://github.com/devabdotolba/univai/blob/main/infra/schema.sql): `infra/schema.sql`

### Other components

- **Learner**
- **Student**
- **Model providers**

## Connections

- Student → Web app and API: uploads book (evidence: `README.md`)
- Web app and API → Book indexing bridge: spawns indexing (evidence: `services/rag-tools/rag_ingest.py`)
- Book indexing bridge → MCP RAG client: calls ingest (evidence: `services/rag-tools/rag_ingest.py`)
- MCP RAG client → RAG and course generation: calls MCP (evidence: `services/common/rag_client.py`)
- RAG and course generation → PostgreSQL: stores course (evidence: `README.md`)
- RAG and course generation → Live lecture rooms: publishes lectures (evidence: `README.md`)
- Live lecture rooms → Exam system: hands off course (evidence: `README.md`)
- Exam system → Proctoring reports: produces reports (evidence: `README.md`)
- Exam system → Learner dashboard: returns grades (evidence: `README.md`)
- Learner dashboard → Student: shows results (evidence: `README.md`)
- Web app and API → Admin controls: provides controls (evidence: `README.md`)
- Admin controls → Virtual clock: drives time (evidence: `README.md`)
- RAG and course generation → Plan contracts: uses plan contract
- RAG and course generation → Source contracts: uses source contract
- Generation state machine → Plan contracts: validates plans (evidence: `services/orchestrator/programme_generation.py`)
- Generation state machine → Source contracts: validates collections (evidence: `services/orchestrator/programme_generation.py`)
- RAG and course generation → LLM adapter: generates with
- LLM adapter → Model providers: requests completion (evidence: `services/common/llm.py`)
- MCP RAG client → AI input guard: guards inputs (evidence: `services/common/rag_client.py`)
- LLM adapter → AI input guard: guards inputs (evidence: `services/common/llm.py`)
- LLM adapter → Tracing and redaction: propagates trace (evidence: `services/common/llm.py`)
- MCP RAG client → Tracing and redaction: propagates trace (evidence: `services/common/rag_client.py`)
