# leqo-framework/bloqcat architecture

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

- Interactive diagram: https://gitdiagram.com/leqo-framework/bloqcat
- Repository: https://github.com/leqo-framework/bloqcat

## Overview

##### Project type and purpose
- BloQCat is a backend microservice (Flask-based REST API) whose purpose is to ingest a JSON description of a quantum topology, apply pattern aggregation logic, and emit a .qasm file.
- It provides JWT-secured endpoints for authentication and a single “bloqcat” endpoint for the quantum‐pattern aggregation.

##### File structure for architectural clues
- Top‐level modules:
- bloqcat/api – the REST controllers (v1_auth, v1_bloqcat)
- bloqcat/db – database access (SQLAlchemy models, Alembic migrations)
- bloqcat/util – configuration, logging, reverse‐proxy fixes, debug routes
- bloqcat/licenses, static, templates – UI assets for license pages and API docs
- Config/build: Dockerfile, CI/CD workflows under .github, poetry/pyproject.toml, migrations (alembic.ini, env.py).
- External docs: Sphinx in docs/, OpenAPI via Smorest + Swagger UI/RapiDoc.

##### README for additional insights
- Endpoints (/api/v1/auth and /api/v1/bloqcat).
- Uses JWT for access/refresh tokens.
- Generates .qasm files.
- Interactive docs at /api/swagger-ui and /api/rapidoc.

##### Main components & their relationships
A. Clients
- REST clients (CLI, web apps, curl, Swagger UI/RapiDoc)
B. API Gateway / Load Balancer (optional; e.g. nginx in front of Flask)
C. Flask Application
1. Routing Layer (bloqcat/api/v1_api)
- AuthController – login, refresh, whoami
- BloqcatController – deploy topology → returns .qasm
2. Business Logic Layer
- Validation (util/config/smorest_config.py)
- JWT issuance/validation (api/jwt.py)
- Pattern aggregation (bloqcat/babel.py, bloqcat/licenses.py)
3. Data Layer
- SQLAlchemy models (bloqcat/db/models)
- Alembic migrations (migrations/)
4. Utility Services
- Logging (util/logging.py)
- Reverse proxy fixes (util/reverse_proxy_fix.py)
- Debug‐routes UI (util/debug_routes)
D. Database
- PostgreSQL / MySQL (configured via sqlalchemy_config.py)
E. CI/CD Pipeline
- GitHub Actions (ci-cd.yml, docker-image.yml, lint_format.yml)
- Docker Registry → Production
F. Documentation Generator
- Sphinx + docs/ → ReadTheDocs

##### Architectural patterns & design principles
- Layered architecture: Controllers → Services → Data access
- RESTful API with versioning (v1)
- JWT for stateless authentication
- Externalized configuration (poetry, env vars via .flaskenv, shell.nix)
- Migrations with Alembic for schema evolution
- Automated CI/CD with GitHub Actions + Docker

