# it4innovations/quantum-as-a-service architecture

> Architecture diagram of the GitHub repository it4innovations/quantum-as-a-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/it4innovations/quantum-as-a-service
- Repository: https://github.com/it4innovations/quantum-as-a-service

## Overview

QHEAppE provides Python access to IQM quantum hardware through LEXIS and HEAppE/QScheduler. The principal workflow is to create a provider, resolve a project resource and compatible backend, submit a circuit, then poll and retrieve results. A parallel pulse-level QPulla capability reaches IQM through a HEAppE executor. The repository also retains the older `qaas.client` API and an IQM backend-service/accounting subsystem. Connections among unsampled components are omitted where the excerpts and README do not establish runtime calls.

Main entry points: [`src/qheappe_client/qprovider.py`](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qprovider.py) (QProvider), [`src/qheappe_client/qclient.py`](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qclient.py) (Async QClient), [`src/qaas/iqm_backend/backend_service.py`](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/iqm_backend/backend_service.py) (IQM service), [`src/qheappe_client/qpulla/heappe_iqm.py`](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qpulla/heappe_iqm.py) (HEAppE IQM executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modern["QHEAppE Client"]
  node_provider["QProvider<br/>[qprovider.py]"]
  node_metadata["Resource metadata"]
  node_compat["IQM stack selector<br/>[factory.py]"]
  node_qclient["Async QClient<br/>[qclient.py]"]
  node_qbackend["Qiskit backend<br/>[qbackend.py]"]
  node_iqmbackend["IQM backend<br/>[qbackend_iqm.py]"]
end

subgraph group_pulse["Pulse Access"]
  node_qpulla["QPulla client<br/>[qpulla.py]"]
  node_executor["HEAppE IQM executor<br/>[heappe_iqm.py]"]
end

subgraph group_legacy["Legacy QaaS Client"]
  node_legacyprovider["Legacy provider<br/>[provider.py]"]
  node_legacybackend["Legacy backend<br/>[backend.py]"]
  node_legacyiqm["Legacy IQM backend<br/>[backend_iqm.py]"]
  node_legacyclient["Legacy client<br/>[client.py]"]
  node_legacypulla["Legacy QPulla<br/>[qpulla.py]"]
end

subgraph group_service["IQM Backend Service"]
  node_service["IQM service<br/>[backend_service.py]"]
  node_accounting["Accounting info"]
  node_consumption["Consumption tracking"]
  node_accountdb[("Accounting models")]
end

node_user(("Quantum user"))
node_lexis["LEXIS"]
node_heappe["HEAppE / QScheduler"]
node_hardware["IQM hardware"]

node_user -->|"creates"| node_provider
node_provider -->|"resolves resource"| node_metadata
node_provider -->|"configures"| node_qclient
node_qclient -->|"authenticates and resolves"| node_lexis
node_qclient -->|"calls scheduler API"| node_heappe
node_provider -->|"selects compatible stack"| node_compat
node_provider -->|"provides backend"| node_iqmbackend
node_user -->|"transpiles and runs"| node_iqmbackend
node_iqmbackend -->|"submits jobs"| node_qclient
node_qbackend -->|"submits circuits"| node_qclient
node_user -->|"requests pulse access"| node_qpulla
node_qpulla -->|"uses executor"| node_executor
node_executor -->|"submits and tracks jobs"| node_qclient
node_executor -->|"runs via scheduler"| node_heappe
node_provider -.->|"alternative legacy API"| node_legacyprovider
node_legacyprovider -.->|"offers backend"| node_legacybackend
node_legacybackend -.->|"submits jobs"| node_legacyclient
node_legacyprovider -.->|"offers pulse access"| node_legacypulla
node_legacybackend -.->|"IQM specialization"| node_legacyiqm
node_service -->|"uses accounting data"| node_accounting
node_service -->|"records consumption"| node_consumption
node_consumption -->|"persists accounting"| node_accountdb
node_service -->|"fetches calibration"| node_hardware

click node_provider "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qprovider.py"
click node_metadata "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/backend_metadata.py"
click node_compat "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/iqm_compat/factory.py"
click node_qclient "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qclient.py"
click node_qbackend "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qiskit/qbackend.py"
click node_iqmbackend "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qiskit/qbackend_iqm.py"
click node_qpulla "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qpulla/qpulla.py"
click node_executor "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qpulla/heappe_iqm.py"
click node_legacyprovider "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/provider.py"
click node_legacybackend "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/backend.py"
click node_legacyiqm "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/backend_iqm.py"
click node_legacyclient "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/client.py"
click node_legacypulla "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/qpulla.py"
click node_service "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/iqm_backend/backend_service.py"
click node_accounting "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/iqm_backend/backend_service_accounting_info.py"
click node_consumption "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/iqm_backend/backend_service_consumption.py"
click node_accountdb "https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/iqm_backend/internal_accounting_table_models.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_provider,node_metadata,node_compat,node_qclient,node_qbackend,node_iqmbackend,node_user toneBlue
class node_qpulla,node_executor toneAmber
class node_legacyprovider,node_legacybackend,node_legacyiqm,node_legacyclient,node_legacypulla toneMint
class node_service,node_accounting,node_consumption,node_accountdb,node_heappe toneRose
class node_lexis,node_hardware toneIndigo
```

## Components

### QHEAppE Client

- [QProvider](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qprovider.py): `src/qheappe_client/qprovider.py`
- [Resource metadata](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/backend_metadata.py): `src/qheappe_client/backend_metadata.py`
- [IQM stack selector](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/iqm_compat/factory.py): `src/qheappe_client/iqm_compat/factory.py`
- [Async QClient](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qclient.py): `src/qheappe_client/qclient.py`
- [Qiskit backend](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qiskit/qbackend.py): `src/qheappe_client/qiskit/qbackend.py`
- [IQM backend](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qiskit/qbackend_iqm.py): `src/qheappe_client/qiskit/qbackend_iqm.py`

### Pulse Access

- [QPulla client](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qpulla/qpulla.py): `src/qheappe_client/qpulla/qpulla.py`
- [HEAppE IQM executor](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qheappe_client/qpulla/heappe_iqm.py): `src/qheappe_client/qpulla/heappe_iqm.py`

### Legacy QaaS Client

- [Legacy provider](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/provider.py): `src/qaas/client/provider.py`
- [Legacy backend](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/backend.py): `src/qaas/client/backend.py`
- [Legacy IQM backend](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/backend_iqm.py): `src/qaas/client/backend_iqm.py`
- [Legacy client](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/client.py): `src/qaas/client/client.py`
- [Legacy QPulla](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/client/qpulla.py): `src/qaas/client/qpulla.py`

### IQM Backend Service

- [IQM service](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/iqm_backend/backend_service.py): `src/qaas/iqm_backend/backend_service.py`
- [Accounting info](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/iqm_backend/backend_service_accounting_info.py): `src/qaas/iqm_backend/backend_service_accounting_info.py`
- [Consumption tracking](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/iqm_backend/backend_service_consumption.py): `src/qaas/iqm_backend/backend_service_consumption.py`
- [Accounting models](https://github.com/it4innovations/quantum-as-a-service/blob/main/src/qaas/iqm_backend/internal_accounting_table_models.py): `src/qaas/iqm_backend/internal_accounting_table_models.py`

### Other components

- **Quantum user**
- **LEXIS**
- **HEAppE / QScheduler**
- **IQM hardware**

## Connections

- Quantum user → QProvider: creates (evidence: `README.rst`)
- QProvider → Resource metadata: resolves resource (evidence: `src/qheappe_client/qprovider.py`)
- QProvider → Async QClient: configures (evidence: `src/qheappe_client/qprovider.py`)
- Async QClient → LEXIS: authenticates and resolves (evidence: `src/qheappe_client/qclient.py`)
- Async QClient → HEAppE / QScheduler: calls scheduler API (evidence: `src/qheappe_client/qclient.py`)
- QProvider → IQM stack selector: selects compatible stack (evidence: `src/qheappe_client/qprovider.py`)
- QProvider → IQM backend: provides backend (evidence: `README.rst`)
- Quantum user → IQM backend: transpiles and runs (evidence: `README.rst`)
- IQM backend → Async QClient: submits jobs (evidence: `src/qheappe_client/qiskit/qbackend_iqm.py`)
- Qiskit backend → Async QClient: submits circuits (evidence: `src/qheappe_client/qiskit/qbackend.py`)
- Quantum user → QPulla client: requests pulse access (evidence: `README.rst`)
- QPulla client → HEAppE IQM executor: uses executor (evidence: `src/qheappe_client/qpulla/qpulla.py`)
- HEAppE IQM executor → Async QClient: submits and tracks jobs (evidence: `src/qheappe_client/qpulla/heappe_iqm.py`)
- HEAppE IQM executor → HEAppE / QScheduler: runs via scheduler (evidence: `src/qheappe_client/qpulla/heappe_iqm.py`)
- QProvider → Legacy provider: alternative legacy API (evidence: `README.rst`)
- Legacy provider → Legacy backend: offers backend (evidence: `src/qaas/client/provider.py`)
- Legacy backend → Legacy client: submits jobs (evidence: `src/qaas/client/backend.py`)
- Legacy provider → Legacy QPulla: offers pulse access (evidence: `src/qaas/client/provider.py`)
- Legacy backend → Legacy IQM backend: IQM specialization (evidence: `src/qaas/client/backend_iqm.py`)
- IQM service → Accounting info: uses accounting data (evidence: `src/qaas/iqm_backend/backend_service.py`)
- IQM service → Consumption tracking: records consumption (evidence: `src/qaas/iqm_backend/backend_service.py`)
- Consumption tracking → Accounting models: persists accounting (evidence: `src/qaas/iqm_backend/backend_service_consumption.py`)
- IQM service → IQM hardware: fetches calibration (evidence: `src/qaas/iqm_backend/backend_service.py`)