# saisankarbommala/qois architecture

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

- Interactive diagram: https://gitdiagram.com/saisankarbommala/qois
- Repository: https://github.com/saisankarbommala/qois

## Overview

QOIS is a web platform for composing quantum jobs, submitting them to IBM Quantum, and monitoring results. Users enter through the React application, authenticate, create and inspect jobs, then submit them through the backend; a background worker polls IBM and broadcasts status changes. The README also describes circuit building, OpenQASM editing, backend recommendations, and predictive queue analytics. Those capabilities are represented where the tree supports them, but unsampled implementations and their wiring are not assumed; dashed links mark documented or unverified connections.

Main entry points: [`frontend/src/App.jsx`](https://github.com/saisankarbommala/qois/blob/main/frontend/src/App.jsx) (React app), [`backend/server.js`](https://github.com/saisankarbommala/qois/blob/main/backend/server.js) (API server), [`backend/controllers/jobController.js`](https://github.com/saisankarbommala/qois/blob/main/backend/controllers/jobController.js) (Job controller), [`backend/services/jobWorker.js`](https://github.com/saisankarbommala/qois/blob/main/backend/services/jobWorker.js) (Job worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_app["React app<br/>[App.jsx]"]
  node_home["Circuit workspace<br/>[Home.jsx]"]
  node_dashboard["Execution dashboard<br/>[Dashboard.jsx]"]
  node_hiring["Job dashboard"]
  node_submission["Job composer<br/>[JobSubmission.jsx]"]
  node_details["Job details<br/>[JobDetails.jsx]"]
end

subgraph group_identity["Identity"]
  node_authcontext["Auth context<br/>[AuthContext.jsx]"]
  node_authapi["Auth client<br/>[authApi.js]"]
  node_authroutes["Auth routes<br/>[authRoutes.js]"]
  node_authcontroller["Auth controller<br/>[AuthController.js]"]
  node_users[("User records<br/>[User.js]")]
  node_otps[("OTP records<br/>[Otp.js]")]
end

subgraph group_jobs["Job lifecycle"]
  node_jobroutes["Job routes<br/>[jobRoutes.js]"]
  node_jobcontroller["Job controller<br/>[jobController.js]"]
  node_jobrecords[("Job records<br/>[Job.js]")]
  node_worker["Job worker<br/>[jobWorker.js]"]
end

subgraph group_intelligence["Quantum intelligence"]
  node_intelligence["Circuit intelligence"]
  node_optimization["Scheduling optimization"]
  node_estimation["Job estimation"]
end

subgraph group_platform["Runtime platform"]
  node_server["API server<br/>[server.js]"]
  node_socket["Live updates<br/>[socket.js]"]
  node_ibmservice["IBM adapter<br/>[ibmService.js]"]
end

node_user(("Quantum user"))
node_mongodb[("MongoDB")]
node_ibm{{"IBM Quantum"}}

node_user -.->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_hiring
node_app -->|"routes to"| node_submission
node_app -->|"routes to"| node_details
node_app -->|"provides auth"| node_authcontext
node_authcontext -->|"loads user"| node_authapi
node_authapi -.->|"calls API"| node_authroutes
node_server -->|"mounts"| node_authroutes
node_authroutes -->|"dispatches"| node_authcontroller
node_authcontroller -->|"reads/writes"| node_users
node_authcontroller -->|"reads/writes"| node_otps
node_server -->|"mounts"| node_jobroutes
node_jobroutes -->|"dispatches"| node_jobcontroller
node_jobcontroller -->|"reads/writes"| node_jobrecords
node_jobcontroller -->|"submits jobs"| node_ibmservice
node_jobcontroller -->|"emits updates"| node_socket
node_server -->|"starts worker"| node_worker
node_worker -->|"reads/writes"| node_jobrecords
node_worker -->|"polls status"| node_ibmservice
node_worker -->|"emits updates"| node_socket
node_server -->|"initializes"| node_socket
node_ibmservice -->|"calls runtime"| node_ibm
node_server -->|"connects"| node_mongodb
node_dashboard -.->|"receives updates"| node_socket
node_submission -.->|"uses analysis"| node_intelligence
node_intelligence -.->|"supports scheduling"| node_optimization
node_optimization -.->|"informs estimates"| node_estimation

click node_app "https://github.com/saisankarbommala/qois/blob/main/frontend/src/App.jsx"
click node_home "https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/Home.jsx"
click node_dashboard "https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/Dashboard.jsx"
click node_hiring "https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/HiringDashboard.jsx"
click node_submission "https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/JobSubmission.jsx"
click node_details "https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/JobDetails.jsx"
click node_authcontext "https://github.com/saisankarbommala/qois/blob/main/frontend/src/context/AuthContext.jsx"
click node_authapi "https://github.com/saisankarbommala/qois/blob/main/frontend/src/authApi.js"
click node_authroutes "https://github.com/saisankarbommala/qois/blob/main/backend/routes/authRoutes.js"
click node_authcontroller "https://github.com/saisankarbommala/qois/blob/main/backend/controllers/AuthController.js"
click node_users "https://github.com/saisankarbommala/qois/blob/main/backend/models/User.js"
click node_otps "https://github.com/saisankarbommala/qois/blob/main/backend/models/Otp.js"
click node_jobroutes "https://github.com/saisankarbommala/qois/blob/main/backend/routes/jobRoutes.js"
click node_jobcontroller "https://github.com/saisankarbommala/qois/blob/main/backend/controllers/jobController.js"
click node_jobrecords "https://github.com/saisankarbommala/qois/blob/main/backend/models/Job.js"
click node_worker "https://github.com/saisankarbommala/qois/blob/main/backend/services/jobWorker.js"
click node_intelligence "https://github.com/saisankarbommala/qois/blob/main/backend/utils/circuitIntelligence.js"
click node_optimization "https://github.com/saisankarbommala/qois/blob/main/backend/services/optimizationService.js"
click node_estimation "https://github.com/saisankarbommala/qois/blob/main/backend/services/estimationService.js"
click node_server "https://github.com/saisankarbommala/qois/blob/main/backend/server.js"
click node_socket "https://github.com/saisankarbommala/qois/blob/main/backend/utils/socket.js"
click node_ibmservice "https://github.com/saisankarbommala/qois/blob/main/backend/services/ibmService.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_home,node_dashboard,node_hiring,node_submission,node_details,node_user toneBlue
class node_authcontext,node_authapi,node_authroutes,node_authcontroller,node_users,node_otps,node_mongodb toneAmber
class node_jobroutes,node_jobcontroller,node_jobrecords,node_worker toneMint
class node_intelligence,node_optimization,node_estimation toneRose
class node_server,node_socket,node_ibmservice,node_ibm toneIndigo
```

## Components

### Web experience

- [React app](https://github.com/saisankarbommala/qois/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Circuit workspace](https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/Home.jsx): `frontend/src/pages/Home.jsx`
- [Execution dashboard](https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Job dashboard](https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/HiringDashboard.jsx): `frontend/src/pages/HiringDashboard.jsx`
- [Job composer](https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/JobSubmission.jsx): `frontend/src/pages/JobSubmission.jsx`
- [Job details](https://github.com/saisankarbommala/qois/blob/main/frontend/src/pages/JobDetails.jsx): `frontend/src/pages/JobDetails.jsx`

### Identity

- [Auth context](https://github.com/saisankarbommala/qois/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Auth client](https://github.com/saisankarbommala/qois/blob/main/frontend/src/authApi.js): `frontend/src/authApi.js`
- [Auth routes](https://github.com/saisankarbommala/qois/blob/main/backend/routes/authRoutes.js): `backend/routes/authRoutes.js`
- [Auth controller](https://github.com/saisankarbommala/qois/blob/main/backend/controllers/AuthController.js): `backend/controllers/AuthController.js`
- [User records](https://github.com/saisankarbommala/qois/blob/main/backend/models/User.js): `backend/models/User.js`
- [OTP records](https://github.com/saisankarbommala/qois/blob/main/backend/models/Otp.js): `backend/models/Otp.js`

### Job lifecycle

- [Job routes](https://github.com/saisankarbommala/qois/blob/main/backend/routes/jobRoutes.js): `backend/routes/jobRoutes.js`
- [Job controller](https://github.com/saisankarbommala/qois/blob/main/backend/controllers/jobController.js): `backend/controllers/jobController.js`
- [Job records](https://github.com/saisankarbommala/qois/blob/main/backend/models/Job.js): `backend/models/Job.js`
- [Job worker](https://github.com/saisankarbommala/qois/blob/main/backend/services/jobWorker.js): `backend/services/jobWorker.js`

### Quantum intelligence

- [Circuit intelligence](https://github.com/saisankarbommala/qois/blob/main/backend/utils/circuitIntelligence.js): `backend/utils/circuitIntelligence.js`
- [Scheduling optimization](https://github.com/saisankarbommala/qois/blob/main/backend/services/optimizationService.js): `backend/services/optimizationService.js`
- [Job estimation](https://github.com/saisankarbommala/qois/blob/main/backend/services/estimationService.js): `backend/services/estimationService.js`

### Runtime platform

- [API server](https://github.com/saisankarbommala/qois/blob/main/backend/server.js): `backend/server.js`
- [Live updates](https://github.com/saisankarbommala/qois/blob/main/backend/utils/socket.js): `backend/utils/socket.js`
- [IBM adapter](https://github.com/saisankarbommala/qois/blob/main/backend/services/ibmService.js): `backend/services/ibmService.js`

### Other components

- **Quantum user**
- **MongoDB**
- **IBM Quantum**

## Connections

- Quantum user → React app: uses (evidence: `README.md`)
- React app → Circuit workspace: routes to (evidence: `frontend/src/App.jsx`)
- React app → Execution dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React app → Job dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React app → Job composer: routes to (evidence: `frontend/src/App.jsx`)
- React app → Job details: routes to (evidence: `frontend/src/App.jsx`)
- React app → Auth context: provides auth (evidence: `frontend/src/App.jsx`)
- Auth context → Auth client: loads user (evidence: `frontend/src/context/AuthContext.jsx`)
- Auth client → Auth routes: calls API (evidence: `README.md`)
- API server → Auth routes: mounts (evidence: `backend/server.js`)
- Auth routes → Auth controller: dispatches (evidence: `backend/routes/authRoutes.js`)
- Auth controller → User records: reads/writes (evidence: `backend/controllers/AuthController.js`)
- Auth controller → OTP records: reads/writes (evidence: `backend/controllers/AuthController.js`)
- API server → Job routes: mounts (evidence: `backend/server.js`)
- Job routes → Job controller: dispatches (evidence: `backend/routes/jobRoutes.js`)
- Job controller → Job records: reads/writes (evidence: `backend/controllers/jobController.js`)
- Job controller → IBM adapter: submits jobs (evidence: `backend/controllers/jobController.js`)
- Job controller → Live updates: emits updates (evidence: `backend/controllers/jobController.js`)
- API server → Job worker: starts worker (evidence: `backend/server.js`)
- Job worker → Job records: reads/writes (evidence: `backend/services/jobWorker.js`)
- Job worker → IBM adapter: polls status (evidence: `backend/services/jobWorker.js`)
- Job worker → Live updates: emits updates (evidence: `backend/services/jobWorker.js`)
- API server → Live updates: initializes (evidence: `backend/server.js`)
- IBM adapter → IBM Quantum: calls runtime (evidence: `backend/services/ibmService.js`)
- API server → MongoDB: connects (evidence: `backend/server.js`)
- Execution dashboard → Live updates: receives updates (evidence: `README.md`)
- Job composer → Circuit intelligence: uses analysis
- Circuit intelligence → Scheduling optimization: supports scheduling
- Scheduling optimization → Job estimation: informs estimates
