How leqo-framework/bloqcat works
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.