# shiv0xparanoid/qvanta architecture

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

- Interactive diagram: https://gitdiagram.com/shiv0xparanoid/qvanta
- Repository: https://github.com/shiv0xparanoid/qvanta

## Overview

QVANTA is a multi-tenant quantum-computing education SaaS. Its principal workflow is user authentication, circuit authoring in the web builder/editor, a tier-checked simulation request, and results displayed to the learner; separate capabilities include saved circuits, lessons, an AI tutor, and subscription billing. The graph preserves documented product branches, but several web and API implementations were not sampled, so uncertain runtime links are omitted. Simulator routing and internal queue use are supported by the source index; API-to-simulator transport is documented only indirectly and is not asserted.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/App.tsx) (Web Routes), [`apps/web/src/pages/CircuitBuilderPage.tsx`](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/CircuitBuilderPage.tsx) (Circuit Builder), [`apps/api/src/lib/prisma.ts`](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/lib/prisma.ts) (Postgres Data), [`apps/api/src/modules/billing/billing.service.ts`](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/billing/billing.service.ts) (Billing Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Learner Web App"]
  node_app["Web Routes<br/>[App.tsx]"]
  node_authui["Auth Screens<br/>[Login.tsx]"]
  node_builder["Circuit Builder"]
  node_scene["Circuit Scene<br/>[CircuitScene3D.tsx]"]
  node_editor["Qiskit Editor"]
  node_results["Simulation Results"]
  node_bloch["Bloch Views<br/>[BlochPanel.tsx]"]
  node_tutorui["Tutor Experience<br/>[Tutor.tsx]"]
  node_chat["Tutor Chat<br/>[ChatPanel.tsx]"]
  node_avatar["Tutor Avatar<br/>[AvatarScene.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_billingui["Billing Screen<br/>[Billing.tsx]"]
  node_circuitlib["Circuit Utilities<br/>[circuit.ts]"]
end

subgraph group_api["Platform API"]
  node_apiroot["API Router<br/>[main.ts]"]
  node_authroutes["Auth Routes<br/>[auth.router.ts]"]
  node_authservice["Auth Service<br/>[auth.service.ts]"]
  node_guard["Access Guard<br/>[auth.middleware.ts]"]
  node_circuits["Circuit Service"]
  node_simroutes["Simulation Routes"]
  node_usage["Usage Guard<br/>[usage-guard.ts]"]
  node_tutor["Tutor Service<br/>[tutor.service.ts]"]
  node_billing["Billing Service<br/>[billing.service.ts]"]
  node_tiers["Tier Definitions<br/>[tiers.ts]"]
  node_database[("Postgres Data<br/>[prisma.ts]")]
end

subgraph group_sim["Quantum Simulator"]
  node_simservice["Simulation Engine<br/>[simulate.py]"]
  node_simqueue["Simulation Queue<br/>[queue.py]"]
  node_simapp["Simulator App<br/>[main.py]"]
end

subgraph group_shared["Shared Packages"]
  node_types["Shared Types<br/>[index.ts]"]
end

node_learner(("Learner"))
node_stripe["Stripe"]

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_builder
node_app -->|"routes to"| node_tutorui
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_billingui
node_builder -.->|"renders"| node_scene
node_builder -.->|"syncs"| node_editor
node_builder -.->|"uses"| node_circuitlib
node_builder -.->|"submits circuit"| node_simroutes
node_simroutes -->|"checks quota"| node_usage
node_usage -->|"checks limits"| node_tiers
node_simservice -->|"dispatches work"| node_simqueue
node_simapp -->|"registers route"| node_simservice
node_simapp -->|"uses queue"| node_simqueue
node_tutorui -.->|"renders"| node_chat
node_chat -.->|"pairs with"| node_avatar
node_tutorui -.->|"sends prompts"| node_tutor
node_tutor -->|"reads course content"| node_database
node_tutor -->|"persists conversations"| node_database
node_authroutes -->|"calls"| node_authservice
node_authservice -->|"reads and writes"| node_database
node_guard -.->|"protects routes"| node_authroutes
node_apiroot -->|"mounts"| node_authroutes
node_apiroot -->|"mounts"| node_simroutes
node_apiroot -.->|"mounts tutor routes"| node_tutor
node_circuits -->|"reads and writes"| node_database
node_billingui -.->|"requests billing"| node_billing
node_billing -->|"creates checkout"| node_stripe
node_billing -->|"updates subscriptions"| node_database
node_billing -->|"selects tier"| node_tiers
node_results -.->|"shows state"| node_bloch
node_editor -.->|"parses circuit"| node_circuitlib
node_builder -.->|"saves circuits"| node_circuits

click node_app "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/App.tsx"
click node_authui "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/Login.tsx"
click node_builder "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/CircuitBuilderPage.tsx"
click node_scene "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/circuit/CircuitScene3D.tsx"
click node_editor "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/circuit/CodeEditorPanel.tsx"
click node_results "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/circuit/SimulationResults.tsx"
click node_bloch "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/circuit/BlochPanel.tsx"
click node_tutorui "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/Tutor.tsx"
click node_chat "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/tutor/ChatPanel.tsx"
click node_avatar "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/tutor/AvatarScene.tsx"
click node_dashboard "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/Dashboard.tsx"
click node_billingui "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/Billing.tsx"
click node_apiroot "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/main.ts"
click node_authroutes "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/auth/auth.router.ts"
click node_authservice "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_guard "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/auth/auth.middleware.ts"
click node_circuits "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/circuits/circuits.service.ts"
click node_simroutes "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/simulations/simulations.router.ts"
click node_usage "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/lib/billing/usage-guard.ts"
click node_tutor "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/tutor/tutor.service.ts"
click node_billing "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/billing/billing.service.ts"
click node_tiers "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/lib/billing/tiers.ts"
click node_database "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/lib/prisma.ts"
click node_simservice "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/simulator/app/routers/simulate.py"
click node_simqueue "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/simulator/app/queue.py"
click node_simapp "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/simulator/app/main.py"
click node_types "https://github.com/shiv0xparanoid/qvanta/blob/main/packages/types/src/index.ts"
click node_circuitlib "https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/lib/circuit.ts"

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_builder,node_scene,node_editor,node_results,node_bloch,node_tutorui,node_chat,node_avatar,node_dashboard,node_billingui,node_circuitlib toneBlue
class node_apiroot,node_authroutes,node_authservice,node_guard,node_circuits,node_simroutes,node_usage,node_tutor,node_billing,node_tiers,node_database toneAmber
class node_simservice,node_simqueue,node_simapp toneMint
class node_types toneRose
class node_learner,node_stripe toneIndigo
```

## Components

### Learner Web App

- [Web Routes](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Auth Screens](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/Login.tsx): `apps/web/src/pages/Login.tsx`
- [Circuit Builder](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/CircuitBuilderPage.tsx): `apps/web/src/pages/CircuitBuilderPage.tsx`
- [Circuit Scene](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/circuit/CircuitScene3D.tsx): `apps/web/src/components/circuit/CircuitScene3D.tsx`
- [Qiskit Editor](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/circuit/CodeEditorPanel.tsx): `apps/web/src/components/circuit/CodeEditorPanel.tsx`
- [Simulation Results](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/circuit/SimulationResults.tsx): `apps/web/src/components/circuit/SimulationResults.tsx`
- [Bloch Views](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/circuit/BlochPanel.tsx): `apps/web/src/components/circuit/BlochPanel.tsx`
- [Tutor Experience](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/Tutor.tsx): `apps/web/src/pages/Tutor.tsx`
- [Tutor Chat](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/tutor/ChatPanel.tsx): `apps/web/src/components/tutor/ChatPanel.tsx`
- [Tutor Avatar](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/components/tutor/AvatarScene.tsx): `apps/web/src/components/tutor/AvatarScene.tsx`
- [Dashboard](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/Dashboard.tsx): `apps/web/src/pages/Dashboard.tsx`
- [Billing Screen](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/pages/Billing.tsx): `apps/web/src/pages/Billing.tsx`
- [Circuit Utilities](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/web/src/lib/circuit.ts): `apps/web/src/lib/circuit.ts`

### Platform API

- [API Router](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/main.ts): `apps/api/src/main.ts`
- [Auth Routes](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/auth/auth.router.ts): `apps/api/src/modules/auth/auth.router.ts`
- [Auth Service](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [Access Guard](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/auth/auth.middleware.ts): `apps/api/src/modules/auth/auth.middleware.ts`
- [Circuit Service](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/circuits/circuits.service.ts): `apps/api/src/modules/circuits/circuits.service.ts`
- [Simulation Routes](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/simulations/simulations.router.ts): `apps/api/src/modules/simulations/simulations.router.ts`
- [Usage Guard](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/lib/billing/usage-guard.ts): `apps/api/src/lib/billing/usage-guard.ts`
- [Tutor Service](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/tutor/tutor.service.ts): `apps/api/src/modules/tutor/tutor.service.ts`
- [Billing Service](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/modules/billing/billing.service.ts): `apps/api/src/modules/billing/billing.service.ts`
- [Tier Definitions](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/lib/billing/tiers.ts): `apps/api/src/lib/billing/tiers.ts`
- [Postgres Data](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/api/src/lib/prisma.ts): `apps/api/src/lib/prisma.ts`

### Quantum Simulator

- [Simulation Engine](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/simulator/app/routers/simulate.py): `apps/simulator/app/routers/simulate.py`
- [Simulation Queue](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/simulator/app/queue.py): `apps/simulator/app/queue.py`
- [Simulator App](https://github.com/shiv0xparanoid/qvanta/blob/main/apps/simulator/app/main.py): `apps/simulator/app/main.py`

### Shared Packages

- [Shared Types](https://github.com/shiv0xparanoid/qvanta/blob/main/packages/types/src/index.ts): `packages/types/src/index.ts`

### Other components

- **Learner**
- **Stripe**

## Connections

- Learner → Web Routes: uses (evidence: `apps/web/src/App.tsx`)
- Web Routes → Auth Screens: routes to (evidence: `apps/web/src/App.tsx`)
- Web Routes → Circuit Builder: routes to (evidence: `apps/web/src/App.tsx`)
- Web Routes → Tutor Experience: routes to (evidence: `apps/web/src/App.tsx`)
- Web Routes → Dashboard: routes to (evidence: `apps/web/src/App.tsx`)
- Web Routes → Billing Screen: routes to (evidence: `apps/web/src/App.tsx`)
- Circuit Builder → Circuit Scene: renders
- Circuit Builder → Qiskit Editor: syncs (evidence: `README.md`)
- Circuit Builder → Circuit Utilities: uses
- Circuit Builder → Simulation Routes: submits circuit
- Simulation Routes → Usage Guard: checks quota (evidence: `apps/api/src/modules/simulations/simulations.router.ts`)
- Usage Guard → Tier Definitions: checks limits (evidence: `apps/api/src/lib/billing/usage-guard.ts`)
- Simulation Engine → Simulation Queue: dispatches work (evidence: `apps/simulator/app/routers/simulate.py`)
- Simulator App → Simulation Engine: registers route (evidence: `apps/simulator/app/main.py`)
- Simulator App → Simulation Queue: uses queue (evidence: `apps/simulator/app/main.py`)
- Tutor Experience → Tutor Chat: renders
- Tutor Chat → Tutor Avatar: pairs with (evidence: `README.md`)
- Tutor Experience → Tutor Service: sends prompts
- Tutor Service → Postgres Data: reads course content (evidence: `apps/api/src/modules/tutor/tutor.service.ts`)
- Tutor Service → Postgres Data: persists conversations (evidence: `apps/api/src/modules/tutor/tutor.service.ts`)
- Auth Routes → Auth Service: calls (evidence: `apps/api/src/modules/auth/auth.router.ts`)
- Auth Service → Postgres Data: reads and writes (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Access Guard → Auth Routes: protects routes
- API Router → Auth Routes: mounts (evidence: `apps/api/src/main.ts`)
- API Router → Simulation Routes: mounts (evidence: `apps/api/src/main.ts`)
- API Router → Tutor Service: mounts tutor routes
- Circuit Service → Postgres Data: reads and writes (evidence: `apps/api/src/modules/circuits/circuits.service.ts`)
- Billing Screen → Billing Service: requests billing
- Billing Service → Stripe: creates checkout (evidence: `apps/api/src/modules/billing/billing.service.ts`)
- Billing Service → Postgres Data: updates subscriptions (evidence: `apps/api/src/modules/billing/billing.service.ts`)
- Billing Service → Tier Definitions: selects tier (evidence: `apps/api/src/modules/billing/billing.service.ts`)
- Simulation Results → Bloch Views: shows state
- Qiskit Editor → Circuit Utilities: parses circuit
- Circuit Builder → Circuit Service: saves circuits
