# omenndt/frombittoqubit architecture

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

- Interactive diagram: https://gitdiagram.com/omenndt/frombittoqubit
- Repository: https://github.com/omenndt/frombittoqubit

## Overview

##### Project Type and Purpose
- This is a hybrid full-stack application combining:
- A Unity-based visualization front end (C#)
- A Python backend that simulates quantum circuits
- Docker & Nginx for containerized deployment
- Jupyter notebooks for teaching/demo purposes
- Purpose: provide an educational journey from classical bits to qubits by running circuit simulations in Python and visualizing them in a Unity UI.

##### Main Components
A. Unity Frontend
– Unity/Assets/Scripts/QuantumSimulationManager.cs
– QuantumUI.cs, QuantumVisualizer.cs, QubitVisualizer.cs
*Role*: fetch simulation results and render them in 3D.
B. Python Backend Service
– quantum_backend.py (local)
– quantum_backend_simple.py (no-deps quick demo)
– quantum_backend_docker.py (production entry point)
– requirements.txt (dependencies)
*Role*: expose a REST or RPC API to compute quantum circuit state vectors or probabilities.
C. Orchestration & Reverse Proxy
– docker-compose.yml / docker-compose.simple.yml
– nginx.conf
– Dockerfile / Dockerfile.simple
– deploy.sh, DOCKER_SETUP.md, DOCKER_SUMMARY.md
*Role*: containerize backend, serve API over HTTP, optionally reverse-proxy via Nginx.
D. Demo & Testing
– circuits/01_circuit_basics.ipynb (educational notebook)
– test_backend.py, test_simple_backend.py, test_docker.py
*Role*: verify correctness of simulation and Docker setup.

##### Relationships & Data Flow
1. Unity Frontend → HTTP calls → Nginx (or direct)
2. Nginx → forwards /api/simulate requests → quantum_backend_docker container
3. Python Backend → computes quantum circuit → returns JSON payload
4. Unity ← parses JSON → updates visual representation
5. (Separately) Jupyter notebook reads quantum_backend.py for interactive exploration
6. CI/testing suite invokes backends and Docker environment to validate endpoints

##### Architectural Patterns & Principles
- Separation of Concerns: visualization (Unity) vs. computation (Python)
- Containerization: reproducible environment via Docker
- API-first design: backend exposes well-defined HTTP endpoints
- Extensibility: two backend modes (simple vs. full Docker) for quick demos or production

##### Diagramming Conventions
- Rounded-rectangle for applications (Unity, Jupyter Notebook)
- Parallelogram or cloud for external resources (Docker Hub, Git, NPM)
- Blue = Frontend components
- Green = Backend services
- Orange = Deployment/orchestration
- Gray = Demo/test artifacts
- Containers with ports exposed (e.g., 8000)

##### Final Checklist
- Every component is clearly labeled
- Notes on deployment scripts/compose files are included

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Tier: Unity Frontend
    subgraph "Unity Client"
        direction TB
        QSM["QuantumSimulationManager.cs"]:::frontend
        QUI["QuantumUI.cs"]:::frontend
        QVS["QuantumVisualizer.cs"]:::frontend
        QBV["QubitVisualizer.cs"]:::frontend
    end

    %% Middle Tier: Orchestration & Reverse Proxy
    subgraph "Orchestration & Reverse Proxy"
        direction TB
        DC["docker-compose.yml"]:::orchestration
        DCS["docker-compose.simple.yml"]:::orchestration
        DF["Dockerfile"]:::orchestration
        DFS["Dockerfile.simple"]:::orchestration
        NG["nginx.conf"]:::orchestration
        DEPLOY["deploy.sh"]:::orchestration
        DSUM["DOCKER_SUMMARY.md"]:::orchestration
        DSET["DOCKER_SETUP.md"]:::orchestration
    end

    %% Bottom Tier: Quantum Backend Container
    subgraph "Quantum Backend Container"
        direction TB
        QBD["quantum_backend_docker.py"]:::backend
        REQ["requirements.txt"]:::backend
    end

    %% Side: Alternate Backend Flows
    subgraph "Alternate Backend Flows"
        direction TB
        QBS["quantum_backend_simple.py"]:::backend
        QBL["quantum_backend.py"]:::backend
    end

    %% Sidebar: Demo & Testing
    subgraph "Demo & Testing"
        direction TB
        NB["01_circuit_basics.ipynb"]:::demo
        TB1["test_backend.py"]:::demo
        TB2["test_simple_backend.py"]:::demo
        TB3["test_docker.py"]:::demo
    end

    %% Connections
    QSM -->|HTTP POST /simulate| DC
    QSM -->|HTTP POST /simulate| DCS
    DC -->|links to| NG
    DCS -->|links to| NG
    NG -->|"forward to port 8000"| QBD
    QBD -->|"JSON response"| NG
    NG -->|"JSON response"| QSM

    NB -->|imports| QBL

    TB1 -->|tests API| QBD
    TB2 -->|tests simple| QBS
    TB3 -->|tests docker| DC

    %% Click Events
    click QSM "https://github.com/omenndt/frombittoqubit/blob/main/Unity/Assets/Scripts/QuantumSimulationManager.cs"
    click QUI "https://github.com/omenndt/frombittoqubit/blob/main/Unity/Assets/Scripts/QuantumUI.cs"
    click QVS "https://github.com/omenndt/frombittoqubit/blob/main/Unity/Assets/Scripts/QuantumVisualizer.cs"
    click QBV "https://github.com/omenndt/frombittoqubit/blob/main/Unity/Assets/Scripts/QubitVisualizer.cs"

    click QBL "https://github.com/omenndt/frombittoqubit/blob/main/quantum_backend.py"
    click QBS "https://github.com/omenndt/frombittoqubit/blob/main/quantum_backend_simple.py"
    click QBD "https://github.com/omenndt/frombittoqubit/blob/main/quantum_backend_docker.py"
    click REQ "https://github.com/omenndt/frombittoqubit/blob/main/requirements.txt"

    click DC "https://github.com/omenndt/frombittoqubit/blob/main/docker-compose.yml"
    click DCS "https://github.com/omenndt/frombittoqubit/blob/main/docker-compose.simple.yml"
    click DF "https://github.com/omenndt/frombittoqubit/tree/main/Dockerfile"
    click DFS "https://github.com/omenndt/frombittoqubit/blob/main/Dockerfile.simple"
    click NG "https://github.com/omenndt/frombittoqubit/blob/main/nginx.conf"
    click DEPLOY "https://github.com/omenndt/frombittoqubit/blob/main/deploy.sh"
    click DSET "https://github.com/omenndt/frombittoqubit/blob/main/DOCKER_SETUP.md"
    click DSUM "https://github.com/omenndt/frombittoqubit/blob/main/DOCKER_SUMMARY.md"

    click NB "https://github.com/omenndt/frombittoqubit/blob/main/circuits/01_circuit_basics.ipynb"
    click TB1 "https://github.com/omenndt/frombittoqubit/blob/main/test_backend.py"
    click TB2 "https://github.com/omenndt/frombittoqubit/blob/main/test_simple_backend.py"
    click TB3 "https://github.com/omenndt/frombittoqubit/blob/main/test_docker.py"

    %% Styles
    classDef frontend fill:#aecbfa,stroke:#0366d6,color:#0366d6
    classDef backend fill:#a5d6a7,stroke:#2e7d32,color:#2e7d32
    classDef orchestration fill:#ffcc80,stroke:#ef6c00,color:#e65100
    classDef demo fill:#e0e0e0,stroke:#424242,color:#424242
```
