# balena-io-modules/drivelist architecture

> Architecture diagram of the GitHub repository balena-io-modules/drivelist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/balena-io-modules/drivelist
- Repository: https://github.com/balena-io-modules/drivelist

## Overview

##### Project Type and Purpose
- Purpose: The “drivelist” project is a cross-platform Node.js library that retrieves and lists drive information from the host machine. It abstracts the OS-specific logic, so the end user interacts with a unified API.
- Project Type: A Node.js module with native bindings. It leverages both JavaScript/TypeScript (in the lib folder) and native code (in src folders for darwin, linux, and windows) to support different platforms.

##### File Structure
- Top-Level Overview:
- Configuration files (.editorconfig, .eslintrc.yml, .npmignore, etc.) help ensure coding standards.
- GitHub workflows and CI configurations (inside the .github directory) indicate automated testing and continuous integration.
- The presence of binding.gyp shows native module compilation, linking the C/C++ (and Objective-C on macOS) components to the Node.js runtime.
- The lib directory contains TypeScript files that likely serve as the higher-level API and helper utilities (e.g., the “lsblk” subfolder handles Linux-specific behavior).
- The src directory houses platform-specific implementations:
- src/darwin: Contains Objective-C/Objective-C++ code for macOS.
- src/linux: Contains C++ code for Linux.
- src/windows: Contains C++ code for Windows.
- The tests folder includes unit and integration tests with sample data to validate drive listing outputs.

##### Key Components
a. Main Application Components:
- API Layer: Represented by the “lib/index.ts” which exports the main “drivelist.list()” function for users.
- Platform-agnostic module: This component detects the operating system based on runtime conditions.

b. OS-Specific Adapter Components:
- Linux Adapter:
- Implemented in src/linux and supported by helper code in lib/lsblk.
- It parses the output of system commands (e.g., “lsblk”).
- macOS (Darwin) Adapter:
- Implemented in src/darwin using Objective-C/C++.
- Windows Adapter:
- Present in src/windows with corresponding C++ implementations.
- Native Binding Infrastructure: The binding.gyp file and associated build system compile these native components as part of the Node.js module.

c. Supporting Components:
- Testing Infrastructure: Represent tests that simulate input data (e.g., tests/data/lsblk files) and validate the output format.

##### Relationships and Interactions
- Data Flow:
1. When a user calls drivelist.list(), the API layer (in lib/index.ts) receives the request.
2. OS Detection: The module checks the current operating system.
3. Based on OS, the corresponding adapter is invoked:
- For Linux, it may trigger a system command (lsblk) and then use the helper functions from lib/lsblk for JSON parsing.
- For macOS, it forwards the request to the native macOS code in src/darwin.
- For Windows, the request goes to the corresponding code in src/windows.
4. Each adapter fetches and formats drive data, returning a consistent structure to the API layer.
5. The API layer aggregates and returns this data to the caller.
- Dependency of the JavaScript/TypeScript front end on these compiled native components (using Node Addons).

##### Architectural Patterns and Design Principles
- Abstraction and Modularity: Separation between the high-level API and the platform-specific implementations.
- Adapter Pattern: OS-specific adapters allow the use of a single API irrespective of underlying OS differences.
- Native Integration: Use of binding.gyp indicates bridging native code with Node.js through compiled C/C++/Objective-C modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("User calls drivelist.list()"):::logic
    B("Drivelist API Layer"):::js
    C("OS Detector"):::logic
    D("Linux Adapter"):::native
    E("Lib/lsblk Utility"):::js
    F("macOS Adapter"):::native
    G("Windows Adapter"):::native
    H("Native Bindings/Build Process"):::native
    I("Test Suite"):::test
    J("CI/CD Pipelines"):::ci

    A -->|"invokes"| B
    B -->|"detectsOS"| C
    C -->|"Linux"| D
    C -->|"macOS"| F
    C -->|"Windows"| G

    D -->|"uses"| E
    D -->|"builtWith"| H
    F -->|"builtWith"| H
    G -->|"builtWith"| H

    D -->|"returnsData"| B
    F -->|"returnsData"| B
    G -->|"returnsData"| B
    B -->|"respondsTo"| A

    I -.->|"validates"| B
    J -.->|"deploysTests"| B

    click B "https://github.com/balena-io-modules/drivelist/blob/master/lib/index.ts"
    click D "https://github.com/balena-io-modules/drivelist/tree/master/src/linux"
    click E "https://github.com/balena-io-modules/drivelist/tree/master/lib/lsblk/"
    click F "https://github.com/balena-io-modules/drivelist/tree/master/src/darwin"
    click G "https://github.com/balena-io-modules/drivelist/tree/master/src/windows"
    click H "https://github.com/balena-io-modules/drivelist/blob/master/binding.gyp"
    click I "https://github.com/balena-io-modules/drivelist/tree/master/tests"
    click J "https://github.com/balena-io-modules/drivelist/blob/master/.github"

    classDef js fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef native fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef test fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef ci fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef logic fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
