# shlok926/quantum-flow-pqc-platform architecture

> Architecture diagram of the GitHub repository shlok926/quantum-flow-pqc-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shlok926/quantum-flow-pqc-platform
- Repository: https://github.com/shlok926/quantum-flow-pqc-platform

## Overview

Quantum Flow is a PQC discovery and risk-assessment platform: users register targets or submit source material, run staged assessments, review a cryptographic inventory and QVI risk, and export reports. The map preserves both enterprise-console and public-scanner capabilities, plus the API, worker, collectors, correlation, scoring, and persistence layers. Edges use the excerpts, SOURCE INDEX references, or README; unsampled endpoint internals are represented only where documented.

Main entry points: [`services/api/app/services/assessment_service.py`](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/services/assessment_service.py) (Assessment orchestration), [`apps/web/src/app/App.tsx`](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/app/App.tsx) (Enterprise console), [`apps/web/src/services/api.ts`](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/services/api.ts) (Web API client), [`services/api/app/services/job_service.py`](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/services/job_service.py) (Job coordination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["User interfaces"]
  node_console_app["Enterprise console<br/>[App.tsx]"]
  node_target_management["Target management"]
  node_source_upload["Source upload<br/>[SourceUpload.tsx]"]
  node_assessment_ui["Assessment review"]
  node_public_scanner["Public scanner<br/>[ScannerPage.tsx]"]
  node_scan_results["Public scan results"]
end

subgraph group_control["API and orchestration"]
  node_web_api["Web API client<br/>[api.ts]"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_router["API v1 routes<br/>[router.py]"]
  node_domain_endpoints["Domain endpoints"]
  node_assessment_service["Assessment orchestration"]
  node_job_service["Job coordination<br/>[job_service.py]"]
  node_worker["Background worker<br/>[worker.py]"]
end

subgraph group_discovery["Discovery and analysis"]
  node_scanner_suite["Discovery collectors"]
  node_process_containment["Process containment<br/>[containment.py]"]
  node_source_models["Source findings<br/>[models.py]"]
  node_cbom["CBOM correlation<br/>[correlator.py]"]
  node_risk_engine["QVI risk engine<br/>[engine.py]"]
  node_report_export["Report export<br/>[exporter.py]"]
end

subgraph group_records["Assessment records"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_assessment_records[("Assessment records<br/>[assessment.py]")]
  node_asset_records[("Cryptographic assets")]
  node_risk_records[("Risk records<br/>[risk_assessment.py]")]
  node_job_records[("Discovery jobs<br/>[discovery_job.py]")]
  node_other_db_models[("Evidence and target models")]
end

node_enterprise_user(("Enterprise user"))
node_public_visitor(("Public visitor"))

node_enterprise_user -->|"uses"| node_console_app
node_public_visitor -->|"submits scan"| node_public_scanner
node_console_app -->|"renders"| node_target_management
node_console_app -->|"renders"| node_source_upload
node_console_app -->|"renders"| node_assessment_ui
node_target_management -->|"calls"| node_web_api
node_assessment_ui -->|"calls"| node_web_api
node_public_scanner -->|"routes to"| node_scan_results
node_scan_results -->|"calls"| node_web_api
node_web_api -.->|"HTTP requests"| node_api_app
node_api_app -->|"mounts"| node_api_router
node_api_router -->|"registers"| node_domain_endpoints
node_domain_endpoints -.->|"orchestrates"| node_assessment_service
node_assessment_service -.->|"creates jobs"| node_job_service
node_worker -->|"claims jobs"| node_job_service
node_worker -->|"executes assessments"| node_assessment_service
node_assessment_service -->|"runs collectors"| node_scanner_suite
node_scanner_suite -.->|"uses boundaries"| node_process_containment
node_assessment_service -->|"correlates findings"| node_cbom
node_assessment_service -->|"evaluates risk"| node_risk_engine
node_assessment_service -.->|"exports reports"| node_report_export
node_cbom -->|"creates assets"| node_asset_records
node_risk_engine -->|"produces scores"| node_risk_records
node_assessment_service -.->|"persists lifecycle"| node_db_session
node_db_session -->|"database sessions"| node_assessment_records
node_job_service -->|"stores jobs"| node_job_records
node_assessment_records -->|"relates evidence"| node_other_db_models
node_asset_records -->|"relates observations"| node_other_db_models

click node_console_app "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/app/App.tsx"
click node_target_management "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/targets/TargetManagement.tsx"
click node_source_upload "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/discovery/SourceUpload.tsx"
click node_assessment_ui "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/assessments/AssessmentDetail.tsx"
click node_public_scanner "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/public/ScannerPage.tsx"
click node_scan_results "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/public/ScanResultsPage.tsx"
click node_web_api "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/services/api.ts"
click node_api_app "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/main.py"
click node_api_router "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/api/v1/router.py"
click node_domain_endpoints "https://github.com/shlok926/quantum-flow-pqc-platform/tree/main/services/api/app/api/v1/endpoints"
click node_assessment_service "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/services/assessment_service.py"
click node_job_service "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/services/job_service.py"
click node_worker "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/worker/app/worker.py"
click node_scanner_suite "https://github.com/shlok926/quantum-flow-pqc-platform/tree/main/packages/scanner"
click node_process_containment "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/scanner/safety/containment.py"
click node_source_models "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/scanner/source/models.py"
click node_cbom "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/cbom/correlator.py"
click node_risk_engine "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/risk/engine.py"
click node_report_export "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/reports/exporter.py"
click node_db_session "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/session.py"
click node_assessment_records "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/models/assessment.py"
click node_asset_records "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/models/cryptographic_asset.py"
click node_risk_records "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/models/risk_assessment.py"
click node_job_records "https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/models/discovery_job.py"
click node_other_db_models "https://github.com/shlok926/quantum-flow-pqc-platform/tree/main/services/api/app/db/models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_console_app,node_target_management,node_source_upload,node_assessment_ui,node_public_scanner,node_scan_results,node_enterprise_user toneBlue
class node_web_api,node_api_app,node_api_router,node_domain_endpoints,node_assessment_service,node_job_service,node_worker toneAmber
class node_scanner_suite,node_process_containment,node_source_models,node_cbom,node_risk_engine,node_report_export toneMint
class node_db_session,node_assessment_records,node_asset_records,node_risk_records,node_job_records,node_other_db_models toneRose
class node_public_visitor toneIndigo
```

## Components

### User interfaces

- [Enterprise console](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/app/App.tsx): `apps/web/src/app/App.tsx`
- [Target management](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/targets/TargetManagement.tsx): `apps/web/src/features/targets/TargetManagement.tsx`
- [Source upload](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/discovery/SourceUpload.tsx): `apps/web/src/features/discovery/SourceUpload.tsx`
- [Assessment review](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/assessments/AssessmentDetail.tsx): `apps/web/src/features/assessments/AssessmentDetail.tsx`
- [Public scanner](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/public/ScannerPage.tsx): `apps/web/src/features/public/ScannerPage.tsx`
- [Public scan results](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/features/public/ScanResultsPage.tsx): `apps/web/src/features/public/ScanResultsPage.tsx`

### API and orchestration

- [Web API client](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/apps/web/src/services/api.ts): `apps/web/src/services/api.ts`
- [FastAPI application](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/main.py): `services/api/app/main.py`
- [API v1 routes](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/api/v1/router.py): `services/api/app/api/v1/router.py`
- [Domain endpoints](https://github.com/shlok926/quantum-flow-pqc-platform/tree/main/services/api/app/api/v1/endpoints): `services/api/app/api/v1/endpoints`
- [Assessment orchestration](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/services/assessment_service.py): `services/api/app/services/assessment_service.py`
- [Job coordination](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/services/job_service.py): `services/api/app/services/job_service.py`
- [Background worker](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/worker/app/worker.py): `services/worker/app/worker.py`

### Discovery and analysis

- [Discovery collectors](https://github.com/shlok926/quantum-flow-pqc-platform/tree/main/packages/scanner): `packages/scanner`
- [Process containment](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/scanner/safety/containment.py): `packages/scanner/safety/containment.py`
- [Source findings](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/scanner/source/models.py): `packages/scanner/source/models.py`
- [CBOM correlation](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/cbom/correlator.py): `packages/cbom/correlator.py`
- [QVI risk engine](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/risk/engine.py): `packages/risk/engine.py`
- [Report export](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/packages/reports/exporter.py): `packages/reports/exporter.py`

### Assessment records

- [Database sessions](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/session.py): `services/api/app/db/session.py`
- [Assessment records](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/models/assessment.py): `services/api/app/db/models/assessment.py`
- [Cryptographic assets](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/models/cryptographic_asset.py): `services/api/app/db/models/cryptographic_asset.py`
- [Risk records](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/models/risk_assessment.py): `services/api/app/db/models/risk_assessment.py`
- [Discovery jobs](https://github.com/shlok926/quantum-flow-pqc-platform/blob/main/services/api/app/db/models/discovery_job.py): `services/api/app/db/models/discovery_job.py`
- [Evidence and target models](https://github.com/shlok926/quantum-flow-pqc-platform/tree/main/services/api/app/db/models): `services/api/app/db/models`

### Other components

- **Enterprise user**
- **Public visitor**

## Connections

- Enterprise user → Enterprise console: uses
- Public visitor → Public scanner: submits scan
- Enterprise console → Target management: renders (evidence: `apps/web/src/app/App.tsx`)
- Enterprise console → Source upload: renders (evidence: `apps/web/src/app/App.tsx`)
- Enterprise console → Assessment review: renders (evidence: `apps/web/src/app/App.tsx`)
- Target management → Web API client: calls (evidence: `apps/web/src/features/targets/TargetManagement.tsx`)
- Assessment review → Web API client: calls (evidence: `apps/web/src/features/assessments/AssessmentDetail.tsx`)
- Public scanner → Public scan results: routes to (evidence: `apps/web/src/app/App.tsx`)
- Public scan results → Web API client: calls (evidence: `apps/web/src/features/public/ScanResultsPage.tsx`)
- Web API client → FastAPI application: HTTP requests
- FastAPI application → API v1 routes: mounts (evidence: `services/api/app/main.py`)
- API v1 routes → Domain endpoints: registers (evidence: `services/api/app/api/v1/router.py`)
- Domain endpoints → Assessment orchestration: orchestrates
- Assessment orchestration → Job coordination: creates jobs (evidence: `services/api/app/services/assessment_service.py`)
- Background worker → Job coordination: claims jobs (evidence: `services/worker/app/worker.py`)
- Background worker → Assessment orchestration: executes assessments (evidence: `services/worker/app/worker.py`)
- Assessment orchestration → Discovery collectors: runs collectors (evidence: `services/api/app/services/assessment_service.py`)
- Discovery collectors → Process containment: uses boundaries
- Assessment orchestration → CBOM correlation: correlates findings (evidence: `services/api/app/services/assessment_service.py`)
- Assessment orchestration → QVI risk engine: evaluates risk (evidence: `services/api/app/services/assessment_service.py`)
- Assessment orchestration → Report export: exports reports
- CBOM correlation → Cryptographic assets: creates assets (evidence: `packages/cbom/correlator.py`)
- QVI risk engine → Risk records: produces scores (evidence: `packages/risk/engine.py`)
- Assessment orchestration → Database sessions: persists lifecycle
- Database sessions → Assessment records: database sessions (evidence: `services/api/app/db/session.py`)
- Job coordination → Discovery jobs: stores jobs (evidence: `services/api/app/services/job_service.py`)
- Assessment records → Evidence and target models: relates evidence (evidence: `services/api/app/db/models/assessment.py`)
- Cryptographic assets → Evidence and target models: relates observations (evidence: `services/api/app/db/models/cryptographic_asset.py`)
