# qutech-delft/compute-runtime-schema architecture

> Architecture diagram of the GitHub repository qutech-delft/compute-runtime-schema, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qutech-delft/compute-runtime-schema
- Repository: https://github.com/qutech-delft/compute-runtime-schema

## Overview

##### Project Type and Purpose
- Type: Open-source schema library + validation/testing framework
- Purpose: Provide JSON Schema definitions for initialization, execution, dynamic/static data retrieval, state publish, and termination messages between client code and quantum compute runtimes. Also include tests and docs to ensure schema correctness and generate user documentation.

##### File Structure
- Top-level directories:
– schemas/ : the core JSON Schema files, one subfolder per operation (initialize, execute, get_dynamic, get_static, publish_state, terminate).
– tests/ : two test suites
- control-software-validator/ : Python-based integration tests that import schemas and validate message flows
- schema-check/ : shell-script-driven tests that validate JSON examples against schemas
– docs/ : MkDocs-based documentation, with assets, markdown pages, and publish guidelines
– .github/workflows/ : CI pipelines for schema validation and docs publishing
– requirements.txt : Python dependencies for validators and docs
– mkdocs.yml & mkdocs-base.yml : doc builder configs

##### README Insights
– Very brief: “JSON schema to connect to the quantum compute runtimes.”
– No built-in runtime or service; it’s purely schemas + tooling.

##### Main Components
A. Schema Module
- Contains operation-specific folders under schemas/
- Each folder has request.schema.json, reply_success.schema.json, reply_failure.schema.json (or message.schema.json for publish_state)

B. Test Suite
1. Schema-Check Runner
– Shell script + JSON example files under tests/schema-check/data
– Uses a JSON Schema validator CLI to ensure examples conform
2. Control-Software Validator
– Python code that imports schemas and simulates full request/response flows
– models/ for typed message classes, channels/ for I/O simulation, test_flows.py

C. Documentation Generator
- MkDocs reads docs/ and uses schemas (maybe embedded or linked) to build HTML docs
- GitHub Pages (via docs-publish pipeline)

D. CI/CD Pipelines
– validation.yaml: runs both test suites, linting, schema validity
– docs.yaml: builds and deploys docs

E. External Tools/Services
- JSON Schema Validator CLI (e.g., ajv)
- Python interpreter + pytest
- MkDocs for static site generation
- GitHub Actions for CI

##### Relationships and Data Flows
– Developer → pushes code + schemas → GitHub → CI pipelines
- Validation Pipeline → executes schema-check → runs control-software-validator → reports pass/fail
- Docs Pipeline → runs mkdocs build → publishes to GitHub Pages
– End user (another project) → installs compute-runtime-schema → imports JSON schemas → uses validator library to check payloads when interacting with a quantum runtime

##### Architectural Patterns and Principles
- Clear separation of concerns:
– Core schema definitions
– Validation/testing layers
– Documentation layer
– CI/CD orchestration
- Modular design: one folder per operation type, making extension of new operations straightforward.
- Infrastructure as code: pipelines defined in YAML, docs configuration in mkdocs.yml.