##### Elements
- Clear component boundaries (e.g. “API Layer”, “Data Layer”)
- Green for runtime components (Flask App, DB)
- Blue for external actors (Clients, GitHub Actions)
- Yellow for auxiliary services (Auth, Logging, Migrations)
- Annotations for key technologies: Flask, SQLAlchemy, Alembic, Smorest (Swagger), Docker, GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    subgraph "Clients" 
        direction TB
        RESTClients(["REST Clients\n(CLI, Web, curl)"]):::external
        SwaggerUI(["Swagger UI/RapiDoc"]):::external
    end

    %% API Gateway
    APIGateway(["NGINX API Gateway"]):::external

    %% Flask Application
    subgraph "Flask App" 
        direction TB
        subgraph "Routing Layer"
            direction TB
            AuthController["AuthController\n(bloqcat/api/v1_api/auth.py)"]:::runtime
            BloqcatController["BloqcatController\n(bloqcat/api/v1_api/bloqcat.py)"]:::runtime
            RootSchema["Root/API Models\n(root.py, models/*.py)"]:::runtime
        end

        subgraph "Business Logic"
            direction TB
            JWTService["JWT Service\n(bloqcat/api/jwt.py)"]:::aux
            PatternAgg["Pattern Aggregation\n(bloqcat/babel.py)"]:::aux
            LicenseHandler["License Handling\n(bloqcat/licenses.py)"]:::aux
            ConfigValidation["OpenAPI Config\n(smorest_config.py)"]:::aux
        end

        subgraph "Data Layer"
            direction TB
            SQLModels["SQLAlchemy Models\n(models/example.py)"]:::runtime
            DBAccess["DB Access & CLI\n(db.py, cli.py)"]:::runtime
            Migrations["Alembic Migrations\n(migrations/)"]:::aux
        end

        subgraph "Utility Services"
            direction TB
            LoggingSvc["Logging Service\n(logging.py)"]:::aux
            ReverseProxy["Reverse Proxy Fix\n(reverse_proxy_fix.py)"]:::aux
            DebugRoutes["Debug Routes UI\n(debug_routes/)"]:::aux
        end

        %% In-App Connections
        AuthController -->|POST /api/v1/auth| JWTService
        BloqcatController -->|POST /api/v1/bloqcat| PatternAgg
        PatternAgg --> LicenseHandler
        PatternAgg --> SQLModels
        SQLModels --> DBAccess
        DBAccess --> Migrations
        AuthController --> ConfigValidation
        BloqcatController --> ConfigValidation
        LoggingSvc --> AuthController
        LoggingSvc --> BloqcatController
        ReverseProxy --> AuthController
        ReverseProxy --> BloqcatController
        DebugRoutes --> AuthController
        DebugRoutes --> BloqcatController
    end

    %% Database
    Database(("PostgreSQL/MySQL")):::runtime

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GH_Actions(["GitHub Actions\n(ci-cd.yml, docker-image.yml, lint_format.yml)"]):::external
        DockerRegistry(["Docker Registry"]):::external
        Production(["Production Deployment"]):::external
    end

    %% Documentation Generator
    DocsGen(["Sphinx Docs\n(docs/, readthedocs.yml)"]):::external

    %% Static & Templates
    subgraph "UI Assets"
        direction TB
        StaticCSS["licenses.css\n(static/licenses.css)"]:::aux
        Templates["HTML Templates\n(templates/*.html)"]:::aux
    end

    %% Flows
    RESTClients -->|Calls| APIGateway --> FlaskApp[("Flask App")] 
    SwaggerUI -->|Interactive Docs| FlaskApp
    FlaskApp -->|Reads/Writes| Database
    GH_Actions -->|Build & Push| DockerRegistry --> Production
    FlaskApp -->|Serves| StaticCSS
    FlaskApp -->|Serves| Templates
    DocsGen -->|Publishes| SwaggerUI

    %% Click Events
    click AuthController "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/api/v1_api/auth.py"
    click BloqcatController "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/api/v1_api/bloqcat.py"
    click RootSchema "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/api/v1_api/root.py"
    click JWTService "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/api/jwt.py"
    click PatternAgg "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/babel.py"
    click LicenseHandler "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/licenses.py"
    click ConfigValidation "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/util/config/smorest_config.py"
    click SQLModels "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/db/models/example.py"
    click DBAccess "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/db/db.py"
    click DBAccess "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/db/cli.py"
    click Migrations "https://github.com/leqo-framework/bloqcat/tree/main/migrations/"
    click LoggingSvc "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/util/logging.py"
    click ReverseProxy "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/util/reverse_proxy_fix.py"
    click DebugRoutes "https://github.com/leqo-framework/bloqcat/tree/main/bloqcat/util/debug_routes/"
    click StaticCSS "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/static/licenses.css"
    click Templates "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/templates/licenses.html"
    click Templates "https://github.com/leqo-framework/bloqcat/blob/main/bloqcat/templates/included_licenses.html"
    click GH_Actions "https://github.com/leqo-framework/bloqcat/blob/main/.github/workflows/ci-cd.yml"
    click GH_Actions "https://github.com/leqo-framework/bloqcat/blob/main/.github/workflows/docker-image.yml"
    click GH_Actions "https://github.com/leqo-framework/bloqcat/blob/main/.github/workflows/lint_format.yml"
    click DocsGen "https://github.com/leqo-framework/bloqcat/tree/main/docs/"
    click DocsGen "https://github.com/leqo-framework/bloqcat/blob/main/readthedocs.yml"

    %% Styles
    classDef runtime fill:#a8ddb5,stroke:#2b8cbe,stroke-width:1px
    classDef external fill:#9ecae1,stroke:#08519c,stroke-width:1px
    classDef aux fill:#fee391,stroke:#e6550d,stroke-width:1px
```
