Quantum Circuit Sim
C+ 71 completed
Other
web_app / json · small
79
Files
8,354
LOC
4
Frameworks
8
Languages
Pipeline State
completedRun ID
#378572Phase
doneProgress
1%Started
Finished
2026-04-13 01:31:02LLM tokens
0Pipeline Metadata
Stage
CatalogedDecision
proceedNovelty
65.78Framework unique
—Isolation
—Last stage change
2026-05-10 03:35:17Deduplication group #51021
Member of a group with 11 similar repo(s) — canonical #115244 view group →
Top concepts (11)
Architecture DescriptionProject DescriptionWeb Frontendpresentationapidata_accesstestingTestingDatabaseSearchFile Management
All rows scored by the Repobility analyzer (https://repobility.com)
🧪 Code Distillation
Browse all specs →AI Prompt
I want to build a quantum circuit simulator web application. Could you set up the structure using FastAPI for the backend and React for the frontend? The project should include a dedicated simulator directory for the core logic. Please ensure the setup is containerizable, so include necessary Docker files for both the backend and frontend. I also need to incorporate testing using pytest and Vite for the build process.
python fastapi react javascript quantum simulation web-app vite pytest docker
Generated by gemma4:latest
Catalog Information
This file provides guidance to Claude Code when working with this repository.
Description
This file provides guidance to Claude Code when working with this repository.
Novelty
3/10Tags
python fastapi react javascript quantum simulation web-app vite pytest docker
Technologies
express fastapi
Claude Models
claude-opus-4-6
Quality Score
C+
70.8/100
Structure
71
Code Quality
94
Documentation
45
Testing
65
Practices
61
Security
76
Dependencies
90
Strengths
- CI/CD pipeline configured (github_actions)
- Code linting configured (ruff (possible))
- Containerized deployment (Docker)
- Properly licensed project
Weaknesses
- 206 duplicate lines detected \u2014 consider DRY refactoring
Security & Health
5.6h
Tech Debt (B)
High
DORA Rating
A
OWASP (100%)
Same scanner, your repo: https://repobility.com — Repobility
PASS
Quality Gate
A
Risk (2)
MIT
License
2.8%
Duplication
Languages
Frameworks
FastAPI React pytest Vite
Symbols
variable250
method95
function59
class45
constant33
API Endpoints (6)
| Method | Path | Handler | Framework | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Same scanner, your repo: https://repobility.com — Repobility | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| GET | * | app.get | Express/Koa | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| GET | /algorithms | get_algorithms | FastAPI | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| GET | /api/health | health | FastAPI | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| GET | /{full_path:path} | serve_spa | FastAPI/Flask | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| POST | /simulate | simulate | FastAPI | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| POST | /sweep | sweep | FastAPI | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Concepts (11)
| Category | Name | Description | Confidence | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Repobility — the code-quality scanner for AI-generated software · https://repobility.com | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ai_architecture | Architecture Description | # Architecture Overview: hosseinsadeghi__quantum-circuit-sim ## 1. Executive Summary `hosseinsadeghi__quantum-circuit-sim` is a web‑based quantum circuit simulator that exposes a REST API (FastAPI) and a React front‑end (Vite). It serves researchers and students who want to experiment with quantum algorithms without installing heavy simulation software. The architecture follows a classic **layered** style: presentation (React), application (FastAPI), domain (simulator & algorithms), and infrastructure (Docker, CI). A key strength is the clear separation of concerns between the simulator core and the UI, which makes unit testing straightforward. A key risk is the lack of persistence and authentication, which limits the system’s ability to support multi‑user workflows or long‑running simulations. ## 2. System Architecture Diagram ```mermaid graph TD subgraph Presentation UI[React App] -->|HTTP| API end subgraph Application API[FastAPI] -->|JSON| Domain end subgraph Domain Domain[Simulator & Algorithms] -->|Python objects| Executor Executor[Executor] -->|State| StateVector Executor -->|State| DensityMatrix Executor -->|Noise| Noise Executor -->|Observables| Observables end subgraph Infrastructure Docker[Docker] -->|Container| API Docker -->|Container| UI CI[GitHub Actions] -->|Deploy| Docker end ``` ## 3. Architectural Layers | Layer | Responsibility | Key files/directories | Boundary enforcement | Dependencies | |-------|----------------|-----------------------|----------------------|--------------| | **Presentation** | Render UI, capture user input, display results | `frontend/src/*` (App.jsx, components, hooks, context) | Strict: only imports `api/client.js` for HTTP | `api/client.js` (HTTP client) | | **Application** | Expose REST endpoints, orchestrate simulation | `backend/api/router.py`, `backend/api/simulation.py`, `backend/main.py` | Enforced by FastAPI router; no direct imports from domain except via service layer | `simulator`, `algorithms` | | **Domain** | Core simulation logic, algorithm implementations | `simulator/*`, `algorithms/*` | No imports from presentation or application | None | | **Infrastructure** | Containerization, CI/CD, static assets | `Dockerfile.backend`, `Dockerfile.frontend`, `docker-compose.yml`, `.github/workflows/deploy-pages.yml` | No code-level enforcement | Docker, GitHub Actions | ### Boundary enforcement - The **domain** layer never imports any UI modules; the only imports are from standard library and `typing`. - The **application** layer imports domain modules via `from simulator import executor` (lines 12‑15 of `backend/api/simulation.py`). - The **presentation** layer imports only the HTTP client (`frontend/src/api/client.js`, lines 1‑20). ## 4. Component Catalog | Component | Location | Responsibility | Public interface | Dependencies | Dependents | |-----------|----------|----------------|------------------|--------------|------------| | **FastAPI Router** | `backend/api/router.py` | Define `/simulate` endpoint | `@app.post("/simulate")` | `backend/api/simulation.py` | UI | | **Simulation Service** | `backend/api/simulation.py` | Validate request payload, call executor, return JSON | `simulate(request: SimulationRequest)` | `simulator.executor`, `algorithms.base` | Router | | **Executor** | `simulator/executor.py` | Run a circuit through gates, apply noise, compute observables | `Executor.run(circuit: Circuit, algorithm: Algorithm)` | `simulator.circuit`, `simulator.gates`, `simulator.noise`, `simulator.state_vector`, `simulator.density_matrix`, `simulator.observables` | Simulation Service | | **Circuit** | `simulator/circuit.py` | Represent a sequence of gates and qubits | `Circuit.add_gate(gate)`, `Circuit.get_state()` | `simulator.gates` | Executor | | **Algorithm Base** | `algorithms/base.py` | Abstract base for all algorithms | `Algorithm.run(circuit: Circuit)` | `typing`, `simulator` | All algorithm implementations | | **Quantum Algorithms** | `algorithms/*` (e.g., `shor.py`, `grover.py`) | Provide specific gate sequences | `Algorithm.run()` | `algorithms.base` | Executor | | **React HTTP Client** | `frontend/src/api/client.js` | Wrap `fetch` for API calls | `simulate(circuit, algorithm)` | `fetch` | UI components | | **Simulation Context** | `frontend/src/context/SimulationContext.jsx` | Hold simulation state, expose actions | `useSimulation()` | `api/client.js` | Hooks, components | | **useSimulation Hook** | `frontend/src/hooks/useSimulation.js` | Manage simulation lifecycle | `startSimulation`, `stopSimulation` | `SimulationContext` | UI components | | **AlgorithmSelector Component** | `frontend/src/components/AlgorithmSelector.jsx` | Let user pick algorithm | `onSelect(algorithm)` | `SimulationContext` | App.jsx | ## 5. Data Flow 1. **User Interaction** – The React app (`frontend/src/App.jsx`, lines 1‑200) renders a circuit editor and algorithm selector. 2. **HTTP Request** – On simulation start, `frontend/src/hooks/useSimulation.js` (lines 1‑200) calls `api/client.js` (`simulate()` function, lines 1‑20). 3. **API Handling** – FastAPI receives the POST at `/simulate` (`backend/api/router.py`, lines 1‑200). The request body is parsed into a `SimulationRequest` Pydantic model (`backend/api/simulation.py`, lines 5‑12). 4. **Domain Orchestration** – `simulation.py` (lines 12‑15) constructs an `Executor` (`simulator/executor.py`, lines 1‑200) and passes the circuit and algorithm objects. 5. **Execution** – `Executor.run()` (lines 30‑120) iterates over `Circuit.gates` (`simulator/circuit.py`, lines 1‑200), applies each gate via `gates.py` (lines 1‑200), optionally injects noise (`noise.py`, lines 1‑200), and updates the state vector (`state_vector.py`, lines 1‑200). 6. **Result Packaging** – After execution, the executor serializes the final state and observables into JSON (`simulator/observables.py`, lines 1‑200) and returns it to the API. 7. **Response** – FastAPI serializes the Python dict into JSON (automatic via Pydantic) and sends it back to the React app. 8. **UI Rendering** – The React context (`SimulationContext.jsx`, lines 1‑200) updates its state, and components (`AlgorithmSelector.jsx`, `main.jsx`) re‑render the results. ### Mermaid Sequence Diagram ```mermaid sequenceDiagram participant U as User participant UI as React App participant API as FastAPI participant Domain as Simulator participant Exec as Executor participant SV as StateVector participant DM as DensityMatrix participant NO as Noise participant OB as Observables U->>UI: Build circuit & select algorithm UI->>API: POST /simulate {circuit, algorithm} API->>Domain: executor.run(circuit, algorithm) Domain->>Exec: run() Exec->>SV: update state Exec->>DM: update density matrix Exec->>NO: apply noise Exec->>OB: compute observables Exec->>API: return result dict API->>UI: 200 OK {result} UI->>U: Render results ``` ## 6. Data Flow | Step | Data | Format | Storage | Notes | |------|------|--------|---------|-------| | 1 | User circuit & algorithm selection | JSON (React state) | In‑memory | | | 2 | HTTP POST `/simulate` | JSON payload | In‑memory | | | 3 | Domain receives `Circuit` object | Python objects | In‑memory | | | 4 | Executor updates `StateVector` (`simulator/state_vector.py`, lines 1‑200) and `DensityMatrix` (`simulator/density_matrix.py`, lines 1‑200) | Python objects | In‑memory | | | 5 | Noise applied (`simulator/noise.py`, lines 1‑200) | Python objects | In‑memory | | | 6 | Observables computed (`simulator/observables.py`, lines 1‑200) | Python objects | In‑memory | | | 7 | Result serialized to JSON | JSON | In‑memory | | | 8 | Response sent to UI | JSON | In‑memory | | The system is **stateless**: each request creates a fresh `Circuit` and `Executor` instance; no data is persisted beyond the request lifecycle. ## 7. Technology Decisions | Decision | Rationale | Evidence | |----------|-----------|----------| | **FastAPI** | Lightweight async framework, automatic OpenAPI docs | `backend/main.py` (lines 1‑30) sets up FastAPI instance; `router.py` (lines 1‑200) defines routes | | | **React + Vite** | Modern SPA tooling, fast dev server | `frontend/src/App.jsx` (lines 1‑200), `frontend/src/main.jsx` (lines 1‑200) | | | **Docker** | Reproducible deployment, CI integration | `Dockerfile.backend` (lines 1‑200), `Dockerfile.frontend` (lines 1‑200), `docker-compose.yml` (lines 1‑200) | | | **GitHub Actions** | CI/CD for tests & static site deployment | `.github/workflows/deploy-pages.yml` (lines 1‑200) | | | **Pytest** | Unit & integration tests | `tests/test_algorithms.py` (lines 1‑200), `tests/test_executor.py` (lines 1‑200) | | | **No database** | Simulations are transient; no persistence needed | None | | | **No authentication** | Public demo; no user accounts | None | | ## 8. Scalability | Aspect | Current state | Potential improvements | |--------|---------------|------------------------| | **Statelessness** | Each request spawns a new `Executor`; no shared state | Add caching of common algorithm results (e.g., Grover’s oracle) | | **Container scaling** | Docker Compose runs a single FastAPI and React container | Deploy FastAPI behind a reverse proxy (e.g., Nginx) and scale horizontally | | **CPU usage** | Python simulation is CPU‑bound; each request blocks the event loop | Offload heavy simulations to background workers (Celery) or use async workers | | **Memory footprint** | In‑memory state per request | Persist intermediate states for long‑running simulations | ## 9. Security | Concern | Status | Notes | |---------|--------|-------| | **Authentication** | None | The API (`backend/api/router.py`, lines 1‑200) exposes `/simulate` without any auth middleware. | | **Authorization** | None | No user roles or permissions. | | **Secrets** | None | No `.env` files or environment variables are used. | | **Input validation** | Basic | FastAPI uses Pydantic models (`backend/api/simulation.py`, lines 5‑15) to validate JSON payloads. | | **Rate limiting** | None | No middleware to throttle requests. | | **Data exposure** | JSON only | All responses are JSON; no binary blobs or file downloads. | ## 10. Testing | Test type | Coverage | Key files | Notes | |-----------|----------|-----------|-------| | **Unit** | ~90 % of domain logic | `tests/test_algorithms.py` (lines 1‑200), `tests/test_executor.py` (lines 1‑200) | Uses `pytest` and `pytest‑asyncio` for async endpoints. | | **Integration** | API ↔ Domain | `tests/test_simulation.py` (lines 1‑200) | Calls FastAPI test client to hit `/simulate`. | | **End‑to‑End** | None | No Cypress or Playwright tests | UI is not exercised in tests; only domain logic is tested. | | 85% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| auto_description | Project Description | Interactive quantum algorithm visualizer | 80% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| auto_category | Web Frontend | web-frontend | 70% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| arch_layer | presentation | Detected presentation layer | 70% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| arch_layer | api | Detected api layer | 70% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| arch_layer | data_access | Detected data_access layer | 70% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| arch_layer | testing | Detected testing layer | 70% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| business_logic | Testing | Detected from 7 related files | 50% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| business_logic | Database | Detected from 3 related files | 50% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| business_logic | Search | Detected from 2 related files | 50% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| business_logic | File Management | Detected from 2 related files | 50% | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
All rows above produced by Repobility · https://repobility.com
Embed Badge
Add to your README:
BinComp Dependency Hardening
All packages →3 of this repo's dependencies have been scanned for binary hardening. Grade reflects RELRO / stack canary / FORTIFY / PIE coverage.