# muditbhargava66/opennandlab architecture

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

- Interactive diagram: https://gitdiagram.com/muditbhargava66/opennandlab
- Repository: https://github.com/muditbhargava66/opennandlab

## Overview

OpenNANDLab is a NAND/SSD research simulator and characterization toolkit. The principal workflow is a researcher invoking the CLI or Python API, configuring and initializing a controller, then running page operations against an FTL and NAND device; characterization and metrics provide an analysis branch. The graph preserves documented defect handling, ECC, optimization, firmware, and visualization capabilities. Some subsystem interactions are documented only at a high level; unverified wiring is omitted rather than inferred from imports.

Main entry points: [`src/opennandlab/simulator.py`](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/simulator.py) (NAND controller), [`src/opennandlab/cli.py`](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/cli.py) (CLI), [`src/opennandlab/ftl/gc.py`](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ftl/gc.py) (Garbage collection), [`src/opennandlab/analytics/data_collection.py`](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/analytics/data_collection.py) (Characterization collection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces and setup"]
  node_cli["CLI<br/>[cli.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_controller["NAND controller<br/>[simulator.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

subgraph group_storage["Translation and NAND"]
  node_ftl["Page FTL<br/>[page_ftl.py]"]
  node_gc["Garbage collection<br/>[gc.py]"]
  node_nand_sim["Simulated NAND"]
  node_nand_device["NAND device interface<br/>[device.py]"]
end

subgraph group_reliability["Reliability features"]
  node_bad_blocks["Bad block management<br/>[bad_block.py]"]
  node_wear["Wear leveling<br/>[wear_leveling.py]"]
  node_ecc_handler["ECC handler<br/>[handler.py]"]
  node_bch["BCH codec<br/>[bch.py]"]
  node_ldpc["LDPC codec<br/>[ldpc.py]"]
  node_bch_forney["Forney algorithm<br/>[bch_forney.py]"]
end

subgraph group_optimization["Performance features"]
  node_cache["Caching<br/>[caching.py]"]
  node_compression["Compression<br/>[compression.py]"]
  node_parallel["Parallel access<br/>[parallel_access.py]"]
end

subgraph group_insight["Firmware and analysis"]
  node_firmware["Firmware specifications<br/>[specs.py]"]
  node_firmware_validation["Firmware validation<br/>[validation.py]"]
  node_collector["Characterization collection<br/>[data_collection.py]"]
  node_metrics["Metrics analysis<br/>[metrics.py]"]
  node_dashboard["Dashboard<br/>[dashboard.py]"]
  node_heatmap["Wear heatmap<br/>[wear_heatmap.py]"]
  node_workloads["Workloads"]
end

node_researcher(("Researcher"))

node_researcher -->|"invokes"| node_cli
node_researcher -->|"uses API"| node_controller
node_cli -->|"runs simulation"| node_controller
node_cli -->|"loads config"| node_config
node_cli -->|"characterizes"| node_collector
node_cli -->|"launches"| node_dashboard
node_controller -->|"initializes interface"| node_nand_sim
node_controller -->|"translates pages"| node_ftl
node_controller -->|"runs collection"| node_gc
node_controller -->|"caches data"| node_cache
node_controller -->|"compresses data"| node_compression
node_controller -->|"dispatches operations"| node_parallel
node_nand_sim -->|"implements"| node_nand_device
node_gc -->|"allocates pages"| node_ftl
node_gc -->|"moves and erases"| node_nand_sim
node_ecc_handler -->|"selects codec"| node_bch
node_ecc_handler -->|"selects codec"| node_ldpc
node_collector -->|"samples device"| node_nand_device
node_controller -->|"manages defects"| node_bad_blocks
node_controller -->|"tracks wear"| node_wear
node_firmware -->|"validated by"| node_firmware_validation
node_collector -.->|"analyzed by"| node_metrics
node_dashboard -->|"visualizes wear"| node_heatmap

click node_cli "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/cli.py"
click node_config "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/config.py"
click node_controller "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/simulator.py"
click node_ftl "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ftl/page_ftl.py"
click node_gc "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ftl/gc.py"
click node_nand_sim "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/nand/simulator_device.py"
click node_nand_device "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/nand/device.py"
click node_bad_blocks "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/defect/bad_block.py"
click node_wear "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/defect/wear_leveling.py"
click node_ecc_handler "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ecc/handler.py"
click node_bch "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ecc/bch.py"
click node_ldpc "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ecc/ldpc.py"
click node_bch_forney "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ecc/bch_forney.py"
click node_cache "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/optimization/caching.py"
click node_compression "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/optimization/compression.py"
click node_parallel "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/optimization/parallel_access.py"
click node_firmware "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/firmware/specs.py"
click node_firmware_validation "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/firmware/validation.py"
click node_collector "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/analytics/data_collection.py"
click node_metrics "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/analytics/metrics.py"
click node_dashboard "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/visualization/dashboard.py"
click node_heatmap "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/visualization/wear_heatmap.py"
click node_workloads "https://github.com/muditbhargava66/opennandlab/tree/main/src/opennandlab/workloads"
click node_logger "https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/utils/logger.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_cli,node_config,node_controller,node_logger toneBlue
class node_ftl,node_gc,node_nand_sim,node_nand_device toneAmber
class node_bad_blocks,node_wear,node_ecc_handler,node_bch,node_ldpc,node_bch_forney toneMint
class node_cache,node_compression,node_parallel toneRose
class node_firmware,node_firmware_validation,node_collector,node_metrics,node_dashboard,node_heatmap,node_workloads,node_researcher toneIndigo
```

## Components

### Interfaces and setup

- [CLI](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/cli.py): `src/opennandlab/cli.py`
- [Configuration](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/config.py): `src/opennandlab/config.py`
- [NAND controller](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/simulator.py): `src/opennandlab/simulator.py`
- [Logging](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/utils/logger.py): `src/opennandlab/utils/logger.py`

### Translation and NAND

- [Page FTL](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ftl/page_ftl.py): `src/opennandlab/ftl/page_ftl.py`
- [Garbage collection](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ftl/gc.py): `src/opennandlab/ftl/gc.py`
- [Simulated NAND](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/nand/simulator_device.py): `src/opennandlab/nand/simulator_device.py`
- [NAND device interface](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/nand/device.py): `src/opennandlab/nand/device.py`

### Reliability features

- [Bad block management](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/defect/bad_block.py): `src/opennandlab/defect/bad_block.py`
- [Wear leveling](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/defect/wear_leveling.py): `src/opennandlab/defect/wear_leveling.py`
- [ECC handler](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ecc/handler.py): `src/opennandlab/ecc/handler.py`
- [BCH codec](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ecc/bch.py): `src/opennandlab/ecc/bch.py`
- [LDPC codec](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ecc/ldpc.py): `src/opennandlab/ecc/ldpc.py`
- [Forney algorithm](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/ecc/bch_forney.py): `src/opennandlab/ecc/bch_forney.py`

### Performance features

- [Caching](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/optimization/caching.py): `src/opennandlab/optimization/caching.py`
- [Compression](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/optimization/compression.py): `src/opennandlab/optimization/compression.py`
- [Parallel access](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/optimization/parallel_access.py): `src/opennandlab/optimization/parallel_access.py`

### Firmware and analysis

- [Firmware specifications](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/firmware/specs.py): `src/opennandlab/firmware/specs.py`
- [Firmware validation](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/firmware/validation.py): `src/opennandlab/firmware/validation.py`
- [Characterization collection](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/analytics/data_collection.py): `src/opennandlab/analytics/data_collection.py`
- [Metrics analysis](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/analytics/metrics.py): `src/opennandlab/analytics/metrics.py`
- [Dashboard](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/visualization/dashboard.py): `src/opennandlab/visualization/dashboard.py`
- [Wear heatmap](https://github.com/muditbhargava66/opennandlab/blob/main/src/opennandlab/visualization/wear_heatmap.py): `src/opennandlab/visualization/wear_heatmap.py`
- [Workloads](https://github.com/muditbhargava66/opennandlab/tree/main/src/opennandlab/workloads): `src/opennandlab/workloads`

### Other components

- **Researcher**

## Connections

- Researcher → CLI: invokes (evidence: `README.md`)
- Researcher → NAND controller: uses API (evidence: `README.md`)
- CLI → NAND controller: runs simulation (evidence: `README.md`)
- CLI → Configuration: loads config (evidence: `README.md`)
- CLI → Characterization collection: characterizes (evidence: `README.md`)
- CLI → Dashboard: launches (evidence: `README.md`)
- NAND controller → Simulated NAND: initializes interface (evidence: `src/opennandlab/simulator.py`)
- NAND controller → Page FTL: translates pages (evidence: `src/opennandlab/simulator.py`)
- NAND controller → Garbage collection: runs collection (evidence: `src/opennandlab/simulator.py`)
- NAND controller → Caching: caches data (evidence: `src/opennandlab/simulator.py`)
- NAND controller → Compression: compresses data (evidence: `README.md`)
- NAND controller → Parallel access: dispatches operations (evidence: `src/opennandlab/simulator.py`)
- Simulated NAND → NAND device interface: implements (evidence: `src/opennandlab/nand/simulator_device.py`)
- Garbage collection → Page FTL: allocates pages (evidence: `src/opennandlab/ftl/gc.py`)
- Garbage collection → Simulated NAND: moves and erases (evidence: `src/opennandlab/ftl/gc.py`)
- ECC handler → BCH codec: selects codec (evidence: `src/opennandlab/ecc/handler.py`)
- ECC handler → LDPC codec: selects codec (evidence: `src/opennandlab/ecc/handler.py`)
- Characterization collection → NAND device interface: samples device (evidence: `src/opennandlab/analytics/data_collection.py`)
- NAND controller → Bad block management: manages defects (evidence: `src/opennandlab/simulator.py`)
- NAND controller → Wear leveling: tracks wear (evidence: `src/opennandlab/simulator.py`)
- Firmware specifications → Firmware validation: validated by (evidence: `README.md`)
- Characterization collection → Metrics analysis: analyzed by
- Dashboard → Wear heatmap: visualizes wear (evidence: `README.md`)
