# armink/flashdb architecture

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

- Interactive diagram: https://gitdiagram.com/armink/flashdb
- Repository: https://github.com/armink/flashdb

## Overview

1. **Repository purpose**
   - This is **FlashDB**, an embedded storage library for microcontrollers and other constrained systems.
   - The repo is organized around a small **core database engine** plus a separate **flash abstraction layer** and multiple **platform demos**.

2. **Core database subsystem**
   - The main library lives under `src/` and `inc/`.
   - `src/fdb_kvdb.c` implements the **key-value database**.
   - `src/fdb_tsdb.c` implements the **time-series database**.
   - `src/fdb.c`, `src/fdb_file.c`, and `src/fdb_utils.c` provide shared database logic, record/file handling, and utility functions.
   - `inc/flashdb.h` is the public entry point for consumers of the library.

3. **Database modes and responsibilities**
   - **KVDB** is for persistent settings, parameters, and small blobs/strings.
   - **TSDB** is for append-heavy timestamped records and log-like data.
   - These two modes share common storage primitives but expose different access patterns and metadata handling.

4. **Flash abstraction boundary**
   - `port/fal/` contains the **Flash Abstraction Layer (FAL)**.
   - FAL isolates FlashDB from device-specific flash drivers and partition layouts.
   - Its source files (`fal.c`, `fal_flash.c`, `fal_partition.c`) manage flash devices, partition tables, and low-level read/write/erase operations.
   - This boundary is central to the architecture: **FlashDB does not talk directly to hardware flash; it talks to FAL**.

5. **Platform-specific porting layer**
   - Each demo includes a small platform port that connects FAL to actual flash hardware.
   - Examples:
     - `demos/esp32_spi_flash/components/FlashDB/porting/fal_flash_esp32_port.c`
     - `demos/esp8266_spi_flash/components/FlashDB/porting/fal_flash_esp8266_port.c`
     - `demos/stm32f103ve/applications/fal_cfg.h`
     - `demos/stm32f405rg_spi_flash/drivers/drv_spi_flash.c`
   - These files are the main hardware boundary and vary by board, flash type, and build system.

6. **Demo applications as integration layers**
   - The `demos/` directory shows how to embed FlashDB in real projects.
   - There are demos for:
     - **Linux** host simulation
     - **ESP8266 / ESP32** with SPI flash
     - **STM32F103VE** and **STM32F405RG**
     - **STM32F405RG SPI flash**
   - Each demo wires together platform startup, console output, flash configuration, and database examples.

7. **Hardware support structure in MCU demos**
   - STM32 demos include board bring-up code under `drivers/`, CMSIS startup/system files, HAL drivers, and linker scripts.
   - The ARM-based demos are therefore full firmware projects, not just sample C files.
   - This means FlashDB sits above a substantial board-support layer when used on bare metal.

8. **Configuration model**
   - Configuration is split between `fdb_cfg.h` and `fal_cfg.h` variants in demos and templates.
   - `inc/fdb_cfg_template.h` is the library-side configuration template.
   - `port/fal/samples/porting/fal_cfg.h` and demo-specific equivalents define flash devices, partitions, and database sizing.
   - Architecture-wise, configuration is a cross-cutting layer that determines storage layout, wear behavior, and feature enablement.

9. **Samples and usage patterns**
   - `samples/` contains focused examples for:
     - basic KVDB usage
     - string values
     - blob values
     - TSDB usage
   - These are small application-level references that sit above the core API and show expected data flow: application code calls FlashDB APIs, which call into FAL-backed storage.

10. **Testing and verification**
   - `tests/` contains unit/functional test cases for KVDB and TSDB.
   - The top-level GitHub workflow under `.github/workflows/main.yml` provides CI automation.
   - So the repo has both embedded demo validation and host/test validation.

11. **Zephyr integration**
   - `zephyr/module.yml` indicates FlashDB can be consumed as a **Zephyr module**.
   - This is another integration boundary, separate from the standalone demos and MCU board projects.

12. **Documentation as architecture map**
   - `docs/` holds the project documentation, API references, porting guides, and per-demo notes.
   - The docs reinforce the repo structure: core API, configuration, porting, and platform examples are treated as distinct layers.

13. **Typical data flow**
   - Application code issues KVDB or TSDB operations.
   - FlashDB core validates, indexes, and manages records.
   - FlashDB delegates physical storage access to FAL.
   - FAL routes requests to the platform-specific flash port.
   - The port performs erase/read/write on real flash hardware or a host simulation backend.

