# priyanshitamta/vivaran-vqe architecture

> Architecture diagram of the GitHub repository priyanshitamta/vivaran-vqe, 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/priyanshitamta/vivaran-vqe
- Repository: https://github.com/priyanshitamta/vivaran-vqe

## Overview

Vivaran-VQE is a three-system learning platform whose learner workflow is assess skills, recommend courses, learn, verify with quizzes, then re-assess from quiz results. System 3 is the role-based web application and state owner; it delegates competency analysis to System 1 and quiz generation to System 2. The graph preserves the trainer/admin workspaces and progress features documented in the README. Some subsystem wiring is documented rather than shown in sampled source, so only documented calls are linked; peripheral routes are omitted.

Main entry points: [`System-3 Complete_Website/app.py`](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/app.py) (Web routes), [`System-2 MCQ_Generator/app.py`](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/app.py) (Quiz application), [`System-1 Recommandation_Engine/app/api/routes.py`](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/api/routes.py) (Recommendation API), [`System-1 Recommandation_Engine/app/services/registration_service.py`](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/services/registration_service.py) (Profile registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["System 3 Web Platform"]
  node_browser["Browser UI<br/>[intake.js]"]
  node_webapp["Web routes<br/>[app.py]"]
  node_webdb[("Platform state<br/>[db.py]")]
  node_catalogue["Course catalogue<br/>[courses.py]"]
  node_roadmap["Roadmap builder<br/>[recommender.py]"]
  node_progress["Progress tracking<br/>[progress.py]"]
  node_s1client["S1 HTTP client<br/>[s1_client.py]"]
  node_s2bridge["S2 quiz bridge<br/>[s2_bridge.py]"]
end

subgraph group_recommend["System 1 Recommendations"]
  node_s1main["Engine assembly<br/>[main.py]"]
  node_s1api["Recommendation API<br/>[routes.py]"]
  node_loader["Dataset loader<br/>[loader.py]"]
  node_repositories["Data repositories<br/>[repositories.py]"]
  node_gap["Gap analysis<br/>[gap_service.py]"]
  node_ranking["Course ranking"]
  node_registration["Profile registration"]
  node_dataset["Profile datasets<br/>[loader.py]"]
end

subgraph group_quiz["System 2 Quiz Engine"]
  node_s2app["Quiz application<br/>[app.py]"]
  node_video["Video processing<br/>[video_processor.py]"]
  node_transcriber["Audio transcription"]
  node_mcq["MCQ generation<br/>[mcq_generator.py]"]
  node_questions["Question selection"]
  node_results[("Quiz results<br/>[results_manager.py]")]
end

subgraph group_external["External Services"]
  node_youtube["YouTube"]
  node_groq["Groq API"]
end

node_learner(("Learner"))
node_trainer(("Trainer"))
node_admin(("Admin"))

node_learner -->|"uses"| node_browser
node_trainer -->|"uses"| node_browser
node_admin -->|"uses"| node_browser
node_browser -->|"HTTP requests"| node_webapp
node_webapp -->|"reads/writes"| node_webdb
node_webapp -->|"loads courses"| node_catalogue
node_webapp -->|"builds roadmap"| node_roadmap
node_webapp -->|"updates progress"| node_progress
node_webapp -->|"requests analysis"| node_s1client
node_s1client -->|"REST/JSON"| node_s1api
node_s1main -->|"loads datasets"| node_loader
node_loader -->|"reads"| node_dataset
node_s1main -->|"builds"| node_repositories
node_s1main -->|"mounts routes"| node_s1api
node_s1api -->|"computes gaps"| node_gap
node_s1api -->|"ranks courses"| node_ranking
node_s1api -->|"registers profile"| node_registration
node_registration -->|"computes gaps"| node_gap
node_registration -->|"gets recommendations"| node_ranking
node_registration -->|"persists profile"| node_dataset
node_webapp -->|"starts quiz job"| node_s2bridge
node_s2bridge -->|"in-process call"| node_s2app
node_s2app -->|"processes video"| node_video
node_video -.->|"downloads video"| node_youtube
node_s2app -->|"transcribes audio"| node_transcriber
node_s2app -->|"generates questions"| node_mcq
node_mcq -.->|"calls LLM"| node_groq
node_s2app -->|"selects questions"| node_questions
node_s2app -->|"saves attempts"| node_results
node_webapp -->|"caches quiz sets"| node_webdb

click node_browser "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/static/js/intake.js"
click node_webapp "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/app.py"
click node_webdb "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/db.py"
click node_catalogue "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/courses.py"
click node_roadmap "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/recommender.py"
click node_progress "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/progress.py"
click node_s1client "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/s1_client.py"
click node_s2bridge "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/s2_bridge.py"
click node_s1main "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/main.py"
click node_s1api "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/api/routes.py"
click node_loader "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/data/loader.py"
click node_repositories "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/data/repositories.py"
click node_gap "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/services/gap_service.py"
click node_ranking "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/services/recommendation_service.py"
click node_registration "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/services/registration_service.py"
click node_dataset "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/data/loader.py"
click node_s2app "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/app.py"
click node_video "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/video_processor.py"
click node_transcriber "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/audio_transcriber.py"
click node_mcq "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/mcq_generator.py"
click node_questions "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/question_manager.py"
click node_results "https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/results_manager.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_browser,node_webapp,node_webdb,node_catalogue,node_roadmap,node_progress,node_s1client,node_s2bridge toneBlue
class node_s1main,node_s1api,node_loader,node_repositories,node_gap,node_ranking,node_registration,node_dataset toneAmber
class node_s2app,node_video,node_transcriber,node_mcq,node_questions,node_results toneMint
class node_youtube,node_groq toneRose
class node_learner,node_trainer,node_admin toneIndigo
```

## Components

### System 3 Web Platform

- [Browser UI](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/static/js/intake.js): `System-3 Complete_Website/static/js/intake.js`
- [Web routes](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/app.py): `System-3 Complete_Website/app.py`
- [Platform state](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/db.py): `System-3 Complete_Website/db.py`
- [Course catalogue](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/courses.py): `System-3 Complete_Website/courses.py`
- [Roadmap builder](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/recommender.py): `System-3 Complete_Website/recommender.py`
- [Progress tracking](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/progress.py): `System-3 Complete_Website/progress.py`
- [S1 HTTP client](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/s1_client.py): `System-3 Complete_Website/s1_client.py`
- [S2 quiz bridge](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-3%20Complete_Website/s2_bridge.py): `System-3 Complete_Website/s2_bridge.py`

### System 1 Recommendations

- [Engine assembly](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/main.py): `System-1 Recommandation_Engine/app/main.py`
- [Recommendation API](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/api/routes.py): `System-1 Recommandation_Engine/app/api/routes.py`
- [Dataset loader](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/data/loader.py): `System-1 Recommandation_Engine/app/data/loader.py`
- [Data repositories](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/data/repositories.py): `System-1 Recommandation_Engine/app/data/repositories.py`
- [Gap analysis](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/services/gap_service.py): `System-1 Recommandation_Engine/app/services/gap_service.py`
- [Course ranking](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/services/recommendation_service.py): `System-1 Recommandation_Engine/app/services/recommendation_service.py`
- [Profile registration](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/services/registration_service.py): `System-1 Recommandation_Engine/app/services/registration_service.py`
- [Profile datasets](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-1%20Recommandation_Engine/app/data/loader.py): `System-1 Recommandation_Engine/app/data/loader.py`

### System 2 Quiz Engine

- [Quiz application](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/app.py): `System-2 MCQ_Generator/app.py`
- [Video processing](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/video_processor.py): `System-2 MCQ_Generator/utils/video_processor.py`
- [Audio transcription](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/audio_transcriber.py): `System-2 MCQ_Generator/utils/audio_transcriber.py`
- [MCQ generation](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/mcq_generator.py): `System-2 MCQ_Generator/utils/mcq_generator.py`
- [Question selection](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/question_manager.py): `System-2 MCQ_Generator/utils/question_manager.py`
- [Quiz results](https://github.com/priyanshitamta/vivaran-vqe/blob/main/System-2%20MCQ_Generator/utils/results_manager.py): `System-2 MCQ_Generator/utils/results_manager.py`

### External Services

- **YouTube**
- **Groq API**

### Other components

- **Learner**
- **Trainer**
- **Admin**

## Connections

- Learner → Browser UI: uses
- Trainer → Browser UI: uses
- Admin → Browser UI: uses
- Browser UI → Web routes: HTTP requests
- Web routes → Platform state: reads/writes
- Web routes → Course catalogue: loads courses
- Web routes → Roadmap builder: builds roadmap
- Web routes → Progress tracking: updates progress
- Web routes → S1 HTTP client: requests analysis
- S1 HTTP client → Recommendation API: REST/JSON
- Engine assembly → Dataset loader: loads datasets
- Dataset loader → Profile datasets: reads
- Engine assembly → Data repositories: builds
- Engine assembly → Recommendation API: mounts routes
- Recommendation API → Gap analysis: computes gaps
- Recommendation API → Course ranking: ranks courses
- Recommendation API → Profile registration: registers profile
- Profile registration → Gap analysis: computes gaps
- Profile registration → Course ranking: gets recommendations
- Profile registration → Profile datasets: persists profile
- Web routes → S2 quiz bridge: starts quiz job
- S2 quiz bridge → Quiz application: in-process call
- Quiz application → Video processing: processes video
- Video processing → YouTube: downloads video
- Quiz application → Audio transcription: transcribes audio
- Quiz application → MCQ generation: generates questions
- MCQ generation → Groq API: calls LLM
- Quiz application → Question selection: selects questions
- Quiz application → Quiz results: saves attempts
- Web routes → Platform state: caches quiz sets