##### Essential Details to Capture
- The 6 operation types beneath schemas/
- Two distinct test strategies (shell-based vs. Python-based)
- CI workflow triggers and job sequences
- Docs pipeline and publishing target
- The role of external validators and MkDocs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Dev["Developer"]:::external
    GHRepo[(GitHub Repository)]:::artifact
    EndUser["End User Application"]:::external
    PublishedDocs[(Published Docs\nGitHub Pages)]:::artifact

    %% Schema Module
    subgraph "Schema Module" 
        direction TB
        Schemas["schemas/"]:::code
        Initialize["initialize/"]:::code
        Execute["execute/"]:::code
        GetDynamic["get_dynamic/"]:::code
        GetStatic["get_static/"]:::code
        PublishState["publish_state/"]:::code
        Terminate["terminate/"]:::code
    end

    %% Test Suite
    subgraph "Test Suite" 
        direction TB
        subgraph "Schema-Check Runner" 
            direction TB
            SchemaCheckRunner["tests.sh"]:::code
            SchemaCheckData["data/"]:::code
        end
        subgraph "Control-Software Validator" 
            direction TB
            CSV_Flows["test_flows.py"]:::code
            CSV_Channels["channels/"]:::code
            CSV_Models["models/"]:::code
            CSV_Generate["generate.sh"]:::code
        end
    end

    %% Documentation
    subgraph "Documentation Generator" 
        direction TB
        DocsSrc["docs/"]:::doc
        MkdocsConfig["mkdocs.yml & mkdocs-base.yml"]:::doc
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines" 
        direction TB
        ValidationCI["validation.yaml"]:::ci
        DocsCI["docs.yaml"]:::ci
    end

    %% External Tools
    subgraph "External Tools" 
        direction TB
        AJV["JSON Schema Validator CLI"]:::tool
        PyTest["Python & pytest"]:::tool
        MkDocsTool["MkDocs"]:::tool
        GHActions["GitHub Actions"]:::tool
    end

    %% Relationships
    Dev -->|"push code"| GHRepo
    GHRepo -->|triggers| ValidationCI
    GHRepo -->|triggers| DocsCI
    ValidationCI -->|runs| SchemaCheckRunner
    ValidationCI -->|runs| CSV_Flows
    SchemaCheckRunner -->|uses examples in| SchemaCheckData
    CSV_Flows -->|imports schemas| Schemas
    CSV_Generate -->|invokes| CSV_Flows
    DocsCI -->|builds site with| MkDocsTool
    DocsCI -->|reads| DocsSrc
    DocsCI -->|reads| MkdocsConfig
    DocsCI -->|publishes to| PublishedDocs
    Schemas -->|input to| SchemaCheckRunner
    Schemas -->|input to| CSV_Flows
    Schemas -->|linked in| DocsSrc
    EndUser -->|installs & imports| Schemas

    %% Click Events
    click Schemas "https://github.com/qutech-delft/compute-runtime-schema/tree/master/schemas/"
    click Initialize "https://github.com/qutech-delft/compute-runtime-schema/tree/master/schemas/initialize/"
    click Execute "https://github.com/qutech-delft/compute-runtime-schema/tree/master/schemas/execute/"
    click GetDynamic "https://github.com/qutech-delft/compute-runtime-schema/tree/master/schemas/get_dynamic/"
    click GetStatic "https://github.com/qutech-delft/compute-runtime-schema/tree/master/schemas/get_static/"
    click PublishState "https://github.com/qutech-delft/compute-runtime-schema/tree/master/schemas/publish_state/"
    click Terminate "https://github.com/qutech-delft/compute-runtime-schema/tree/master/schemas/terminate/"
    click SchemaCheckRunner "https://github.com/qutech-delft/compute-runtime-schema/blob/master/tests/schema-check/tests.sh"
    click SchemaCheckData "https://github.com/qutech-delft/compute-runtime-schema/tree/master/tests/schema-check/data/"
    click CSV_Flows "https://github.com/qutech-delft/compute-runtime-schema/blob/master/tests/control-software-validator/test_flows.py"
    click CSV_Channels "https://github.com/qutech-delft/compute-runtime-schema/tree/master/tests/control-software-validator/channels/"
    click CSV_Models "https://github.com/qutech-delft/compute-runtime-schema/tree/master/tests/control-software-validator/models/"
    click CSV_Generate "https://github.com/qutech-delft/compute-runtime-schema/blob/master/tests/control-software-validator/generate.sh"
    click DocsSrc "https://github.com/qutech-delft/compute-runtime-schema/tree/master/docs/"
    click MkdocsConfig "https://github.com/qutech-delft/compute-runtime-schema/blob/master/mkdocs.yml"
    click MkdocsConfig "https://github.com/qutech-delft/compute-runtime-schema/blob/master/mkdocs-base.yml"
    click ValidationCI "https://github.com/qutech-delft/compute-runtime-schema/blob/master/.github/workflows/validation.yaml"
    click DocsCI "https://github.com/qutech-delft/compute-runtime-schema/blob/master/.github/workflows/docs.yaml"

    %% Styles
    classDef code fill:#cfe2f3,stroke:#000,stroke-width:1px
    classDef doc fill:#f9cb9c,stroke:#000,stroke-width:1px
    classDef ci fill:#b6d7a8,stroke:#000,stroke-width:1px
    classDef tool fill:#d9d2e9,stroke:#000,stroke-width:1px
    classDef artifact fill:#fff2cc,stroke:#000,stroke-width:1px
    classDef external fill:#f4cccc,stroke:#000,stroke-width:1px
```
