# jayendra-877/qubitquest architecture

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

- Interactive diagram: https://gitdiagram.com/jayendra-877/qubitquest
- Repository: https://github.com/jayendra-877/qubitquest

## Overview

QubitQuest is a quantum-learning game: learners study theory, build circuits, run simulations, and complete challenges for progress. The frontend exposes learning, sandbox, authentication, and challenge views; the Java backend contains the richer documented domain, including saved circuits, AI assistance, and live arena matchmaking. Circuit execution is a separate Qiskit service. The tree also contains an Express API alongside the Java backend; its routing is visible, but its broader role and frontend integrations are not established by the excerpts.

Main entry points: [`frontend/src/App.jsx`](https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/App.jsx) (Route application), [`QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/AuthController.java`](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/AuthController.java) (Authentication API), [`QubitQuest-ExecutionService/app/api/execution_routes.py`](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-ExecutionService/app/api/execution_routes.py) (Execution endpoints), [`backend/routes/auth.js`](https://github.com/jayendra-877/qubitquest/blob/main/backend/routes/auth.js) (Express auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner experience"]
  node_app["Route application<br/>[App.jsx]"]
  node_authui["Login and signup"]
  node_learningui["Theory learning<br/>[Learning.jsx]"]
  node_challengeui["Challenge views"]
  node_sandboxui["Circuit sandbox<br/>[Sandbox.jsx]"]
  node_canvas["Circuit canvas<br/>[CircuitCanvas.jsx]"]
end

subgraph group_domain["Learning and play"]
  node_challengeapi["Challenge API"]
  node_challenges["Challenge workflow"]
  node_savedcircuits["Saved circuits"]
  node_arena["Live arena"]
  node_redis[("Arena state")]
end

subgraph group_identity["Identity"]
  node_authcontroller["Authentication API"]
  node_authservice["Account service"]
  node_jwt["JWT tokens"]
  node_userstore[("User records")]
end

subgraph group_simulation["Circuit simulation"]
  node_executionclient["Execution client"]
  node_execapi["Execution endpoints"]
  node_qiskit["Qiskit simulation<br/>[qiskit_service.py]"]
  node_execresult["Simulation results<br/>[circuit_models.py]"]
end

subgraph group_legacy["Express API"]
  node_express["Express API router<br/>[server.js]"]
  node_expressauth["Express auth<br/>[auth.js]"]
  node_expressmiddleware["Token middleware<br/>[authMiddleware.js]"]
  node_expressuser[("Express users<br/>[User.js]")]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_learningui
node_app -->|"routes to"| node_challengeui
node_app -->|"routes to"| node_sandboxui
node_learner -.->|"requests"| node_authcontroller
node_authcontroller -->|"delegates"| node_authservice
node_authcontroller -->|"issues token"| node_jwt
node_authservice -->|"reads and writes"| node_userstore
node_learner -.->|"requests"| node_challengeapi
node_challengeapi -->|"delegates"| node_challenges
node_learner -.->|"builds circuit"| node_canvas
node_sandboxui -.->|"submits circuit"| node_executionclient
node_challenges -.->|"runs circuit"| node_executionclient
node_executionclient -.->|"calls"| node_execapi
node_execapi -->|"runs simulation"| node_qiskit
node_execapi -->|"formats response"| node_execresult
node_learner -.->|"manages circuits"| node_savedcircuits
node_learner -.->|"plays matches"| node_arena
node_arena -.->|"stores match state"| node_redis
node_express -->|"mounts route"| node_expressauth
node_expressauth -->|"reads and writes"| node_expressuser
node_expressauth -->|"protects profile"| node_expressmiddleware

click node_app "https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/jayendra-877/qubitquest/tree/main/frontend/src/pages/Auth"
click node_learningui "https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/pages/Learning/Learning.jsx"
click node_challengeui "https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/pages/Challenges/ChallengeDetail.jsx"
click node_sandboxui "https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/pages/Sandbox/Sandbox.jsx"
click node_canvas "https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/components/CircuitCanvas/CircuitCanvas.jsx"
click node_authcontroller "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/AuthController.java"
click node_authservice "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/Impl/AuthServiceImpl.java"
click node_jwt "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/security/JwtTokenService.java"
click node_userstore "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/repository/UserRepository.java"
click node_challengeapi "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/ChallengeController.java"
click node_challenges "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/ChallengeService.java"
click node_savedcircuits "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/SavedCircuitService.java"
click node_arena "https://github.com/jayendra-877/qubitquest/tree/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service"
click node_redis "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/Impl/ArenaRedisService.java"
click node_executionclient "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/ExecutionClient.java"
click node_execapi "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-ExecutionService/app/api/execution_routes.py"
click node_qiskit "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-ExecutionService/app/services/qiskit_service.py"
click node_execresult "https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-ExecutionService/app/models/circuit_models.py"
click node_express "https://github.com/jayendra-877/qubitquest/blob/main/backend/server.js"
click node_expressauth "https://github.com/jayendra-877/qubitquest/blob/main/backend/routes/auth.js"
click node_expressmiddleware "https://github.com/jayendra-877/qubitquest/blob/main/backend/middleware/authMiddleware.js"
click node_expressuser "https://github.com/jayendra-877/qubitquest/blob/main/backend/models/User.js"

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_app,node_authui,node_learningui,node_challengeui,node_sandboxui,node_canvas toneBlue
class node_challengeapi,node_challenges,node_savedcircuits,node_arena,node_redis toneAmber
class node_authcontroller,node_authservice,node_jwt,node_userstore toneMint
class node_executionclient,node_execapi,node_qiskit,node_execresult toneRose
class node_express,node_expressauth,node_expressmiddleware,node_expressuser,node_learner toneIndigo
```

## Components

### Learner experience

- [Route application](https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Login and signup](https://github.com/jayendra-877/qubitquest/tree/main/frontend/src/pages/Auth): `frontend/src/pages/Auth`
- [Theory learning](https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/pages/Learning/Learning.jsx): `frontend/src/pages/Learning/Learning.jsx`
- [Challenge views](https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/pages/Challenges/ChallengeDetail.jsx): `frontend/src/pages/Challenges/ChallengeDetail.jsx`
- [Circuit sandbox](https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/pages/Sandbox/Sandbox.jsx): `frontend/src/pages/Sandbox/Sandbox.jsx`
- [Circuit canvas](https://github.com/jayendra-877/qubitquest/blob/main/frontend/src/components/CircuitCanvas/CircuitCanvas.jsx): `frontend/src/components/CircuitCanvas/CircuitCanvas.jsx`

### Learning and play

- [Challenge API](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/ChallengeController.java): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/ChallengeController.java`
- [Challenge workflow](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/ChallengeService.java): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/ChallengeService.java`
- [Saved circuits](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/SavedCircuitService.java): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/SavedCircuitService.java`
- [Live arena](https://github.com/jayendra-877/qubitquest/tree/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service`
- [Arena state](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/Impl/ArenaRedisService.java): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/Impl/ArenaRedisService.java`

### Identity

- [Authentication API](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/AuthController.java): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/AuthController.java`
- [Account service](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/Impl/AuthServiceImpl.java): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/Impl/AuthServiceImpl.java`
- [JWT tokens](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/security/JwtTokenService.java): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/security/JwtTokenService.java`
- [User records](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/repository/UserRepository.java): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/repository/UserRepository.java`

### Circuit simulation

- [Execution client](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/ExecutionClient.java): `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/ExecutionClient.java`
- [Execution endpoints](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-ExecutionService/app/api/execution_routes.py): `QubitQuest-ExecutionService/app/api/execution_routes.py`
- [Qiskit simulation](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-ExecutionService/app/services/qiskit_service.py): `QubitQuest-ExecutionService/app/services/qiskit_service.py`
- [Simulation results](https://github.com/jayendra-877/qubitquest/blob/main/QubitQuest-ExecutionService/app/models/circuit_models.py): `QubitQuest-ExecutionService/app/models/circuit_models.py`

### Express API

- [Express API router](https://github.com/jayendra-877/qubitquest/blob/main/backend/server.js): `backend/server.js`
- [Express auth](https://github.com/jayendra-877/qubitquest/blob/main/backend/routes/auth.js): `backend/routes/auth.js`
- [Token middleware](https://github.com/jayendra-877/qubitquest/blob/main/backend/middleware/authMiddleware.js): `backend/middleware/authMiddleware.js`
- [Express users](https://github.com/jayendra-877/qubitquest/blob/main/backend/models/User.js): `backend/models/User.js`

### Other components

- **Learner**

## Connections

- Learner → Route application: uses (evidence: `frontend/src/App.jsx`)
- Route application → Login and signup: routes to (evidence: `frontend/src/App.jsx`)
- Route application → Theory learning: routes to (evidence: `frontend/src/App.jsx`)
- Route application → Challenge views: routes to (evidence: `frontend/src/App.jsx`)
- Route application → Circuit sandbox: routes to (evidence: `frontend/src/App.jsx`)
- Learner → Authentication API: requests
- Authentication API → Account service: delegates (evidence: `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/AuthController.java`)
- Authentication API → JWT tokens: issues token (evidence: `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/AuthController.java`)
- Account service → User records: reads and writes (evidence: `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/service/Impl/AuthServiceImpl.java`)
- Learner → Challenge API: requests
- Challenge API → Challenge workflow: delegates (evidence: `QubitQuest-Backend/src/main/java/com/sih/Q_Six/QubitQuest/controller/ChallengeController.java`)
- Learner → Circuit canvas: builds circuit
- Circuit sandbox → Execution client: submits circuit
- Challenge workflow → Execution client: runs circuit
- Execution client → Execution endpoints: calls
- Execution endpoints → Qiskit simulation: runs simulation (evidence: `QubitQuest-ExecutionService/app/api/execution_routes.py`)
- Execution endpoints → Simulation results: formats response (evidence: `QubitQuest-ExecutionService/app/api/execution_routes.py`)
- Learner → Saved circuits: manages circuits
- Learner → Live arena: plays matches
- Live arena → Arena state: stores match state
- Express API router → Express auth: mounts route (evidence: `backend/server.js`)
- Express auth → Express users: reads and writes (evidence: `backend/routes/auth.js`)
- Express auth → Token middleware: protects profile (evidence: `backend/routes/auth.js`)
