# harshan-164/edunexus architecture

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

- Interactive diagram: https://gitdiagram.com/harshan-164/edunexus
- Repository: https://github.com/harshan-164/edunexus

## Overview

The tree contains a substantial adaptive-learning product alongside the Agentic Slice Kit described by the README; the graph preserves both rather than treating the README as documentation for the whole tree. Nexora’s learner flow moves through diagnostic assessment, diagnosis, targeted remediation, and verification, with learner history informing the workflow. The slice-kit branch separately demonstrates reusable agent-run machinery. Edges are limited to excerpted calls, indexed references, or README statements; several frontend-to-backend and unsampled integration links therefore remain omitted.

Main entry points: [`backend/graph/workflow.py`](https://github.com/harshan-164/edunexus/blob/main/backend/graph/workflow.py) (Learning Workflow), [`frontend/src/App.jsx`](https://github.com/harshan-164/edunexus/blob/main/frontend/src/App.jsx) (Web App Shell), [`backend/agents/diagnostic.py`](https://github.com/harshan-164/edunexus/blob/main/backend/agents/diagnostic.py) (Diagnostic Agent), [`slice/runner.py`](https://github.com/harshan-164/edunexus/blob/main/slice/runner.py) (Run State Machine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner Experience"]
  node_frontend["Web App Shell<br/>[App.jsx]"]
  node_learn_page["Learning Pages"]
  node_progress_page["Progress View<br/>[Progress.jsx]"]
  node_api_server["Application API<br/>[server.py]"]
  node_streamlit["Streamlit Learning UI<br/>[app.py]"]
end

subgraph group_learning["Adaptive Learning"]
  node_workflow["Learning Workflow<br/>[workflow.py]"]
  node_diagnostic["Diagnostic Agent<br/>[diagnostic.py]"]
  node_diagnosis["Misconception Diagnosis<br/>[diagnostic.py]"]
  node_remediation["Remediation Agent<br/>[remediation.py]"]
  node_verification["Verification Agent<br/>[verification.py]"]
  node_revision["Revision Agent<br/>[revision.py]"]
  node_agent_tools["Agent Tools<br/>[agent_tools.py]"]
  node_llm_adapter["LLM Adapter<br/>[llm_utils.py]"]
  node_contracts["Learning Contracts<br/>[schemas.py]"]
end

subgraph group_data["Learner Data &amp; Media"]
  node_learner_memory[("Learner History<br/>[learner_memory.py]")]
  node_syllabus_memory[("Syllabus Retrieval<br/>[syllabus_memory.py]")]
  node_user_services["Account Data Services<br/>[user_services.py]"]
  node_lesson_media["Lesson Media<br/>[lesson_media.py]"]
end

subgraph group_slice["Agentic Slice Kit"]
  node_slice_runner["Run State Machine<br/>[runner.py]"]
  node_slice_store[("Append-Only Store<br/>[store.py]")]
  node_slice_llm["Model Calls<br/>[llm.py]"]
  node_slice_budget["Attempt &amp; Token Fences<br/>[budget.py]"]
  node_slice_config["Runtime Config<br/>[config.py]"]
  node_slice_retrieve["Vector Retrieval<br/>[retrieve.py]"]
  node_slice_callback["Human Callback<br/>[callback.py]"]
  node_expert_form["Expert Form<br/>[expert.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_frontend
node_frontend -->|"renders"| node_learn_page
node_frontend -->|"renders"| node_progress_page
node_frontend -->|"fetches learner summary"| node_api_server
node_learner -.->|"uses"| node_streamlit
node_streamlit -->|"reads workflow state"| node_workflow
node_workflow -->|"generates questions"| node_diagnostic
node_workflow -->|"requests diagnosis"| node_diagnosis
node_workflow -->|"requests intervention"| node_remediation
node_workflow -->|"routes verification"| node_verification
node_workflow -->|"loads context"| node_learner_memory
node_workflow -->|"records attempts"| node_learner_memory
node_diagnostic -->|"uses tools"| node_agent_tools
node_diagnostic -->|"validates response"| node_contracts
node_diagnostic -->|"calls completion"| node_llm_adapter
node_remediation -->|"calls completion"| node_llm_adapter
node_verification -->|"calls completion"| node_llm_adapter
node_revision -->|"uses lesson media"| node_lesson_media
node_user_services -->|"provides service"| node_learner_memory
node_user_services -->|"provides service"| node_syllabus_memory
node_slice_runner -.->|"persists runs"| node_slice_store
node_slice_runner -.->|"runs model steps"| node_slice_llm
node_slice_llm -->|"enforces limits"| node_slice_budget
node_slice_llm -->|"loads settings"| node_slice_config
node_slice_retrieve -->|"searches same database"| node_slice_store
node_slice_runner -.->|"supports suspension"| node_slice_callback
node_expert_form -->|"answers callback"| node_slice_callback

click node_frontend "https://github.com/harshan-164/edunexus/blob/main/frontend/src/App.jsx"
click node_learn_page "https://github.com/harshan-164/edunexus/tree/main/frontend/src/pages"
click node_progress_page "https://github.com/harshan-164/edunexus/blob/main/frontend/src/pages/Progress.jsx"
click node_api_server "https://github.com/harshan-164/edunexus/blob/main/server.py"
click node_streamlit "https://github.com/harshan-164/edunexus/blob/main/app.py"
click node_workflow "https://github.com/harshan-164/edunexus/blob/main/backend/graph/workflow.py"
click node_diagnostic "https://github.com/harshan-164/edunexus/blob/main/backend/agents/diagnostic.py"
click node_diagnosis "https://github.com/harshan-164/edunexus/blob/main/backend/agents/diagnostic.py"
click node_remediation "https://github.com/harshan-164/edunexus/blob/main/backend/agents/remediation.py"
click node_verification "https://github.com/harshan-164/edunexus/blob/main/backend/agents/verification.py"
click node_revision "https://github.com/harshan-164/edunexus/blob/main/backend/agents/revision.py"
click node_agent_tools "https://github.com/harshan-164/edunexus/blob/main/backend/tools/agent_tools.py"
click node_llm_adapter "https://github.com/harshan-164/edunexus/blob/main/backend/agents/llm_utils.py"
click node_contracts "https://github.com/harshan-164/edunexus/blob/main/backend/models/schemas.py"
click node_learner_memory "https://github.com/harshan-164/edunexus/blob/main/backend/memory/learner_memory.py"
click node_syllabus_memory "https://github.com/harshan-164/edunexus/blob/main/backend/memory/syllabus_memory.py"
click node_user_services "https://github.com/harshan-164/edunexus/blob/main/backend/auth/user_services.py"
click node_lesson_media "https://github.com/harshan-164/edunexus/blob/main/backend/media/lesson_media.py"
click node_slice_runner "https://github.com/harshan-164/edunexus/blob/main/slice/runner.py"
click node_slice_store "https://github.com/harshan-164/edunexus/blob/main/slice/store.py"
click node_slice_llm "https://github.com/harshan-164/edunexus/blob/main/slice/llm.py"
click node_slice_budget "https://github.com/harshan-164/edunexus/blob/main/slice/budget.py"
click node_slice_config "https://github.com/harshan-164/edunexus/blob/main/slice/config.py"
click node_slice_retrieve "https://github.com/harshan-164/edunexus/blob/main/slice/retrieve.py"
click node_slice_callback "https://github.com/harshan-164/edunexus/blob/main/slice/callback.py"
click node_expert_form "https://github.com/harshan-164/edunexus/blob/main/web/expert.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_frontend,node_learn_page,node_progress_page,node_api_server,node_streamlit toneBlue
class node_workflow,node_diagnostic,node_diagnosis,node_remediation,node_verification,node_revision,node_agent_tools,node_llm_adapter,node_contracts toneAmber
class node_learner_memory,node_syllabus_memory,node_user_services,node_lesson_media toneMint
class node_slice_runner,node_slice_store,node_slice_llm,node_slice_budget,node_slice_config,node_slice_retrieve,node_slice_callback,node_expert_form toneRose
class node_learner toneIndigo
```

## Components

### Learner Experience

- [Web App Shell](https://github.com/harshan-164/edunexus/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Learning Pages](https://github.com/harshan-164/edunexus/tree/main/frontend/src/pages): `frontend/src/pages`
- [Progress View](https://github.com/harshan-164/edunexus/blob/main/frontend/src/pages/Progress.jsx): `frontend/src/pages/Progress.jsx`
- [Application API](https://github.com/harshan-164/edunexus/blob/main/server.py): `server.py`
- [Streamlit Learning UI](https://github.com/harshan-164/edunexus/blob/main/app.py): `app.py`

### Adaptive Learning

- [Learning Workflow](https://github.com/harshan-164/edunexus/blob/main/backend/graph/workflow.py): `backend/graph/workflow.py`
- [Diagnostic Agent](https://github.com/harshan-164/edunexus/blob/main/backend/agents/diagnostic.py): `backend/agents/diagnostic.py`
- [Misconception Diagnosis](https://github.com/harshan-164/edunexus/blob/main/backend/agents/diagnostic.py): `backend/agents/diagnostic.py`
- [Remediation Agent](https://github.com/harshan-164/edunexus/blob/main/backend/agents/remediation.py): `backend/agents/remediation.py`
- [Verification Agent](https://github.com/harshan-164/edunexus/blob/main/backend/agents/verification.py): `backend/agents/verification.py`
- [Revision Agent](https://github.com/harshan-164/edunexus/blob/main/backend/agents/revision.py): `backend/agents/revision.py`
- [Agent Tools](https://github.com/harshan-164/edunexus/blob/main/backend/tools/agent_tools.py): `backend/tools/agent_tools.py`
- [LLM Adapter](https://github.com/harshan-164/edunexus/blob/main/backend/agents/llm_utils.py): `backend/agents/llm_utils.py`
- [Learning Contracts](https://github.com/harshan-164/edunexus/blob/main/backend/models/schemas.py): `backend/models/schemas.py`

### Learner Data & Media

- [Learner History](https://github.com/harshan-164/edunexus/blob/main/backend/memory/learner_memory.py): `backend/memory/learner_memory.py`
- [Syllabus Retrieval](https://github.com/harshan-164/edunexus/blob/main/backend/memory/syllabus_memory.py): `backend/memory/syllabus_memory.py`
- [Account Data Services](https://github.com/harshan-164/edunexus/blob/main/backend/auth/user_services.py): `backend/auth/user_services.py`
- [Lesson Media](https://github.com/harshan-164/edunexus/blob/main/backend/media/lesson_media.py): `backend/media/lesson_media.py`

### Agentic Slice Kit

- [Run State Machine](https://github.com/harshan-164/edunexus/blob/main/slice/runner.py): `slice/runner.py`
- [Append-Only Store](https://github.com/harshan-164/edunexus/blob/main/slice/store.py): `slice/store.py`
- [Model Calls](https://github.com/harshan-164/edunexus/blob/main/slice/llm.py): `slice/llm.py`
- [Attempt & Token Fences](https://github.com/harshan-164/edunexus/blob/main/slice/budget.py): `slice/budget.py`
- [Runtime Config](https://github.com/harshan-164/edunexus/blob/main/slice/config.py): `slice/config.py`
- [Vector Retrieval](https://github.com/harshan-164/edunexus/blob/main/slice/retrieve.py): `slice/retrieve.py`
- [Human Callback](https://github.com/harshan-164/edunexus/blob/main/slice/callback.py): `slice/callback.py`
- [Expert Form](https://github.com/harshan-164/edunexus/blob/main/web/expert.py): `web/expert.py`

### Other components

- **Learner**

## Connections

- Learner → Web App Shell: uses (evidence: `frontend/src/App.jsx`)
- Web App Shell → Learning Pages: renders (evidence: `frontend/src/App.jsx`)
- Web App Shell → Progress View: renders (evidence: `frontend/src/App.jsx`)
- Web App Shell → Application API: fetches learner summary (evidence: `frontend/src/App.jsx`)
- Learner → Streamlit Learning UI: uses (evidence: `app.py`)
- Streamlit Learning UI → Learning Workflow: reads workflow state (evidence: `app.py`)
- Learning Workflow → Diagnostic Agent: generates questions (evidence: `backend/graph/workflow.py`)
- Learning Workflow → Misconception Diagnosis: requests diagnosis (evidence: `backend/graph/workflow.py`)
- Learning Workflow → Remediation Agent: requests intervention (evidence: `backend/graph/workflow.py`)
- Learning Workflow → Verification Agent: routes verification (evidence: `backend/graph/workflow.py`)
- Learning Workflow → Learner History: loads context (evidence: `backend/graph/workflow.py`)
- Learning Workflow → Learner History: records attempts (evidence: `backend/graph/workflow.py`)
- Diagnostic Agent → Agent Tools: uses tools (evidence: `backend/agents/diagnostic.py`)
- Diagnostic Agent → Learning Contracts: validates response (evidence: `backend/agents/diagnostic.py`)
- Diagnostic Agent → LLM Adapter: calls completion (evidence: `backend/agents/diagnostic.py`)
- Remediation Agent → LLM Adapter: calls completion (evidence: `backend/agents/remediation.py`)
- Verification Agent → LLM Adapter: calls completion (evidence: `backend/agents/verification.py`)
- Revision Agent → Lesson Media: uses lesson media (evidence: `backend/agents/revision.py`)
- Account Data Services → Learner History: provides service (evidence: `backend/auth/user_services.py`)
- Account Data Services → Syllabus Retrieval: provides service (evidence: `backend/auth/user_services.py`)
- Run State Machine → Append-Only Store: persists runs
- Run State Machine → Model Calls: runs model steps
- Model Calls → Attempt & Token Fences: enforces limits (evidence: `slice/llm.py`)
- Model Calls → Runtime Config: loads settings (evidence: `slice/llm.py`)
- Vector Retrieval → Append-Only Store: searches same database (evidence: `slice/retrieve.py`)
- Run State Machine → Human Callback: supports suspension
- Expert Form → Human Callback: answers callback (evidence: `web/expert.py`)