14. **Key architectural takeaway**
   - The repository is built around a clean separation between:
     - **portable database logic**
     - **flash/partition abstraction**
     - **board- or OS-specific integration**
   - If you draw an architecture diagram, the central path should be application → FlashDB core → FAL → hardware flash, with demos/tests/docs orbiting around that core.

Main entry points: [`port/fal/src/fal.c`](https://github.com/armink/flashdb/blob/master/port/fal/src/fal.c) (FAL Core), [`inc/flashdb.h`](https://github.com/armink/flashdb/blob/master/inc/flashdb.h) (Public API), [`src/fdb.c`](https://github.com/armink/flashdb/blob/master/src/fdb.c) (DB Core), [`tests/fdb_kvdb_tc.c`](https://github.com/armink/flashdb/blob/master/tests/fdb_kvdb_tc.c) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core DB"]
  node_node_flashdb_api["Public API<br/>header<br/>[flashdb.h]"]
  node_node_db_common["DB Core<br/>engine<br/>[fdb.c]"]
  node_node_kvdb["KVDB<br/>key-value db<br/>[fdb_kvdb.c]"]
  node_node_tsdb["TSDB<br/>time-series db<br/>[fdb_tsdb.c]"]
  node_node_db_helpers["Utils<br/>support code<br/>[fdb_file.c]"]
  node_node_fdb_cfg["FDB Config<br/>config template<br/>[fdb_cfg_template.h]"]
end

subgraph group_group_fal["FAL"]
  node_node_fal_api["FAL API<br/>flash abstraction<br/>[fal.h]"]
  node_node_fal_core["FAL Core<br/>partition engine<br/>[fal.c]"]
  node_node_fal_flash["Flash IO<br/>device I/O<br/>[fal_flash.c]"]
  node_node_fal_partition["Partitions<br/>layout manager<br/>[fal_partition.c]"]
  node_node_fal_cfg["FAL Config<br/>config layout<br/>[fal_cfg.h]"]
end

subgraph group_group_demos["Demos"]
  node_node_linux_demo["Linux Demo<br/>host demo<br/>[main.c]"]
  node_node_esp_demo["ESP Demo<br/>embedded demo<br/>[main.c]"]
  node_node_stm32_demo["STM32 Demo<br/>firmware demo<br/>[main.c]"]
  node_node_spi_flash_demo["SPI Flash Demo<br/>firmware demo<br/>[main.c]"]
end

subgraph group_group_support["Support"]
  node_node_samples["Samples<br/>usage examples<br/>[tsdb_sample.c]"]
  node_node_tests["Tests<br/>validation<br/>[fdb_kvdb_tc.c]"]
  node_node_docs["Docs<br/>documentation<br/>[README.md]"]
  node_node_zephyr["Zephyr Module<br/>integration<br/>[module.yml]"]
  node_node_ci["CI<br/>automation<br/>[main.yml]"]
end

node_node_flashdb_api -->|"exports"| node_node_db_common
node_node_db_common -->|"implements"| node_node_kvdb
node_node_db_common -->|"implements"| node_node_tsdb
node_node_db_common -->|"uses"| node_node_db_helpers
node_node_kvdb -->|"reads/writes via"| node_node_fal_api
node_node_tsdb -->|"reads/writes via"| node_node_fal_api
node_node_fal_api -->|"defines"| node_node_fal_core
node_node_fal_core -->|"routes"| node_node_fal_partition
node_node_fal_core -->|"delegates"| node_node_fal_flash
node_node_fal_partition -->|"configured by"| node_node_fal_cfg
node_node_fal_flash -->|"configured by"| node_node_fal_cfg
node_node_linux_demo -->|"uses"| node_node_flashdb_api
node_node_linux_demo -->|"binds to"| node_node_fal_core
node_node_esp_demo -->|"uses"| node_node_flashdb_api
node_node_esp_demo -->|"binds to"| node_node_fal_core
node_node_stm32_demo -->|"uses"| node_node_flashdb_api
node_node_stm32_demo -->|"binds to"| node_node_fal_core
node_node_spi_flash_demo -->|"uses"| node_node_flashdb_api
node_node_spi_flash_demo -->|"binds to"| node_node_fal_core
node_node_samples -->|"shows"| node_node_flashdb_api
node_node_tests -->|"verifies"| node_node_kvdb
node_node_tests -->|"verifies"| node_node_tsdb
node_node_docs -->|"documents"| node_node_flashdb_api
node_node_docs -->|"documents"| node_node_fal_core
node_node_zephyr -->|"integrates"| node_node_flashdb_api
node_node_ci -->|"runs"| node_node_tests

click node_node_flashdb_api "https://github.com/armink/flashdb/blob/master/inc/flashdb.h"
click node_node_db_common "https://github.com/armink/flashdb/blob/master/src/fdb.c"
click node_node_kvdb "https://github.com/armink/flashdb/blob/master/src/fdb_kvdb.c"
click node_node_tsdb "https://github.com/armink/flashdb/blob/master/src/fdb_tsdb.c"
click node_node_db_helpers "https://github.com/armink/flashdb/blob/master/src/fdb_file.c"
click node_node_fdb_cfg "https://github.com/armink/flashdb/blob/master/inc/fdb_cfg_template.h"
click node_node_fal_api "https://github.com/armink/flashdb/blob/master/port/fal/inc/fal.h"
click node_node_fal_core "https://github.com/armink/flashdb/blob/master/port/fal/src/fal.c"
click node_node_fal_flash "https://github.com/armink/flashdb/blob/master/port/fal/src/fal_flash.c"
click node_node_fal_partition "https://github.com/armink/flashdb/blob/master/port/fal/src/fal_partition.c"
click node_node_fal_cfg "https://github.com/armink/flashdb/blob/master/port/fal/samples/porting/fal_cfg.h"
click node_node_linux_demo "https://github.com/armink/flashdb/blob/master/demos/linux/applications/main.c"
click node_node_esp_demo "https://github.com/armink/flashdb/blob/master/demos/esp32_spi_flash/main/main.c"
click node_node_stm32_demo "https://github.com/armink/flashdb/blob/master/demos/stm32f103ve/applications/main.c"
click node_node_spi_flash_demo "https://github.com/armink/flashdb/blob/master/demos/stm32f405rg_spi_flash/applications/main.c"
click node_node_samples "https://github.com/armink/flashdb/blob/master/samples/tsdb_sample.c"
click node_node_tests "https://github.com/armink/flashdb/blob/master/tests/fdb_kvdb_tc.c"
click node_node_docs "https://github.com/armink/flashdb/blob/master/docs/README.md"
click node_node_zephyr "https://github.com/armink/flashdb/blob/master/zephyr/module.yml"
click node_node_ci "https://github.com/armink/flashdb/blob/master/.github/workflows/main.yml"

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_node_flashdb_api,node_node_db_common,node_node_kvdb,node_node_tsdb,node_node_db_helpers,node_node_fdb_cfg toneBlue
class node_node_fal_api,node_node_fal_core,node_node_fal_flash,node_node_fal_partition,node_node_fal_cfg toneAmber
class node_node_linux_demo,node_node_esp_demo,node_node_stm32_demo,node_node_spi_flash_demo toneMint
class node_node_samples,node_node_tests,node_node_docs,node_node_zephyr,node_node_ci toneRose
```

## Components

### Core DB

Portable FlashDB database engine and public API

- [Public API](https://github.com/armink/flashdb/blob/master/inc/flashdb.h): header · Library entry point for consumers · `inc/flashdb.h`
- [DB Core](https://github.com/armink/flashdb/blob/master/src/fdb.c): engine · Shared database logic and record handling · `src/fdb.c`
- [KVDB](https://github.com/armink/flashdb/blob/master/src/fdb_kvdb.c): key-value db · Persistent key-value storage for settings and small blobs · `src/fdb_kvdb.c`
- [TSDB](https://github.com/armink/flashdb/blob/master/src/fdb_tsdb.c): time-series db · Append-oriented timestamped record storage · `src/fdb_tsdb.c`
- [Utils](https://github.com/armink/flashdb/blob/master/src/fdb_file.c): support code · Shared file and utility helpers · `src/fdb_file.c`
- [FDB Config](https://github.com/armink/flashdb/blob/master/inc/fdb_cfg_template.h): config template · Library-side configuration template · `inc/fdb_cfg_template.h`

### FAL

Flash abstraction and partition routing layer

- [FAL API](https://github.com/armink/flashdb/blob/master/port/fal/inc/fal.h): flash abstraction · Flash abstraction layer interface · `port/fal/inc/fal.h`
- [FAL Core](https://github.com/armink/flashdb/blob/master/port/fal/src/fal.c): partition engine · FAL runtime and partition management · `port/fal/src/fal.c`
- [Flash IO](https://github.com/armink/flashdb/blob/master/port/fal/src/fal_flash.c): device I/O · Device read/write/erase dispatch · `port/fal/src/fal_flash.c`
- [Partitions](https://github.com/armink/flashdb/blob/master/port/fal/src/fal_partition.c): layout manager · Partition table and mapping logic · `port/fal/src/fal_partition.c`
- [FAL Config](https://github.com/armink/flashdb/blob/master/port/fal/samples/porting/fal_cfg.h): config layout · Flash devices, partitions, and storage sizing · `port/fal/samples/porting/fal_cfg.h`

### Demos

Host and MCU integration projects showing deployment patterns

- [Linux Demo](https://github.com/armink/flashdb/blob/master/demos/linux/applications/main.c): host demo · Host-side simulation and example app · `demos/linux/applications/main.c`
- [ESP Demo](https://github.com/armink/flashdb/blob/master/demos/esp32_spi_flash/main/main.c): embedded demo · ESP32 and ESP8266 SPI-flash integration projects · `demos/esp32_spi_flash/main/main.c`
- [STM32 Demo](https://github.com/armink/flashdb/blob/master/demos/stm32f103ve/applications/main.c): firmware demo · Bare-metal STM32 integration with board support packages · `demos/stm32f103ve/applications/main.c`
- [SPI Flash Demo](https://github.com/armink/flashdb/blob/master/demos/stm32f405rg_spi_flash/applications/main.c): firmware demo · STM32F405RG project using external SPI flash · `demos/stm32f405rg_spi_flash/applications/main.c`

### Support

Documentation, samples, tests, CI, and Zephyr integration

- [Samples](https://github.com/armink/flashdb/blob/master/samples/tsdb_sample.c): usage examples · Focused KVDB and TSDB example programs · `samples/tsdb_sample.c`
- [Tests](https://github.com/armink/flashdb/blob/master/tests/fdb_kvdb_tc.c): validation · KVDB and TSDB functional coverage · `tests/fdb_kvdb_tc.c`
- [Docs](https://github.com/armink/flashdb/blob/master/docs/README.md): documentation · API, configuration, porting, and demo guides · `docs/README.md`
- [Zephyr Module](https://github.com/armink/flashdb/blob/master/zephyr/module.yml): integration · Zephyr consumption entry point · `zephyr/module.yml`
- [CI](https://github.com/armink/flashdb/blob/master/.github/workflows/main.yml): automation · Repository workflow validation · `.github/workflows/main.yml`

## Connections

- Public API → DB Core: exports · Public API exposes the core database engine
- DB Core → KVDB: implements · Shared engine powers KVDB operations
- DB Core → TSDB: implements · Shared engine powers TSDB operations
- DB Core → Utils: uses · Core logic relies on file and utility helpers
- KVDB → FAL API: reads/writes via · KVDB storage is delegated through FAL
- TSDB → FAL API: reads/writes via · TSDB storage is delegated through FAL
- FAL API → FAL Core: defines · API surface for the flash abstraction layer
- FAL Core → Partitions: routes · FAL core resolves partition-to-device mapping
- FAL Core → Flash IO: delegates · Core delegates physical flash operations
- Partitions → FAL Config: configured by · Partition layout comes from configuration
- Flash IO → FAL Config: configured by · Flash device definitions come from configuration
- Linux Demo → Public API: uses · Host demo exercises the library API
- Linux Demo → FAL Core: binds to · Host demo connects FlashDB to the FAL backend
- ESP Demo → Public API: uses · ESP projects exercise the library API
- ESP Demo → FAL Core: binds to · ESP projects connect through FAL to flash ports
- STM32 Demo → Public API: uses · STM32 firmware uses the library API
- STM32 Demo → FAL Core: binds to · STM32 firmware connects through FAL to board ports
- SPI Flash Demo → Public API: uses · External SPI-flash firmware uses the library API
- SPI Flash Demo → FAL Core: binds to · Firmware bridges FlashDB to hardware flash support
- Samples → Public API: shows · Examples demonstrate the public API
- Tests → KVDB: verifies · Tests cover KVDB behavior
- Tests → TSDB: verifies · Tests cover TSDB behavior
- Docs → Public API: documents · Documentation explains the core API and usage
- Docs → FAL Core: documents · Docs cover the flash abstraction and porting model
- Zephyr Module → Public API: integrates · Zephyr module consumes the library as a package
- CI → Tests: runs · Workflow provides automated verification
