# zaarakhan-dev/shiksha-sathi architecture

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

- Interactive diagram: https://gitdiagram.com/zaarakhan-dev/shiksha-sathi
- Repository: https://github.com/zaarakhan-dev/shiksha-sathi

## Overview

Shiksha Sathi is a competency-diagnosis service for statistical-officer training cohorts, not a course platform. Trainers upload rosters or enter assessment scores; the backend combines quiz and appraisal signals, diagnoses prerequisite bottlenecks, and returns an ordered remediation path. Trainers can record reassessment results and inspect cohort bottlenecks. The README also describes a prototype dashboard and human-reviewed AI question workflow. Implementation evidence is concentrated in the two excerpted core files; links for unsampled UI and question-generation behavior are marked unverified or omitted.

Main entry points: [`backend/app/main.py`](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py) (Backend API), [`ml/prerequisite_engine.py`](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py) (Bottleneck diagnosis), [`frontend`](https://github.com/zaarakhan-dev/shiksha-sathi/tree/main/frontend) (Trainer dashboard), [`backend/app`](https://github.com/zaarakhan-dev/shiksha-sathi/tree/main/backend/app) (AI question generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cohort["Cohort setup"]
  node_roster["Roster upload<br/>[main.py]"]
  node_cohort_store[("Cohort records<br/>[main.py]")]
  node_assessment["Assessment scores<br/>[main.py]"]
  node_api["Backend API<br/>[main.py]"]
end

subgraph group_diagnosis["Scoring and diagnosis"]
  node_scoring["Signal scoring"]
  node_prerequisites[("Prerequisite DAG")]
  node_diagnosis_engine["Bottleneck diagnosis"]
  node_coverage["Coverage and confidence"]
end

subgraph group_learning["Learning and review"]
  node_learning_path["Ordered remediation path"]
  node_question_gen["AI question generation"]
  node_review_queue["Trainer review queue<br/>[main.py]"]
end

subgraph group_insight["Progress and insight"]
  node_dashboard["Trainer dashboard"]
  node_reassessment["Reassessment comparison<br/>[main.py]"]
  node_heatmap["Cohort heatmap<br/>[main.py]"]
end

node_trainer(("Trainer"))
node_learner(("Learner"))
node_local_llm["Self-hosted local LLM"]

node_trainer -.->|"uses"| node_dashboard
node_trainer -->|"uploads roster"| node_roster
node_roster -->|"stores officials"| node_cohort_store
node_trainer -->|"enters scores"| node_assessment
node_assessment -.->|"updates scores"| node_cohort_store
node_dashboard -.->|"requests results"| node_api
node_api -->|"reads official"| node_cohort_store
node_api -->|"scores signals"| node_scoring
node_scoring -->|"provides scores"| node_diagnosis_engine
node_diagnosis_engine -->|"traverses"| node_prerequisites
node_api -->|"runs diagnosis"| node_diagnosis_engine
node_api -->|"reports coverage"| node_coverage
node_api -->|"builds path"| node_learning_path
node_learning_path -.->|"guides remediation"| node_learner
node_local_llm -.->|"drafts questions"| node_question_gen
node_question_gen -.->|"submits for review"| node_review_queue
node_trainer -->|"approves questions"| node_review_queue
node_learner -->|"takes retest"| node_reassessment
node_api -->|"records results"| node_reassessment
node_reassessment -->|"updates scores"| node_cohort_store
node_api -->|"aggregates cohort"| node_heatmap
node_heatmap -.->|"presents bottlenecks"| node_dashboard

click node_dashboard "https://github.com/zaarakhan-dev/shiksha-sathi/tree/main/frontend"
click node_roster "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py"
click node_cohort_store "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py"
click node_assessment "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py"
click node_api "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py"
click node_scoring "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py"
click node_prerequisites "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py"
click node_diagnosis_engine "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py"
click node_coverage "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py"
click node_learning_path "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py"
click node_question_gen "https://github.com/zaarakhan-dev/shiksha-sathi/tree/main/backend/app"
click node_review_queue "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py"
click node_reassessment "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py"
click node_heatmap "https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.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_roster,node_cohort_store,node_assessment,node_api toneBlue
class node_scoring,node_prerequisites,node_diagnosis_engine,node_coverage toneAmber
class node_learning_path,node_question_gen,node_review_queue toneMint
class node_dashboard,node_reassessment,node_heatmap toneRose
class node_trainer,node_learner,node_local_llm toneIndigo
```

## Components

### Cohort setup

- [Roster upload](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py): `backend/app/main.py`
- [Cohort records](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py): `backend/app/main.py`
- [Assessment scores](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py): `backend/app/main.py`
- [Backend API](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py): `backend/app/main.py`

### Scoring and diagnosis

- [Signal scoring](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py): `ml/prerequisite_engine.py`
- [Prerequisite DAG](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py): `ml/prerequisite_engine.py`
- [Bottleneck diagnosis](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py): `ml/prerequisite_engine.py`
- [Coverage and confidence](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py): `ml/prerequisite_engine.py`

### Learning and review

- [Ordered remediation path](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/ml/prerequisite_engine.py): `ml/prerequisite_engine.py`
- [AI question generation](https://github.com/zaarakhan-dev/shiksha-sathi/tree/main/backend/app): `backend/app`
- [Trainer review queue](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py): `backend/app/main.py`

### Progress and insight

- [Trainer dashboard](https://github.com/zaarakhan-dev/shiksha-sathi/tree/main/frontend): `frontend`
- [Reassessment comparison](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py): `backend/app/main.py`
- [Cohort heatmap](https://github.com/zaarakhan-dev/shiksha-sathi/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Trainer**
- **Learner**
- **Self-hosted local LLM**

## Connections

- Trainer → Trainer dashboard: uses
- Trainer → Roster upload: uploads roster (evidence: `README.md`)
- Roster upload → Cohort records: stores officials (evidence: `backend/app/main.py`)
- Trainer → Assessment scores: enters scores (evidence: `README.md`)
- Assessment scores → Cohort records: updates scores (evidence: `backend/app/main.py`)
- Trainer dashboard → Backend API: requests results
- Backend API → Cohort records: reads official (evidence: `backend/app/main.py`)
- Backend API → Signal scoring: scores signals (evidence: `backend/app/main.py`)
- Signal scoring → Bottleneck diagnosis: provides scores (evidence: `ml/prerequisite_engine.py`)
- Bottleneck diagnosis → Prerequisite DAG: traverses (evidence: `ml/prerequisite_engine.py`)
- Backend API → Bottleneck diagnosis: runs diagnosis (evidence: `backend/app/main.py`)
- Backend API → Coverage and confidence: reports coverage (evidence: `backend/app/main.py`)
- Backend API → Ordered remediation path: builds path (evidence: `backend/app/main.py`)
- Ordered remediation path → Learner: guides remediation (evidence: `README.md`)
- Self-hosted local LLM → AI question generation: drafts questions (evidence: `README.md`)
- AI question generation → Trainer review queue: submits for review (evidence: `README.md`)
- Trainer → Trainer review queue: approves questions (evidence: `README.md`)
- Learner → Reassessment comparison: takes retest (evidence: `README.md`)
- Backend API → Reassessment comparison: records results (evidence: `backend/app/main.py`)
- Reassessment comparison → Cohort records: updates scores (evidence: `backend/app/main.py`)
- Backend API → Cohort heatmap: aggregates cohort (evidence: `backend/app/main.py`)
- Cohort heatmap → Trainer dashboard: presents bottlenecks
