# infleqtion/client-superstaq architecture

> Architecture diagram of the GitHub repository infleqtion/client-superstaq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/infleqtion/client-superstaq
- Repository: https://github.com/infleqtion/client-superstaq

## Overview

##### Main Components

a) Client Layer:
- Three main client packages:
- qiskit-superstaq
- cirq-superstaq
- general-superstaq

b) Core Services:
- Compiler and Optimization Layer
- Resource Estimation Service
- Serialization Layer
- Validation Layer
- Job Management System

c) Integration Layer:
- Quantum Hardware Providers (IBM, AQT, EEROQ, QSCOUT)
- Simulator Backend
- Benchmarking System (SupermarQ)

##### Component Relationships

**[Client Applications] → [Client Libraries Layer]**
- ↓
**[Authentication & Validation Layer]**
- ↓
**[Core Services Layer] ←→ [Serialization Layer]**
- ↓
**[Hardware Integration Layer] → [Quantum Backends]**

##### Design Elements

Use the following visual elements:
- Blue rectangles: Client libraries
- Green rectangles: Core services
- Yellow rectangles: Integration components
- Purple rectangles: Hardware/backend systems

##### Specific Implementation Details

a) Client Libraries Layer:
- How each client package (Qiskit, Cirq, General) implements:
- Custom gates
- Compiler output handling
- Backend communication
- Job management

b) Core Services:
- Resource estimation component
- Validation and serialization flows
- SupermarQ benchmarking system

c) Integration Layer:
- Connections to different quantum hardware providers
- Simulator integration
- Optimization paths for each backend

##### Infrastructure Layer (Hardware/Simulators)

Left to right organization:
- Core components in the center
- Supporting services on the sides
- Testing and CI/CD components on the far right

##### Important Notes

- Use clear labels for each component
- Version information for major components
- Error handling paths
- Security boundaries

Remember to highlight the modular nature of the system, showing how new quantum backends can be added through the integration layer, and how the different client libraries share core functionality while maintaining their framework-specific interfaces.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Style definitions
    classDef client fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef integration fill:#f1c40f,stroke:#f39c12,color:black
    classDef backend fill:#9b59b6,stroke:#8e44ad,color:white
    classDef testing fill:#e74c3c,stroke:#c0392b,color:white

    %% Client Layer
    subgraph ClientLayer
        QiskitClient["Qiskit Client"]:::client
        CirqClient["Cirq Client"]:::client
        GeneralClient["General Client"]:::client
        
        QGates["Qiskit Custom Gates"]:::client
        CGates["Cirq Custom Gates"]:::client
        
        QCompiler["Qiskit Compiler Output"]:::client
        CCompiler["Cirq Compiler Output"]:::client
    end

    %% Core Services Layer
    subgraph CoreServices
        ResourceEst["Resource Estimation"]:::core
        Serialization["Serialization Layer"]:::core
        Validation["Validation Layer"]:::core
        JobMgmt["Job Management"]:::core
    end

    %% Integration Layer
    subgraph Integration
        SupermarQ["SupermarQ Benchmarking"]:::integration
        
        subgraph HardwareIntegration
            IBM["IBM Integration"]:::integration
            AQT["AQT Integration"]:::integration
            EEROQ["EEROQ Integration"]:::integration
            QSCOUT["QSCOUT Integration"]:::integration
        end
    end

    %% Testing Layer
    subgraph Testing
        CICD["CI/CD Pipeline"]:::testing
        IntegrationTests["Integration Tests"]:::testing
    end

    %% Backend Layer
    subgraph Backends
        IBMBackend["IBM Quantum"]:::backend
        AQTBackend["AQT Hardware"]:::backend
        EEROQBackend["EEROQ Hardware"]:::backend
        QSCOUTBackend["QSCOUT Hardware"]:::backend
        Simulator["Simulator Backend"]:::backend
    end

    %% Relationships
    QiskitClient --> QGates
    QiskitClient --> QCompiler
    CirqClient --> CGates
    CirqClient --> CCompiler

    QiskitClient & CirqClient & GeneralClient --> Validation
    Validation --> ResourceEst
    Validation --> Serialization
    Serialization --> JobMgmt

    JobMgmt --> SupermarQ
    JobMgmt --> HardwareIntegration

    IBM --> IBMBackend
    AQT --> AQTBackend
    EEROQ --> EEROQBackend
    QSCOUT --> QSCOUTBackend

    IntegrationTests --> QiskitClient
    IntegrationTests --> CirqClient
    CICD --> IntegrationTests

    %% Click Events
    click QiskitClient "https://github.com/Infleqtion/client-superstaq/tree/main/qiskit-superstaq/qiskit_superstaq/"
    click CirqClient "https://github.com/Infleqtion/client-superstaq/tree/main/cirq-superstaq/cirq_superstaq/"
    click GeneralClient "https://github.com/Infleqtion/client-superstaq/tree/main/general-superstaq/general_superstaq/"
    click ResourceEst "https://github.com/Infleqtion/client-superstaq/blob/main/general-superstaq/general_superstaq/resource_estimate.py"
    click Serialization "https://github.com/Infleqtion/client-superstaq/blob/main/general-superstaq/general_superstaq/serialization.py"
    click Validation "https://github.com/Infleqtion/client-superstaq/blob/main/general-superstaq/general_superstaq/validation.py"
    click SupermarQ "https://github.com/Infleqtion/client-superstaq/tree/main/supermarq-benchmarks/supermarq/"
    click IBM "https://github.com/Infleqtion/client-superstaq/tree/main/docs/source/optimizations/ibm/"
    click AQT "https://github.com/Infleqtion/client-superstaq/tree/main/docs/source/optimizations/aqt/"
    click EEROQ "https://github.com/Infleqtion/client-superstaq/tree/main/docs/source/optimizations/eeroq/"
    click QSCOUT "https://github.com/Infleqtion/client-superstaq/tree/main/docs/source/optimizations/qscout/"
    click QGates "https://github.com/Infleqtion/client-superstaq/blob/main/qiskit-superstaq/qiskit_superstaq/custom_gates.py"
    click CGates "https://github.com/Infleqtion/client-superstaq/blob/main/cirq-superstaq/cirq_superstaq/ops/qubit_gates.py"
    click QCompiler "https://github.com/Infleqtion/client-superstaq/blob/main/qiskit-superstaq/qiskit_superstaq/compiler_output.py"
    click CCompiler "https://github.com/Infleqtion/client-superstaq/blob/main/cirq-superstaq/cirq_superstaq/compiler_output.py"
    click CICD "https://github.com/Infleqtion/client-superstaq/tree/main/.github/workflows/"
    click IntegrationTests "https://github.com/Infleqtion/client-superstaq/blob/main/cirq-superstaq/cirq_superstaq/daily_integration_test.py"
```
