# sadmansami870213/chameleon architecture

> Architecture diagram of the GitHub repository sadmansami870213/chameleon, 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/sadmansami870213/chameleon
- Repository: https://github.com/sadmansami870213/chameleon

## Overview

Chameleon is a BB84 quantum-key-distribution simulator and research web app for comparing fixed-threshold and adaptive eavesdropping detectors. The principal workflow is user settings through the web/API, validated simulation settings, a BB84 link with configurable noise and Eve, sampled test bits/QBER, detector verdicts, and displayed results. Separate branches provide live Monte Carlo comparison, saved runs, and precomputed research summaries; the experiment package supports broader evaluation and reporting. Edges follow shown imports/calls or README statements; unsampled frontend/API wiring and some experiment internals are left unverified rather than inferred.

Main entry points: [`backend/main.py`](https://github.com/sadmansami870213/chameleon/blob/main/backend/main.py) (HTTP API), [`backend/services/simulation.py`](https://github.com/sadmansami870213/chameleon/blob/main/backend/services/simulation.py) (Simulation service), [`backend/experiments/runner.py`](https://github.com/sadmansami870213/chameleon/blob/main/backend/experiments/runner.py) (Monte Carlo runner), [`backend/qkd/link.py`](https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/link.py) (Quantum link)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_dashboard["Dashboard<br/>[app.js]"]
  node_charts["Charts<br/>[charts.js]"]
end

subgraph group_api["Application services"]
  node_api_app["HTTP API<br/>[main.py]"]
  node_settings["Settings validation<br/>[settings.py]"]
  node_simulation_service["Simulation service<br/>[simulation.py]"]
  node_compare["Live comparison<br/>[compare.py]"]
  node_saved_runs["Saved runs<br/>[experiments.py]"]
  node_storage[("Run storage<br/>[storage.py]")]
  node_research_data["Research summaries<br/>[research.py]"]
end

subgraph group_qkd["QKD simulation"]
  node_bb84["BB84 protocol<br/>[bb84.py]"]
  node_eve["Eavesdropper<br/>[eavesdropper.py]"]
  node_channel["Noise channel<br/>[channel.py]"]
  node_link["Quantum link<br/>[link.py]"]
  node_result["Test bits and QBER<br/>[result.py]"]
  node_contract["QKD result contract<br/>[types.py]"]
end

subgraph group_research["Detection and research"]
  node_detectors["Fixed detector<br/>[traditional.py]"]
  node_adaptive["Adaptive detector<br/>[adaptive.py]"]
  node_experiment_runner["Monte Carlo runner<br/>[runner.py]"]
  node_experiment_config["Experiment configuration<br/>[config.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_report["Experiment reports<br/>[report.py]"]
end

node_user(("Research user"))

node_user -->|"uses"| node_dashboard
node_dashboard -.->|"calls API"| node_api_app
node_api_app -->|"validates settings"| node_settings
node_api_app -->|"routes simulation"| node_simulation_service
node_api_app -->|"routes comparison"| node_compare
node_api_app -->|"routes saved runs"| node_saved_runs
node_api_app -->|"routes summaries"| node_research_data
node_simulation_service -->|"simulates link"| node_link
node_simulation_service -->|"builds result"| node_result
node_simulation_service -->|"evaluates run"| node_detectors
node_simulation_service -->|"calibrates and evaluates"| node_adaptive
node_link -->|"runs protocol"| node_bb84
node_link -->|"applies attack"| node_eve
node_link -->|"applies noise"| node_channel
node_result -->|"samples exchange"| node_link
node_result -->|"creates result"| node_contract
node_detectors -->|"consumes result"| node_contract
node_adaptive -->|"consumes result"| node_contract
node_compare -->|"runs trials"| node_experiment_runner
node_compare -->|"summarizes outcomes"| node_metrics
node_compare -->|"validates settings"| node_settings
node_saved_runs -->|"reads and writes"| node_storage
node_research_data -.->|"supplies summaries"| node_dashboard
node_experiment_runner -->|"uses configuration"| node_experiment_config
node_experiment_runner -->|"uses detector"| node_adaptive
node_experiment_runner -->|"selects detectors"| node_detectors
node_experiment_runner -.->|"produces evaluation data"| node_metrics
node_report -->|"uses metrics"| node_metrics

click node_dashboard "https://github.com/sadmansami870213/chameleon/blob/main/frontend/js/app.js"
click node_charts "https://github.com/sadmansami870213/chameleon/blob/main/frontend/js/charts.js"
click node_api_app "https://github.com/sadmansami870213/chameleon/blob/main/backend/main.py"
click node_settings "https://github.com/sadmansami870213/chameleon/blob/main/backend/services/settings.py"
click node_simulation_service "https://github.com/sadmansami870213/chameleon/blob/main/backend/services/simulation.py"
click node_compare "https://github.com/sadmansami870213/chameleon/blob/main/backend/services/compare.py"
click node_saved_runs "https://github.com/sadmansami870213/chameleon/blob/main/backend/services/experiments.py"
click node_storage "https://github.com/sadmansami870213/chameleon/blob/main/backend/services/storage.py"
click node_research_data "https://github.com/sadmansami870213/chameleon/blob/main/backend/services/research.py"
click node_bb84 "https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/bb84.py"
click node_eve "https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/eavesdropper.py"
click node_channel "https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/channel.py"
click node_link "https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/link.py"
click node_result "https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/result.py"
click node_contract "https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/types.py"
click node_detectors "https://github.com/sadmansami870213/chameleon/blob/main/backend/detection/traditional.py"
click node_adaptive "https://github.com/sadmansami870213/chameleon/blob/main/backend/detection/adaptive.py"
click node_experiment_runner "https://github.com/sadmansami870213/chameleon/blob/main/backend/experiments/runner.py"
click node_experiment_config "https://github.com/sadmansami870213/chameleon/blob/main/backend/experiments/config.py"
click node_metrics "https://github.com/sadmansami870213/chameleon/blob/main/backend/experiments/metrics.py"
click node_report "https://github.com/sadmansami870213/chameleon/blob/main/backend/experiments/report.py"

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_dashboard,node_charts,node_user toneBlue
class node_api_app,node_settings,node_simulation_service,node_compare,node_saved_runs,node_storage,node_research_data toneAmber
class node_bb84,node_eve,node_channel,node_link,node_result,node_contract toneMint
class node_detectors,node_adaptive,node_experiment_runner,node_experiment_config,node_metrics,node_report toneRose
```

## Components

### Web interface

- [Dashboard](https://github.com/sadmansami870213/chameleon/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [Charts](https://github.com/sadmansami870213/chameleon/blob/main/frontend/js/charts.js): `frontend/js/charts.js`

### Application services

- [HTTP API](https://github.com/sadmansami870213/chameleon/blob/main/backend/main.py): `backend/main.py`
- [Settings validation](https://github.com/sadmansami870213/chameleon/blob/main/backend/services/settings.py): `backend/services/settings.py`
- [Simulation service](https://github.com/sadmansami870213/chameleon/blob/main/backend/services/simulation.py): `backend/services/simulation.py`
- [Live comparison](https://github.com/sadmansami870213/chameleon/blob/main/backend/services/compare.py): `backend/services/compare.py`
- [Saved runs](https://github.com/sadmansami870213/chameleon/blob/main/backend/services/experiments.py): `backend/services/experiments.py`
- [Run storage](https://github.com/sadmansami870213/chameleon/blob/main/backend/services/storage.py): `backend/services/storage.py`
- [Research summaries](https://github.com/sadmansami870213/chameleon/blob/main/backend/services/research.py): `backend/services/research.py`

### QKD simulation

- [BB84 protocol](https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/bb84.py): `backend/qkd/bb84.py`
- [Eavesdropper](https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/eavesdropper.py): `backend/qkd/eavesdropper.py`
- [Noise channel](https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/channel.py): `backend/qkd/channel.py`
- [Quantum link](https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/link.py): `backend/qkd/link.py`
- [Test bits and QBER](https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/result.py): `backend/qkd/result.py`
- [QKD result contract](https://github.com/sadmansami870213/chameleon/blob/main/backend/qkd/types.py): `backend/qkd/types.py`

### Detection and research

- [Fixed detector](https://github.com/sadmansami870213/chameleon/blob/main/backend/detection/traditional.py): `backend/detection/traditional.py`
- [Adaptive detector](https://github.com/sadmansami870213/chameleon/blob/main/backend/detection/adaptive.py): `backend/detection/adaptive.py`
- [Monte Carlo runner](https://github.com/sadmansami870213/chameleon/blob/main/backend/experiments/runner.py): `backend/experiments/runner.py`
- [Experiment configuration](https://github.com/sadmansami870213/chameleon/blob/main/backend/experiments/config.py): `backend/experiments/config.py`
- [Evaluation metrics](https://github.com/sadmansami870213/chameleon/blob/main/backend/experiments/metrics.py): `backend/experiments/metrics.py`
- [Experiment reports](https://github.com/sadmansami870213/chameleon/blob/main/backend/experiments/report.py): `backend/experiments/report.py`

### Other components

- **Research user**

## Connections

- Research user → Dashboard: uses (evidence: `README.md`)
- Dashboard → HTTP API: calls API
- HTTP API → Settings validation: validates settings (evidence: `backend/main.py`)
- HTTP API → Simulation service: routes simulation (evidence: `backend/main.py`)
- HTTP API → Live comparison: routes comparison (evidence: `backend/main.py`)
- HTTP API → Saved runs: routes saved runs (evidence: `backend/main.py`)
- HTTP API → Research summaries: routes summaries (evidence: `backend/main.py`)
- Simulation service → Quantum link: simulates link (evidence: `backend/services/simulation.py`)
- Simulation service → Test bits and QBER: builds result (evidence: `backend/services/simulation.py`)
- Simulation service → Fixed detector: evaluates run (evidence: `backend/services/simulation.py`)
- Simulation service → Adaptive detector: calibrates and evaluates (evidence: `backend/services/simulation.py`)
- Quantum link → BB84 protocol: runs protocol (evidence: `backend/qkd/link.py`)
- Quantum link → Eavesdropper: applies attack (evidence: `backend/qkd/link.py`)
- Quantum link → Noise channel: applies noise (evidence: `backend/qkd/link.py`)
- Test bits and QBER → Quantum link: samples exchange (evidence: `backend/qkd/result.py`)
- Test bits and QBER → QKD result contract: creates result (evidence: `backend/qkd/result.py`)
- Fixed detector → QKD result contract: consumes result (evidence: `backend/detection/traditional.py`)
- Adaptive detector → QKD result contract: consumes result (evidence: `backend/detection/adaptive.py`)
- Live comparison → Monte Carlo runner: runs trials (evidence: `backend/services/compare.py`)
- Live comparison → Evaluation metrics: summarizes outcomes (evidence: `backend/services/compare.py`)
- Live comparison → Settings validation: validates settings (evidence: `backend/services/compare.py`)
- Saved runs → Run storage: reads and writes (evidence: `backend/services/experiments.py`)
- Research summaries → Dashboard: supplies summaries
- Monte Carlo runner → Experiment configuration: uses configuration (evidence: `backend/experiments/runner.py`)
- Monte Carlo runner → Adaptive detector: uses detector (evidence: `backend/experiments/runner.py`)
- Monte Carlo runner → Fixed detector: selects detectors (evidence: `backend/experiments/runner.py`)
- Monte Carlo runner → Evaluation metrics: produces evaluation data
- Experiment reports → Evaluation metrics: uses metrics (evidence: `backend/experiments/report.py`)
