# ravishori/i-neet-exam-web architecture

> Architecture diagram of the GitHub repository ravishori/i-neet-exam-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ravishori/i-neet-exam-web
- Repository: https://github.com/ravishori/i-neet-exam-web

## Overview

TALOS is a FastAPI modular-monolith learning platform, with NEET as its first exam product. Its principal user flow is authentication, browsing the academic hierarchy and published content, taking timed practice or mock assessments, then reviewing performance through mastery and rule-based recommendations; AI tutoring and study planning are additional learning paths. Operators manage content through the CMS, including review and publication, and can ingest study materials into knowledge and content workflows. The README documents these capabilities, while sampled code gives implementation detail mainly for ingestion and CMS review; other wiring is shown only where supported by the documented module architecture.

Main entry points: [`apps/backend/app/main.py`](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/main.py) (FastAPI application), [`apps/backend/app/modules/cms/services/content_workflow_service.py`](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/cms/services/content_workflow_service.py) (Content workflow), [`apps/backend/app/modules/ingestion/api/ingestion_router.py`](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ingestion/api/ingestion_router.py) (Ingestion API), [`apps/backend/app/modules/assessment/api/assessment_router.py`](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/assessment/api/assessment_router.py) (Assessment API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_auth_api["Auth API<br/>[auth_router.py]"]
  node_auth_service["Authentication<br/>[auth_service.py]"]
end

subgraph group_content["Academic content"]
  node_academic_api["Academic browse<br/>[academic_router.py]"]
  node_academic_data["Academic hierarchy"]
  node_cms_api["CMS API<br/>[cms_router.py]"]
  node_cms_workflow["Content workflow"]
  node_cms_store[("Content records<br/>[cms_repository.py]")]
  node_ingestion_api["Ingestion API"]
  node_ingestion_orchestration["Source ingestion"]
  node_ingestion_pipeline["Ingestion pipeline"]
end

subgraph group_learning["Learning experience"]
  node_assessment_api["Assessment API"]
  node_assessment_service["Assessment engine"]
  node_learning_api["Learning interactions<br/>[mastery_router.py]"]
  node_mastery["Mastery and recommendations<br/>[mastery_service.py]"]
  node_analytics["Student analytics"]
end

subgraph group_ai["AI services"]
  node_ai_api["AI API<br/>[ai_router.py]"]
  node_tutor["Tutor and planner<br/>[tutor_service.py]"]
  node_ai_gateway["AI provider gateway<br/>[ai_gateway.py]"]
end

subgraph group_operations["Operations and commerce"]
  node_commerce_api["Commerce API<br/>[commerce_router.py]"]
  node_commerce_service["Order and payment"]
end

node_aspirant(("NEET aspirant"))
node_operator(("Content operator"))
node_app["FastAPI application<br/>[main.py]"]
node_razorpay["Razorpay"]

node_aspirant -->|"uses"| node_app
node_operator -->|"uses"| node_app
node_app -->|"dispatches"| node_auth_api
node_app -->|"dispatches"| node_academic_api
node_app -->|"dispatches"| node_cms_api
node_app -->|"dispatches"| node_ingestion_api
node_app -->|"dispatches"| node_assessment_api
node_app -->|"dispatches"| node_learning_api
node_app -->|"dispatches"| node_ai_api
node_app -->|"dispatches"| node_commerce_api
node_auth_api -->|"authenticates"| node_auth_service
node_academic_api -->|"browses hierarchy"| node_academic_data
node_cms_api -->|"manages content"| node_cms_workflow
node_cms_workflow -->|"persists versions"| node_cms_store
node_operator -->|"starts ingestion"| node_ingestion_api
node_ingestion_api -->|"orchestrates"| node_ingestion_orchestration
node_ingestion_orchestration -->|"starts jobs"| node_ingestion_pipeline
node_ingestion_pipeline -->|"creates drafts"| node_cms_workflow
node_aspirant -->|"starts practice"| node_assessment_api
node_assessment_api -->|"scores attempts"| node_assessment_service
node_aspirant -->|"records activity"| node_learning_api
node_learning_api -->|"updates mastery"| node_mastery
node_aspirant -->|"views scorecard"| node_analytics
node_aspirant -->|"requests coaching"| node_ai_api
node_ai_api -->|"invokes agent"| node_tutor
node_tutor -->|"routes generation"| node_ai_gateway
node_aspirant -->|"creates order"| node_commerce_api
node_commerce_api -->|"handles payment"| node_commerce_service
node_commerce_service -->|"verifies payment"| node_razorpay

click node_app "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/main.py"
click node_auth_api "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/identity/api/auth_router.py"
click node_auth_service "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/identity/services/auth_service.py"
click node_academic_api "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/academic/api/academic_router.py"
click node_academic_data "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/academic/repositories/academic_repository.py"
click node_cms_api "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/cms/api/cms_router.py"
click node_cms_workflow "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/cms/services/content_workflow_service.py"
click node_cms_store "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/cms/repositories/cms_repository.py"
click node_ingestion_api "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ingestion/api/ingestion_router.py"
click node_ingestion_orchestration "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ingestion/services/source_ingestion_orchestration_service.py"
click node_ingestion_pipeline "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ingestion/services/ingestion_pipeline_service.py"
click node_assessment_api "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/assessment/api/assessment_router.py"
click node_assessment_service "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/assessment/services/assessment_service.py"
click node_learning_api "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/learning/api/mastery_router.py"
click node_mastery "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/learning/services/mastery_service.py"
click node_analytics "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/analytics/services/analytics_service.py"
click node_ai_api "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ai/api/ai_router.py"
click node_tutor "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ai/services/tutor_service.py"
click node_ai_gateway "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ai/gateway/ai_gateway.py"
click node_commerce_api "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/commerce/api/commerce_router.py"
click node_commerce_service "https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/commerce/services/commerce_service.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_auth_api,node_auth_service toneBlue
class node_academic_api,node_academic_data,node_cms_api,node_cms_workflow,node_cms_store,node_ingestion_api,node_ingestion_orchestration,node_ingestion_pipeline toneAmber
class node_assessment_api,node_assessment_service,node_learning_api,node_mastery,node_analytics,node_app toneMint
class node_ai_api,node_tutor,node_ai_gateway toneRose
class node_commerce_api,node_commerce_service,node_aspirant,node_operator,node_razorpay toneIndigo
```

## Components

### Identity and access

- [Auth API](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/identity/api/auth_router.py): `apps/backend/app/modules/identity/api/auth_router.py`
- [Authentication](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/identity/services/auth_service.py): `apps/backend/app/modules/identity/services/auth_service.py`

### Academic content

- [Academic browse](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/academic/api/academic_router.py): `apps/backend/app/modules/academic/api/academic_router.py`
- [Academic hierarchy](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/academic/repositories/academic_repository.py): `apps/backend/app/modules/academic/repositories/academic_repository.py`
- [CMS API](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/cms/api/cms_router.py): `apps/backend/app/modules/cms/api/cms_router.py`
- [Content workflow](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/cms/services/content_workflow_service.py): `apps/backend/app/modules/cms/services/content_workflow_service.py`
- [Content records](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/cms/repositories/cms_repository.py): `apps/backend/app/modules/cms/repositories/cms_repository.py`
- [Ingestion API](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ingestion/api/ingestion_router.py): `apps/backend/app/modules/ingestion/api/ingestion_router.py`
- [Source ingestion](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ingestion/services/source_ingestion_orchestration_service.py): `apps/backend/app/modules/ingestion/services/source_ingestion_orchestration_service.py`
- [Ingestion pipeline](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ingestion/services/ingestion_pipeline_service.py): `apps/backend/app/modules/ingestion/services/ingestion_pipeline_service.py`

### Learning experience

- [Assessment API](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/assessment/api/assessment_router.py): `apps/backend/app/modules/assessment/api/assessment_router.py`
- [Assessment engine](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/assessment/services/assessment_service.py): `apps/backend/app/modules/assessment/services/assessment_service.py`
- [Learning interactions](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/learning/api/mastery_router.py): `apps/backend/app/modules/learning/api/mastery_router.py`
- [Mastery and recommendations](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/learning/services/mastery_service.py): `apps/backend/app/modules/learning/services/mastery_service.py`
- [Student analytics](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/analytics/services/analytics_service.py): `apps/backend/app/modules/analytics/services/analytics_service.py`

### AI services

- [AI API](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ai/api/ai_router.py): `apps/backend/app/modules/ai/api/ai_router.py`
- [Tutor and planner](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ai/services/tutor_service.py): `apps/backend/app/modules/ai/services/tutor_service.py`
- [AI provider gateway](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/ai/gateway/ai_gateway.py): `apps/backend/app/modules/ai/gateway/ai_gateway.py`

### Operations and commerce

- [Commerce API](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/commerce/api/commerce_router.py): `apps/backend/app/modules/commerce/api/commerce_router.py`
- [Order and payment](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/modules/commerce/services/commerce_service.py): `apps/backend/app/modules/commerce/services/commerce_service.py`

### Other components

- **NEET aspirant**
- **Content operator**
- [FastAPI application](https://github.com/ravishori/i-neet-exam-web/blob/phase2-question-bank/apps/backend/app/main.py): `apps/backend/app/main.py`
- **Razorpay**

## Connections

- NEET aspirant → FastAPI application: uses
- Content operator → FastAPI application: uses
- FastAPI application → Auth API: dispatches
- FastAPI application → Academic browse: dispatches
- FastAPI application → CMS API: dispatches
- FastAPI application → Ingestion API: dispatches
- FastAPI application → Assessment API: dispatches
- FastAPI application → Learning interactions: dispatches
- FastAPI application → AI API: dispatches
- FastAPI application → Commerce API: dispatches
- Auth API → Authentication: authenticates
- Academic browse → Academic hierarchy: browses hierarchy
- CMS API → Content workflow: manages content
- Content workflow → Content records: persists versions
- Content operator → Ingestion API: starts ingestion
- Ingestion API → Source ingestion: orchestrates
- Source ingestion → Ingestion pipeline: starts jobs
- Ingestion pipeline → Content workflow: creates drafts
- NEET aspirant → Assessment API: starts practice
- Assessment API → Assessment engine: scores attempts
- NEET aspirant → Learning interactions: records activity
- Learning interactions → Mastery and recommendations: updates mastery
- NEET aspirant → Student analytics: views scorecard
- NEET aspirant → AI API: requests coaching
- AI API → Tutor and planner: invokes agent
- Tutor and planner → AI provider gateway: routes generation
- NEET aspirant → Commerce API: creates order
- Commerce API → Order and payment: handles payment
- Order and payment → Razorpay: verifies payment