# devus-org/devq architecture

> Architecture diagram of the GitHub repository devus-org/devq, 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/devus-org/devq
- Repository: https://github.com/devus-org/devq
- Video tour (about a minute): https://gitdiagram.com/devus-org/devq/video

## Overview

DevQ is quantum execution middleware: users submit OpenQASM jobs through QShell, which parses them into a hardware-independent circuit representation; the kernel manages job lifecycle, routes each job to one feasible device, and that device’s local scheduler and allocator prepare execution through a provider. Users can inspect devices, errors, mappings, and job activity in the shell. The graph follows the documented architecture and sampled module roles; some internal wiring and individual shell inspection commands are based on README descriptions rather than sampled implementations.

Main entry points: [`kernel/kernel.py`](https://github.com/devus-org/devq/blob/main/kernel/kernel.py) (Kernel), [`shell/qshell.py`](https://github.com/devus-org/devq/blob/main/shell/qshell.py) (QShell), [`providers/base_provider.py`](https://github.com/devus-org/devq/blob/main/providers/base_provider.py) (Provider Contract), [`kernel/device_context.py`](https://github.com/devus-org/devq/blob/main/kernel/device_context.py) (Device Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_shell["QShell<br/>[qshell.py]"]
  node_shell_parser["Job Parser<br/>[parser.py]"]
end

subgraph group_circuits["Circuit Frontends"]
  node_frontend_resolver["Frontend Resolver<br/>[resolver.py]"]
  node_qasm_frontend["QASM2 Frontend<br/>[qasm2_frontend.py]"]
  node_qasm_parser["QASM2 Parser<br/>[parser.py]"]
  node_circuit["CircuitRep<br/>[circuit_rep.py]"]
  node_result["Execution Result"]
end

subgraph group_kernel["Kernel Orchestration"]
  node_kernel["Kernel<br/>[kernel.py]"]
  node_qcb["Job Control Block<br/>[qcb.py]"]
  node_process_table[("Process Table<br/>[process_table.py]")]
  node_lifecycle["Job Lifecycle<br/>[lifecycle.py]"]
  node_router["Device Router<br/>[base_router.py]"]
  node_noise_router["Noise Router<br/>[noise_router.py]"]
  node_events["Kernel Events<br/>[events.py]"]
end

subgraph group_devices["Device Execution"]
  node_context["Device Context<br/>[device_context.py]"]
  node_scheduler["Job Scheduler<br/>[base_scheduler.py]"]
  node_memory["Memory Manager<br/>[memory_manager.py]"]
  node_allocator["Qubit Allocator<br/>[base_allocator.py]"]
  node_qubit_pool[("Qubit Pool<br/>[qubit_pool.py]")]
end

subgraph group_providers["Providers"]
  node_device["Quantum Device<br/>[device.py]"]
  node_provider["Provider Contract<br/>[base_provider.py]"]
  node_devq_provider["DevQ Simulator"]
  node_ibm_provider["IBM Providers<br/>[ibm_provider.py]"]
end

node_user(("User"))
node_backend(("Quantum Backend"))

node_user -->|"submits jobs"| node_shell
node_user -->|"inspects runtime"| node_shell
node_shell -->|"parses arguments"| node_shell_parser
node_shell -->|"selects frontend"| node_frontend_resolver
node_frontend_resolver -->|"dispatches source"| node_qasm_frontend
node_qasm_frontend -->|"parses QASM"| node_qasm_parser
node_qasm_parser -->|"builds circuit"| node_circuit
node_shell -->|"submits circuit"| node_kernel
node_kernel -->|"creates job"| node_qcb
node_kernel -->|"tracks jobs"| node_process_table
node_kernel -->|"advances state"| node_lifecycle
node_kernel -->|"routes job"| node_router
node_router -->|"selects policy"| node_noise_router
node_router -->|"checks candidates"| node_context
node_kernel -->|"dispatches job"| node_context
node_context -->|"queues job"| node_scheduler
node_scheduler -->|"requests qubits"| node_memory
node_memory -->|"allocates circuit"| node_allocator
node_memory -->|"reserves qubits"| node_qubit_pool
node_context -->|"targets device"| node_device
node_device -->|"executes through"| node_provider
node_devq_provider -->|"implements"| node_provider
node_ibm_provider -->|"implements"| node_provider
node_provider -.->|"submits execution"| node_backend
node_backend -.->|"returns results"| node_provider
node_provider -->|"produces result"| node_result
node_kernel -->|"records activity"| node_events
node_shell -->|"displays events"| node_events
node_shell -->|"inspects devices"| node_context

click node_shell "https://github.com/devus-org/devq/blob/main/shell/qshell.py"
click node_shell_parser "https://github.com/devus-org/devq/blob/main/shell/parser.py"
click node_frontend_resolver "https://github.com/devus-org/devq/blob/main/frontends/resolver.py"
click node_qasm_frontend "https://github.com/devus-org/devq/blob/main/frontends/qasm2/qasm2_frontend.py"
click node_qasm_parser "https://github.com/devus-org/devq/blob/main/frontends/qasm2/parser.py"
click node_circuit "https://github.com/devus-org/devq/blob/main/circuits/circuit_rep.py"
click node_kernel "https://github.com/devus-org/devq/blob/main/kernel/kernel.py"
click node_qcb "https://github.com/devus-org/devq/blob/main/kernel/process/qcb.py"
click node_process_table "https://github.com/devus-org/devq/blob/main/kernel/process/process_table.py"
click node_lifecycle "https://github.com/devus-org/devq/blob/main/kernel/process/lifecycle.py"
click node_router "https://github.com/devus-org/devq/blob/main/kernel/router/base_router.py"
click node_noise_router "https://github.com/devus-org/devq/blob/main/kernel/router/noise_router.py"
click node_context "https://github.com/devus-org/devq/blob/main/kernel/device_context.py"
click node_scheduler "https://github.com/devus-org/devq/blob/main/kernel/scheduler/base_scheduler.py"
click node_memory "https://github.com/devus-org/devq/blob/main/kernel/memory/memory_manager.py"
click node_allocator "https://github.com/devus-org/devq/blob/main/kernel/memory/allocators/base_allocator.py"
click node_qubit_pool "https://github.com/devus-org/devq/blob/main/kernel/memory/qubit_pool.py"
click node_device "https://github.com/devus-org/devq/blob/main/hardware/device.py"
click node_provider "https://github.com/devus-org/devq/blob/main/providers/base_provider.py"
click node_devq_provider "https://github.com/devus-org/devq/blob/main/providers/devq/devq_simulated_provider.py"
click node_ibm_provider "https://github.com/devus-org/devq/blob/main/providers/ibm/ibm_provider.py"
click node_result "https://github.com/devus-org/devq/blob/main/circuits/execution_result.py"
click node_events "https://github.com/devus-org/devq/blob/main/kernel/events.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_shell,node_shell_parser,node_user toneBlue
class node_frontend_resolver,node_qasm_frontend,node_qasm_parser,node_circuit,node_result toneAmber
class node_kernel,node_qcb,node_process_table,node_lifecycle,node_router,node_noise_router,node_events toneMint
class node_context,node_scheduler,node_memory,node_allocator,node_qubit_pool toneRose
class node_device,node_provider,node_devq_provider,node_ibm_provider,node_backend toneIndigo
```

## Components

### User Interface

- [QShell](https://github.com/devus-org/devq/blob/main/shell/qshell.py): `shell/qshell.py`
- [Job Parser](https://github.com/devus-org/devq/blob/main/shell/parser.py): `shell/parser.py`

### Circuit Frontends

- [Frontend Resolver](https://github.com/devus-org/devq/blob/main/frontends/resolver.py): `frontends/resolver.py`
- [QASM2 Frontend](https://github.com/devus-org/devq/blob/main/frontends/qasm2/qasm2_frontend.py): `frontends/qasm2/qasm2_frontend.py`
- [QASM2 Parser](https://github.com/devus-org/devq/blob/main/frontends/qasm2/parser.py): `frontends/qasm2/parser.py`
- [CircuitRep](https://github.com/devus-org/devq/blob/main/circuits/circuit_rep.py): `circuits/circuit_rep.py`
- [Execution Result](https://github.com/devus-org/devq/blob/main/circuits/execution_result.py): `circuits/execution_result.py`

### Kernel Orchestration

- [Kernel](https://github.com/devus-org/devq/blob/main/kernel/kernel.py): `kernel/kernel.py`
- [Job Control Block](https://github.com/devus-org/devq/blob/main/kernel/process/qcb.py): `kernel/process/qcb.py`
- [Process Table](https://github.com/devus-org/devq/blob/main/kernel/process/process_table.py): `kernel/process/process_table.py`
- [Job Lifecycle](https://github.com/devus-org/devq/blob/main/kernel/process/lifecycle.py): `kernel/process/lifecycle.py`
- [Device Router](https://github.com/devus-org/devq/blob/main/kernel/router/base_router.py): `kernel/router/base_router.py`
- [Noise Router](https://github.com/devus-org/devq/blob/main/kernel/router/noise_router.py): `kernel/router/noise_router.py`
- [Kernel Events](https://github.com/devus-org/devq/blob/main/kernel/events.py): `kernel/events.py`

### Device Execution

- [Device Context](https://github.com/devus-org/devq/blob/main/kernel/device_context.py): `kernel/device_context.py`
- [Job Scheduler](https://github.com/devus-org/devq/blob/main/kernel/scheduler/base_scheduler.py): `kernel/scheduler/base_scheduler.py`
- [Memory Manager](https://github.com/devus-org/devq/blob/main/kernel/memory/memory_manager.py): `kernel/memory/memory_manager.py`
- [Qubit Allocator](https://github.com/devus-org/devq/blob/main/kernel/memory/allocators/base_allocator.py): `kernel/memory/allocators/base_allocator.py`
- [Qubit Pool](https://github.com/devus-org/devq/blob/main/kernel/memory/qubit_pool.py): `kernel/memory/qubit_pool.py`

### Providers

- [Quantum Device](https://github.com/devus-org/devq/blob/main/hardware/device.py): `hardware/device.py`
- [Provider Contract](https://github.com/devus-org/devq/blob/main/providers/base_provider.py): `providers/base_provider.py`
- [DevQ Simulator](https://github.com/devus-org/devq/blob/main/providers/devq/devq_simulated_provider.py): `providers/devq/devq_simulated_provider.py`
- [IBM Providers](https://github.com/devus-org/devq/blob/main/providers/ibm/ibm_provider.py): `providers/ibm/ibm_provider.py`

### Other components

- **User**
- **Quantum Backend**

## Connections

- User → QShell: submits jobs
- User → QShell: inspects runtime
- QShell → Job Parser: parses arguments
- QShell → Frontend Resolver: selects frontend
- Frontend Resolver → QASM2 Frontend: dispatches source
- QASM2 Frontend → QASM2 Parser: parses QASM
- QASM2 Parser → CircuitRep: builds circuit
- QShell → Kernel: submits circuit
- Kernel → Job Control Block: creates job
- Kernel → Process Table: tracks jobs
- Kernel → Job Lifecycle: advances state
- Kernel → Device Router: routes job
- Device Router → Noise Router: selects policy
- Device Router → Device Context: checks candidates
- Kernel → Device Context: dispatches job
- Device Context → Job Scheduler: queues job
- Job Scheduler → Memory Manager: requests qubits
- Memory Manager → Qubit Allocator: allocates circuit
- Memory Manager → Qubit Pool: reserves qubits
- Device Context → Quantum Device: targets device
- Quantum Device → Provider Contract: executes through
- DevQ Simulator → Provider Contract: implements
- IBM Providers → Provider Contract: implements
- Provider Contract → Quantum Backend: submits execution
- Quantum Backend → Provider Contract: returns results
- Provider Contract → Execution Result: produces result
- Kernel → Kernel Events: records activity
- QShell → Kernel Events: displays events
- QShell → Device Context: inspects devices