# jagadeesh54g/qniverse architecture

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

- Interactive diagram: https://gitdiagram.com/jagadeesh54g/qniverse
- Repository: https://github.com/jagadeesh54g/qniverse

## Overview

Qniverse is an interactive quantum-computing learning platform. A learner enters through the learning interface, completes an assessment, studies structured modules, experiments with circuits, and practices through algorithm studios and challenges; progress can be saved. Authentication, a context-aware tutor, and a student community support that learning loop. The README documents the learning and simulation capabilities, while sampled API handlers confirm persistence and integration behavior; wiring between several UI components is not shown, so those links are omitted.

Main entry points: [`app/community/page.jsx`](https://github.com/jagadeesh54g/qniverse/blob/main/app/community/page.jsx) (Community), [`app/api/onboarding/route.js`](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/onboarding/route.js) (Assessment API), [`components/Playground.jsx`](https://github.com/jagadeesh54g/qniverse/blob/main/components/Playground.jsx) (Circuit workspace), [`app/api/tutor/route.js`](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/tutor/route.js) (Tutor API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning experience"]
  node_home["Landing<br/>[page.jsx]"]
  node_onboarding["Learning assessment<br/>[page.jsx]"]
  node_assessment_ui["Assessment UI"]
  node_lessons["Learning modules<br/>[page.jsx]"]
  node_lesson_content["Lesson content<br/>[lessons.js]"]
  node_progress_ui["Progress view<br/>[page.jsx]"]
  node_tutor_ui["Tutor panel<br/>[TutorPanel.jsx]"]
end

subgraph group_lab["Quantum lab"]
  node_playground["Quantum playground<br/>[page.jsx]"]
  node_playground_ui["Circuit workspace<br/>[Playground.jsx]"]
  node_quantum_sim["Statevector simulation<br/>[quantum.js]"]
  node_circuit_parser["Code parser<br/>[qasm.js]"]
  node_visualization["Circuit visualization<br/>[CircuitBuilder.jsx]"]
  node_algorithms["Algorithm studio<br/>[page.jsx]"]
  node_challenges["Circuit challenges<br/>[page.jsx]"]
  node_challenge_logic["Challenge grading<br/>[grader.js]"]
  node_python_worker["Browser Python runtime<br/>[worker.js]"]
  node_runner_service["Python runner service<br/>[main.py]"]
end

subgraph group_identity["Learner services"]
  node_assessment_api["Assessment API<br/>[route.js]"]
  node_assessment_logic["Assessment scoring<br/>[onboarding.js]"]
  node_progress_api["Progress API<br/>[route.js]"]
  node_tutor_api["Tutor API<br/>[route.js]"]
  node_offline_tutor["Local tutor fallback<br/>[route.js]"]
  node_signin["Sign-in<br/>[page.jsx]"]
  node_auth_api["Authentication API<br/>[route.js]"]
  node_auth_logic["Session handling<br/>[auth.js]"]
end

subgraph group_community["Community"]
  node_community_ui["Community<br/>[page.jsx]"]
  node_community_posts["Posts and replies API<br/>[route.js]"]
  node_community_replies["Reply API<br/>[route.js]"]
  node_community_likes["Likes API<br/>[route.js]"]
  node_community_students["Student directory API<br/>[route.js]"]
end

node_learner(("Learner"))
node_qwen["Qwen service"]
node_mongodb[("MongoDB")]

node_learner -->|"opens"| node_home
node_learner -->|"assesses"| node_onboarding
node_learner -->|"studies"| node_lessons
node_learner -->|"experiments"| node_playground
node_learner -->|"explores"| node_algorithms
node_learner -->|"practices"| node_challenges
node_learner -->|"signs in"| node_signin
node_learner -->|"participates"| node_community_ui
node_assessment_ui -->|"submits answers"| node_assessment_api
node_assessment_api -->|"scores"| node_assessment_logic
node_assessment_api -->|"writes profile"| node_mongodb
node_assessment_api -->|"uses scoring"| node_assessment_logic
node_lessons -.->|"loads content"| node_lesson_content
node_playground_ui -.->|"simulates circuits"| node_quantum_sim
node_playground_ui -.->|"parses code"| node_circuit_parser
node_playground_ui -.->|"visualizes circuits"| node_visualization
node_challenges -.->|"validates solutions"| node_challenge_logic
node_progress_ui -.->|"loads and saves"| node_progress_api
node_progress_api -->|"reads and writes"| node_mongodb
node_tutor_ui -.->|"asks questions"| node_tutor_api
node_tutor_api -.->|"requests answer"| node_qwen
node_tutor_api -->|"falls back"| node_offline_tutor
node_signin -.->|"submits credentials"| node_auth_api
node_auth_api -->|"creates session"| node_auth_logic
node_auth_api -->|"reads and writes"| node_mongodb
node_community_ui -.->|"loads and posts"| node_community_posts
node_community_ui -.->|"submits replies"| node_community_replies
node_community_ui -.->|"likes posts"| node_community_likes
node_community_ui -.->|"loads students"| node_community_students
node_community_posts -->|"reads and writes"| node_mongodb
node_community_replies -->|"reads and writes"| node_mongodb
node_community_likes -->|"updates likes"| node_mongodb
node_community_students -->|"reads users"| node_mongodb

click node_home "https://github.com/jagadeesh54g/qniverse/blob/main/app/page.jsx"
click node_onboarding "https://github.com/jagadeesh54g/qniverse/blob/main/app/onboarding/page.jsx"
click node_assessment_ui "https://github.com/jagadeesh54g/qniverse/blob/main/components/OnboardingAssessment.jsx"
click node_assessment_api "https://github.com/jagadeesh54g/qniverse/blob/main/app/api/onboarding/route.js"
click node_assessment_logic "https://github.com/jagadeesh54g/qniverse/blob/main/lib/onboarding.js"
click node_lessons "https://github.com/jagadeesh54g/qniverse/blob/main/app/learn/page.jsx"
click node_lesson_content "https://github.com/jagadeesh54g/qniverse/blob/main/lib/lessons.js"
click node_playground "https://github.com/jagadeesh54g/qniverse/blob/main/app/playground/page.jsx"
click node_playground_ui "https://github.com/jagadeesh54g/qniverse/blob/main/components/Playground.jsx"
click node_quantum_sim "https://github.com/jagadeesh54g/qniverse/blob/main/lib/quantum.js"
click node_circuit_parser "https://github.com/jagadeesh54g/qniverse/blob/main/lib/challenges/qasm.js"
click node_visualization "https://github.com/jagadeesh54g/qniverse/blob/main/components/challenges/CircuitBuilder.jsx"
click node_algorithms "https://github.com/jagadeesh54g/qniverse/blob/main/app/algorithms/page.jsx"
click node_challenges "https://github.com/jagadeesh54g/qniverse/blob/main/app/challenges/page.jsx"
click node_challenge_logic "https://github.com/jagadeesh54g/qniverse/blob/main/lib/challenges/grader.js"
click node_progress_ui "https://github.com/jagadeesh54g/qniverse/blob/main/app/progress/page.jsx"
click node_progress_api "https://github.com/jagadeesh54g/qniverse/blob/main/app/api/progress/route.js"
click node_tutor_ui "https://github.com/jagadeesh54g/qniverse/blob/main/components/TutorPanel.jsx"
click node_tutor_api "https://github.com/jagadeesh54g/qniverse/blob/main/app/api/tutor/route.js"
click node_offline_tutor "https://github.com/jagadeesh54g/qniverse/blob/main/app/api/tutor/route.js"
click node_signin "https://github.com/jagadeesh54g/qniverse/blob/main/app/sign-in/page.jsx"
click node_auth_api "https://github.com/jagadeesh54g/qniverse/blob/main/app/api/auth/route.js"
click node_auth_logic "https://github.com/jagadeesh54g/qniverse/blob/main/lib/auth.js"
click node_community_ui "https://github.com/jagadeesh54g/qniverse/blob/main/app/community/page.jsx"
click node_community_posts "https://github.com/jagadeesh54g/qniverse/blob/main/app/api/community/posts/route.js"
click node_community_replies "https://github.com/jagadeesh54g/qniverse/blob/main/app/api/community/replies/route.js"
click node_community_likes "https://github.com/jagadeesh54g/qniverse/blob/main/app/api/community/like/route.js"
click node_community_students "https://github.com/jagadeesh54g/qniverse/blob/main/app/api/community/students/route.js"
click node_python_worker "https://github.com/jagadeesh54g/qniverse/blob/main/public/qniverse-py/worker.js"
click node_runner_service "https://github.com/jagadeesh54g/qniverse/blob/main/server/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_home,node_onboarding,node_assessment_ui,node_lessons,node_lesson_content,node_progress_ui,node_tutor_ui toneBlue
class node_playground,node_playground_ui,node_quantum_sim,node_circuit_parser,node_visualization,node_algorithms,node_challenges,node_challenge_logic,node_python_worker,node_runner_service,node_mongodb toneAmber
class node_assessment_api,node_assessment_logic,node_progress_api,node_tutor_api,node_offline_tutor,node_signin,node_auth_api,node_auth_logic toneMint
class node_community_ui,node_community_posts,node_community_replies,node_community_likes,node_community_students toneRose
class node_learner,node_qwen toneIndigo
```

## Components

### Learning experience

- [Landing](https://github.com/jagadeesh54g/qniverse/blob/main/app/page.jsx): `app/page.jsx`
- [Learning assessment](https://github.com/jagadeesh54g/qniverse/blob/main/app/onboarding/page.jsx): `app/onboarding/page.jsx`
- [Assessment UI](https://github.com/jagadeesh54g/qniverse/blob/main/components/OnboardingAssessment.jsx): `components/OnboardingAssessment.jsx`
- [Learning modules](https://github.com/jagadeesh54g/qniverse/blob/main/app/learn/page.jsx): `app/learn/page.jsx`
- [Lesson content](https://github.com/jagadeesh54g/qniverse/blob/main/lib/lessons.js): `lib/lessons.js`
- [Progress view](https://github.com/jagadeesh54g/qniverse/blob/main/app/progress/page.jsx): `app/progress/page.jsx`
- [Tutor panel](https://github.com/jagadeesh54g/qniverse/blob/main/components/TutorPanel.jsx): `components/TutorPanel.jsx`

### Quantum lab

- [Quantum playground](https://github.com/jagadeesh54g/qniverse/blob/main/app/playground/page.jsx): `app/playground/page.jsx`
- [Circuit workspace](https://github.com/jagadeesh54g/qniverse/blob/main/components/Playground.jsx): `components/Playground.jsx`
- [Statevector simulation](https://github.com/jagadeesh54g/qniverse/blob/main/lib/quantum.js): `lib/quantum.js`
- [Code parser](https://github.com/jagadeesh54g/qniverse/blob/main/lib/challenges/qasm.js): `lib/challenges/qasm.js`
- [Circuit visualization](https://github.com/jagadeesh54g/qniverse/blob/main/components/challenges/CircuitBuilder.jsx): `components/challenges/CircuitBuilder.jsx`
- [Algorithm studio](https://github.com/jagadeesh54g/qniverse/blob/main/app/algorithms/page.jsx): `app/algorithms/page.jsx`
- [Circuit challenges](https://github.com/jagadeesh54g/qniverse/blob/main/app/challenges/page.jsx): `app/challenges/page.jsx`
- [Challenge grading](https://github.com/jagadeesh54g/qniverse/blob/main/lib/challenges/grader.js): `lib/challenges/grader.js`
- [Browser Python runtime](https://github.com/jagadeesh54g/qniverse/blob/main/public/qniverse-py/worker.js): `public/qniverse-py/worker.js`
- [Python runner service](https://github.com/jagadeesh54g/qniverse/blob/main/server/main.py): `server/main.py`

### Learner services

- [Assessment API](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/onboarding/route.js): `app/api/onboarding/route.js`
- [Assessment scoring](https://github.com/jagadeesh54g/qniverse/blob/main/lib/onboarding.js): `lib/onboarding.js`
- [Progress API](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/progress/route.js): `app/api/progress/route.js`
- [Tutor API](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/tutor/route.js): `app/api/tutor/route.js`
- [Local tutor fallback](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/tutor/route.js): `app/api/tutor/route.js`
- [Sign-in](https://github.com/jagadeesh54g/qniverse/blob/main/app/sign-in/page.jsx): `app/sign-in/page.jsx`
- [Authentication API](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/auth/route.js): `app/api/auth/route.js`
- [Session handling](https://github.com/jagadeesh54g/qniverse/blob/main/lib/auth.js): `lib/auth.js`

### Community

- [Community](https://github.com/jagadeesh54g/qniverse/blob/main/app/community/page.jsx): `app/community/page.jsx`
- [Posts and replies API](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/community/posts/route.js): `app/api/community/posts/route.js`
- [Reply API](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/community/replies/route.js): `app/api/community/replies/route.js`
- [Likes API](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/community/like/route.js): `app/api/community/like/route.js`
- [Student directory API](https://github.com/jagadeesh54g/qniverse/blob/main/app/api/community/students/route.js): `app/api/community/students/route.js`

### Other components

- **Learner**
- **Qwen service**
- **MongoDB**

## Connections

- Learner → Landing: opens
- Learner → Learning assessment: assesses
- Learner → Learning modules: studies
- Learner → Quantum playground: experiments
- Learner → Algorithm studio: explores
- Learner → Circuit challenges: practices
- Learner → Sign-in: signs in
- Learner → Community: participates
- Assessment UI → Assessment API: submits answers
- Assessment API → Assessment scoring: scores
- Assessment API → MongoDB: writes profile
- Assessment API → Assessment scoring: uses scoring
- Learning modules → Lesson content: loads content
- Circuit workspace → Statevector simulation: simulates circuits
- Circuit workspace → Code parser: parses code
- Circuit workspace → Circuit visualization: visualizes circuits
- Circuit challenges → Challenge grading: validates solutions
- Progress view → Progress API: loads and saves
- Progress API → MongoDB: reads and writes
- Tutor panel → Tutor API: asks questions
- Tutor API → Qwen service: requests answer
- Tutor API → Local tutor fallback: falls back
- Sign-in → Authentication API: submits credentials
- Authentication API → Session handling: creates session
- Authentication API → MongoDB: reads and writes
- Community → Posts and replies API: loads and posts
- Community → Reply API: submits replies
- Community → Likes API: likes posts
- Community → Student directory API: loads students
- Posts and replies API → MongoDB: reads and writes
- Reply API → MongoDB: reads and writes
- Likes API → MongoDB: updates likes
- Student directory API → MongoDB: reads users