# qiskit/qiskit-serverless architecture

> Architecture diagram of the GitHub repository qiskit/qiskit-serverless, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qiskit/qiskit-serverless
- Repository: https://github.com/qiskit/qiskit-serverless

## Overview

##### Project type and purpose
- This repository implements “Qiskit Serverless,” a full-stack, distributed quantum-classical execution platform.
- It consists of three modules:
- A Python “client” library for users to define and submit Qiskit Functions.
- A “gateway” service (Django/ASGI) exposing REST APIs, handling authentication, job metadata, and scheduling.
- Kubernetes/Helm “charts” to deploy gateway, Ray compute cluster, database, storage, and supporting services.

##### File structure
- Top-level directories:
- client/ – Python SDK and CLI
- gateway/ – Django-based API server and job scheduler scripts
- charts/ – Helm chart definitions for Kubernetes deployment
- Other orchestrations:
- Dockerfile-ray-node, docker-compose*.yaml, Makefile — for local Docker-based setups
- .github/workflows – CI/CD pipelines for building client, gateway, Helm chart and running tests
- gateway/api: MVC-style organization with models, serializers, views, services, use-cases, and repositories
- charts/qiskit-serverless: Helm templates for gateway, Ray head/worker, Postgres, PVCs, ingress, hpa, secrets

##### Key insights from README
- Purpose: let users submit long-running Qiskit Functions that automatically scale across CPUs, GPUs, QPUs
- Quickstart:
- Docker Compose for local dev (components: gateway, ray-head, scheduler, postgres)
- Kubernetes via Helm/Kind for production-like deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Environment"
        Client["Client Library (Python SDK)"]:::client
    end

    subgraph "Kubernetes Cluster"
        subgraph "API & Scheduler Layer"
            API["Gateway API Service (Django ASGI)"]:::api
            Scheduler["Scheduler Service"]:::api
        end

        subgraph "Compute Layer"
            RayHead["Ray Head"]:::compute
            RayWorkers["Ray Workers (autoscaled)"]:::compute
        end

        subgraph "Storage Layer"
            Database["PostgreSQL Database"]:::storage
            ArtifactStore["Artifact Storage"]:::storage
        end

        subgraph "Infrastructure"
            Ingress["Ingress Controller"]:::infra
            Configs["ConfigMaps & Secrets"]:::infra
            DockerCompose["Docker Compose (Local Dev)"]:::infra
            HelmChart["Helm Chart"]:::infra
        end
    end

    subgraph "External Services"
        IBMQuantum["IBM Quantum Backend"]:::external
        CI["GitHub Actions CI/CD"]:::external
    end

    %% Relationships
    Client -->|"HTTP/REST: submit/query/cancel jobs"| API
    API -->|"enqueue jobs"| Scheduler
    Scheduler -->|"Ray Client: submit job defs"| RayHead
    RayHead -->|"distribute tasks"| RayWorkers
    RayWorkers -->|"read/write artifacts"| ArtifactStore
    API -->|"read/write artifacts"| ArtifactStore
    API -->|"persist metadata"| Database
    Scheduler -->|"update job status"| Database
    API -->|"auth & job creds"| IBMQuantum
    Ingress -->|routes traffic| API
    Configs --> API
    Configs --> RayHead
    Configs --> RayWorkers
    DockerCompose -.->|local compose| API
    DockerCompose -.->|local compose| RayHead
    HelmChart -.->|deploys| API
    HelmChart -.->|deploys| RayHead
    CI -.->|CI/CD pipelines| DockerCompose
    CI -.->|CI/CD pipelines| HelmChart

    %% Click Events
    click Client "https://github.com/qiskit/qiskit-serverless/tree/main/client/qiskit_serverless"
    click API "https://github.com/qiskit/qiskit-serverless/tree/main/gateway/api/"
    click Scheduler "https://github.com/qiskit/qiskit-serverless/blob/main/gateway/api/management/commands/schedule_queued_jobs.py"
    click RayHead "https://github.com/qiskit/qiskit-serverless/blob/main/gateway/api/ray.py"
    click HelmChart "https://github.com/qiskit/qiskit-serverless/blob/main/charts/qiskit-serverless/Chart.yaml"
    click Ingress "https://github.com/qiskit/qiskit-serverless/blob/main/charts/qiskit-serverless/templates/ingress.yaml"
    click Database "https://github.com/qiskit/qiskit-serverless/blob/main/charts/qiskit-serverless/charts/gateway/templates/secret-psql.yaml"
    click ArtifactStore "https://github.com/qiskit/qiskit-serverless/blob/main/gateway/api/services/file_storage.py"
    click IBMQuantum "https://github.com/qiskit/qiskit-serverless/blob/main/gateway/api/services/authentication/ibm_quantum.py"
    click DockerCompose "https://github.com/qiskit/qiskit-serverless/blob/main/docker-compose.yaml"
    click CI "https://github.com/qiskit/qiskit-serverless/blob/main/.github/workflows/build-containers-test.yaml"

    %% Styles
    classDef client fill:#D6EAF8,stroke:#2980B9,color:#154360;
    classDef api fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef compute fill:#FCF3CF,stroke:#F1C40F,color:#8E44AD;
    classDef storage fill:#FADBD8,stroke:#E74C3C,color:#78281F;
    classDef infra fill:#E8DAEF,stroke:#9B59B6,color:#512E5F;
    classDef external fill:#F0F3F4,stroke:#7B7D7D,color:#1B2631;
```
