# bithabib/flash_ssd_simulator_web architecture

> Architecture diagram of the GitHub repository bithabib/flash_ssd_simulator_web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bithabib/flash_ssd_simulator_web
- Repository: https://github.com/bithabib/flash_ssd_simulator_web

## Overview

EyanaSSD is a web-based educational and research SSD simulator. A user uploads or selects a workload, the server parses and replays it through a conventional, FDP, or ZNS model, and the application streams or presents SSD behavior and metrics for exploration. The repository also includes synthetic and real-trace workload support, a comprehensive evaluation harness, and educational content. The graph reflects documented and indexed source references; unsampled subsystem details and unshown UI-to-backend wiring are left unasserted.

Main entry points: [`eyana_engine/full_eval.py`](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/full_eval.py) (Cross-engine evaluation), [`eyana_engine/simulator.py`](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/simulator.py) (Conventional simulator), [`eyana_engine/zns/zns_device.py`](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns/zns_device.py) (ZNS device), [`app.py`](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/app.py) (Flask application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Flask application<br/>[app.py]"]
  node_trace_stream["Trace upload and streaming<br/>[simulate_stream.py]"]
  node_trace_reader["Trace visualization reader"]
  node_web_pages["Simulator and site views"]
  node_visualizers["Interactive visualizers"]
end

subgraph group_engine["Simulation engine"]
  node_config["SSD configuration<br/>[config.py]"]
  node_simulator["Conventional simulator<br/>[simulator.py]"]
  node_device["Flash device state<br/>[device.py]"]
  node_allocation["Page allocation<br/>[allocation.py]"]
  node_gc["Garbage collection policies"]
  node_fdp["FDP placement engine<br/>[fdp_engine.py]"]
  node_stream_sim["Conventional stream runner<br/>[stream_sim.py]"]
  node_fdp_stream["FDP stream runner<br/>[fdp_stream.py]"]
end

subgraph group_zns["ZNS simulation"]
  node_zns_stream["ZNS stream runner<br/>[zns_stream.py]"]
  node_zns_sim["ZNS simulator<br/>[zns_simulator.py]"]
  node_zns_device["ZNS device<br/>[zns_device.py]"]
  node_host_ftl["Host FTL and reclaim<br/>[host_ftl.py]"]
  node_zone["Zone state<br/>[zone.py]"]
end

subgraph group_research["Workload evaluation"]
  node_workloads["Workload generators<br/>[workloads.py]"]
  node_metrics["Simulation metrics<br/>[metrics.py]"]
  node_full_eval["Cross-engine evaluation<br/>[full_eval.py]"]
end

subgraph group_education["Learning content"]
  node_blog["SSD and ZNS lessons<br/>[blog_content.py]"]
end

node_user(("Learner / researcher"))

node_user -->|"uses"| node_app
node_app -->|"registers routes"| node_trace_stream
node_app -->|"registers routes"| node_trace_reader
node_app -->|"registers views"| node_web_pages
node_trace_stream -->|"runs conventional"| node_stream_sim
node_trace_stream -->|"runs FDP"| node_fdp_stream
node_trace_stream -->|"runs ZNS"| node_zns_stream
node_stream_sim -->|"replays through"| node_simulator
node_stream_sim -->|"parses traces"| node_workloads
node_stream_sim -->|"configures"| node_config
node_fdp_stream -->|"replays through"| node_fdp
node_fdp_stream -->|"uses"| node_workloads
node_fdp_stream -->|"configures"| node_config
node_zns_stream -->|"uses"| node_zns_device
node_zns_stream -->|"uses"| node_host_ftl
node_zns_stream -->|"uses"| node_workloads
node_simulator -->|"uses"| node_config
node_simulator -->|"updates"| node_device
node_simulator -->|"allocates through"| node_allocation
node_simulator -->|"selects policy"| node_gc
node_fdp -->|"uses"| node_config
node_zns_sim -->|"uses"| node_zns_device
node_zns_sim -->|"uses"| node_host_ftl
node_zns_device -->|"validates geometry"| node_config
node_zns_device -->|"tracks state"| node_zone
node_host_ftl -->|"appends and resets"| node_zns_device
node_host_ftl -->|"uses state"| node_zone
node_full_eval -->|"evaluates"| node_simulator
node_full_eval -->|"evaluates"| node_fdp
node_full_eval -->|"evaluates"| node_zns_device
node_full_eval -->|"evaluates"| node_host_ftl
node_full_eval -->|"generates inputs"| node_workloads
node_full_eval -->|"uses metrics"| node_metrics
node_app -->|"registers blog"| node_blog
node_user -->|"explores metrics"| node_visualizers

click node_app "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/app.py"
click node_trace_stream "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/views/simulate_stream.py"
click node_trace_reader "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/views/api/trace_file_reader.py"
click node_web_pages "https://github.com/bithabib/flash_ssd_simulator_web/tree/main/views"
click node_visualizers "https://github.com/bithabib/flash_ssd_simulator_web/tree/main/static/src/js"
click node_config "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/config.py"
click node_workloads "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/workloads.py"
click node_simulator "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/simulator.py"
click node_device "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/device.py"
click node_allocation "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/allocation.py"
click node_gc "https://github.com/bithabib/flash_ssd_simulator_web/tree/main/eyana_engine/gc"
click node_fdp "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/fdp/fdp_engine.py"
click node_metrics "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/metrics.py"
click node_stream_sim "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/stream_sim.py"
click node_fdp_stream "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/fdp_stream.py"
click node_zns_stream "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns_stream.py"
click node_zns_sim "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns/zns_simulator.py"
click node_zns_device "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns/zns_device.py"
click node_host_ftl "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns/host_ftl.py"
click node_zone "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns/zone.py"
click node_full_eval "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/full_eval.py"
click node_blog "https://github.com/bithabib/flash_ssd_simulator_web/blob/main/views/blog_content.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_app,node_trace_stream,node_trace_reader,node_web_pages,node_visualizers toneBlue
class node_config,node_simulator,node_device,node_allocation,node_gc,node_fdp,node_stream_sim,node_fdp_stream toneAmber
class node_zns_stream,node_zns_sim,node_zns_device,node_host_ftl,node_zone toneMint
class node_workloads,node_metrics,node_full_eval toneRose
class node_blog,node_user toneIndigo
```

## Components

### Web experience

- [Flask application](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/app.py): `app.py`
- [Trace upload and streaming](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/views/simulate_stream.py): `views/simulate_stream.py`
- [Trace visualization reader](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/views/api/trace_file_reader.py): `views/api/trace_file_reader.py`
- [Simulator and site views](https://github.com/bithabib/flash_ssd_simulator_web/tree/main/views): `views`
- [Interactive visualizers](https://github.com/bithabib/flash_ssd_simulator_web/tree/main/static/src/js): `static/src/js`

### Simulation engine

- [SSD configuration](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/config.py): `eyana_engine/config.py`
- [Conventional simulator](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/simulator.py): `eyana_engine/simulator.py`
- [Flash device state](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/device.py): `eyana_engine/device.py`
- [Page allocation](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/allocation.py): `eyana_engine/allocation.py`
- [Garbage collection policies](https://github.com/bithabib/flash_ssd_simulator_web/tree/main/eyana_engine/gc): `eyana_engine/gc`
- [FDP placement engine](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/fdp/fdp_engine.py): `eyana_engine/fdp/fdp_engine.py`
- [Conventional stream runner](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/stream_sim.py): `eyana_engine/stream_sim.py`
- [FDP stream runner](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/fdp_stream.py): `eyana_engine/fdp_stream.py`

### ZNS simulation

- [ZNS stream runner](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns_stream.py): `eyana_engine/zns_stream.py`
- [ZNS simulator](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns/zns_simulator.py): `eyana_engine/zns/zns_simulator.py`
- [ZNS device](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns/zns_device.py): `eyana_engine/zns/zns_device.py`
- [Host FTL and reclaim](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns/host_ftl.py): `eyana_engine/zns/host_ftl.py`
- [Zone state](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/zns/zone.py): `eyana_engine/zns/zone.py`

### Workload evaluation

- [Workload generators](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/workloads.py): `eyana_engine/workloads.py`
- [Simulation metrics](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/metrics.py): `eyana_engine/metrics.py`
- [Cross-engine evaluation](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/eyana_engine/full_eval.py): `eyana_engine/full_eval.py`

### Learning content

- [SSD and ZNS lessons](https://github.com/bithabib/flash_ssd_simulator_web/blob/main/views/blog_content.py): `views/blog_content.py`

### Other components

- **Learner / researcher**

## Connections

- Learner / researcher → Flask application: uses (evidence: `README.md`)
- Flask application → Trace upload and streaming: registers routes (evidence: `app.py`)
- Flask application → Trace visualization reader: registers routes (evidence: `app.py`)
- Flask application → Simulator and site views: registers views (evidence: `app.py`)
- Trace upload and streaming → Conventional stream runner: runs conventional (evidence: `views/simulate_stream.py`)
- Trace upload and streaming → FDP stream runner: runs FDP (evidence: `views/simulate_stream.py`)
- Trace upload and streaming → ZNS stream runner: runs ZNS (evidence: `views/simulate_stream.py`)
- Conventional stream runner → Conventional simulator: replays through (evidence: `eyana_engine/stream_sim.py`)
- Conventional stream runner → Workload generators: parses traces (evidence: `eyana_engine/stream_sim.py`)
- Conventional stream runner → SSD configuration: configures (evidence: `eyana_engine/stream_sim.py`)
- FDP stream runner → FDP placement engine: replays through (evidence: `eyana_engine/fdp_stream.py`)
- FDP stream runner → Workload generators: uses (evidence: `eyana_engine/fdp_stream.py`)
- FDP stream runner → SSD configuration: configures (evidence: `eyana_engine/fdp_stream.py`)
- ZNS stream runner → ZNS device: uses (evidence: `eyana_engine/zns_stream.py`)
- ZNS stream runner → Host FTL and reclaim: uses (evidence: `eyana_engine/zns_stream.py`)
- ZNS stream runner → Workload generators: uses (evidence: `eyana_engine/zns_stream.py`)
- Conventional simulator → SSD configuration: uses (evidence: `eyana_engine/simulator.py`)
- Conventional simulator → Flash device state: updates (evidence: `eyana_engine/simulator.py`)
- Conventional simulator → Page allocation: allocates through (evidence: `eyana_engine/simulator.py`)
- Conventional simulator → Garbage collection policies: selects policy (evidence: `eyana_engine/simulator.py`)
- FDP placement engine → SSD configuration: uses (evidence: `eyana_engine/fdp/fdp_engine.py`)
- ZNS simulator → ZNS device: uses (evidence: `eyana_engine/zns/zns_simulator.py`)
- ZNS simulator → Host FTL and reclaim: uses (evidence: `eyana_engine/zns/zns_simulator.py`)
- ZNS device → SSD configuration: validates geometry (evidence: `eyana_engine/zns/zns_device.py`)
- ZNS device → Zone state: tracks state (evidence: `eyana_engine/zns/zns_device.py`)
- Host FTL and reclaim → ZNS device: appends and resets (evidence: `eyana_engine/zns/host_ftl.py`)
- Host FTL and reclaim → Zone state: uses state (evidence: `eyana_engine/zns/host_ftl.py`)
- Cross-engine evaluation → Conventional simulator: evaluates (evidence: `eyana_engine/full_eval.py`)
- Cross-engine evaluation → FDP placement engine: evaluates (evidence: `eyana_engine/full_eval.py`)
- Cross-engine evaluation → ZNS device: evaluates (evidence: `eyana_engine/full_eval.py`)
- Cross-engine evaluation → Host FTL and reclaim: evaluates (evidence: `eyana_engine/full_eval.py`)
- Cross-engine evaluation → Workload generators: generates inputs (evidence: `eyana_engine/full_eval.py`)
- Cross-engine evaluation → Simulation metrics: uses metrics (evidence: `eyana_engine/full_eval.py`)
- Flask application → SSD and ZNS lessons: registers blog (evidence: `app.py`)
- Learner / researcher → Interactive visualizers: explores metrics (evidence: `README.md`)
