# marnunez/basictdf architecture

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

- Interactive diagram: https://gitdiagram.com/marnunez/basictdf
- Repository: https://github.com/marnunez/basictdf

## Overview

##### Project type and purpose
- This is an open-source Python library (basictdf) for reading and writing the BTS Bioengineering TDF binary data format.
- Its core responsibility is to parse a .tdf file into in-memory Python objects (and vice versa), expose a clean API for clients, and ship documentation and tests with CI/CD.

##### File structure
- `src/basictdf/`: the heart of the parser. Contains:
- basictdf.py – top-level façade
- tdfBlock.py, tdfCalibrationData.py, tdfData2D.py, tdfData3D.py, tdfEMG.py, tdfEvents.py, tdfForce3D.py, tdfForcePlatformsCalibration.py, tdfForcePlatformsData.py, tdfOpticalSystem.py, tdfTypes.py, tdfUtils.py
– these map to the various components (blocks) of the TDF format.
- `tests/`: unit tests for each component and end-to-end file parsing.
- `.github/workflows/`: CI pipelines for testing and publishing to TestPyPI.
- `docs/`: generated HTML docs for each module.
- `pyproject.toml` & `tox.ini`: build, test, and packaging config.

##### README for additional insights
- It confirms usage via `pip install basictdf` (PyPI distribution) and docs hosted on GitHub Pages.
- Development uses Poetry for dependency management.
- No external microservices or DB—just file I/O and in-process parsing.

a. Main components
- Client Application – any user script that calls basictdf API
- I/O Layer – file reader/writer (wrapped around Python’s `open`, `io`, `struct`)
- Parser Engine – orchestrates parsing: reads block headers, dispatches to specific block parsers
- Block Parsers & Data Models – modules for each TDF block type (Block, CalibrationData, Data2D, Data3D, EMG, Events, Force3D, ForcePlatformsCalibration, ForcePlatformsData, OpticalSystem)
- Utility Module – common functions (byte conversions, checksum, etc.)
- Packaging & Distribution – Poetry, PyPI
- Documentation Generator – Sphinx (via docs folder)
- CI/CD – GitHub Actions (test.yml, publish-to-test-pypi.yml)

b. Relationships & interactions
1. Client calls `basictdf.read_tdf(filename)`
2. I/O Layer reads raw bytes → feeds Parser Engine
3. Parser Engine uses Utility Module to interpret headers and routes payload to the proper Block Parser
4. Block Parser instantiates a Data Model object, populates fields, returns it to the engine
5. Engine assembles all blocks into a high-level Python object and returns to client
6. Client can manipulate objects, then call `basictdf.write_tdf(obj, filename)` to reverse the flow
7. On commit, CI/CD runs tests, builds docs, optionally publishes to TestPyPI
8. Documentation Generator consumes docstrings in source to produce HTML in `docs/`

c. Architectural patterns & design principles
- Modular parsing: one parser per block type (Separation of Concerns)
- Layered design: I/O → Engine → Data Models → Client
- Convention over configuration: naming of modules matches TDF block names
- CI/CD as code: GitHub workflows define build/test/publish steps

d. Key technologies & libraries
- Python’s built-ins: `io`, `struct`, `pathlib`
- Poetry for dependency & packaging
- Sphinx (implied by docs) for documentation
- pytest or unittest for tests
- GitHub Actions for CI/CD

##### Diagramming recommendations
- Blue for runtime components (I/O, Engine, Parsers)
- Green for external dependencies (file system, PyPI, GitHub Actions)
- Yellow for development tooling (Poetry, Sphinx)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client Application"]:::external

    %% Runtime Components
    subgraph "Runtime Components"
        direction TB
        IO["I/O Layer"]:::runtime
        Engine["Parser Engine"]:::runtime
        subgraph "Block Parsers & Data Models"
            direction TB
            BlockBase["Base Block Parser"]:::runtime
            Calib["Calibration Data Parser"]:::runtime
            Data2D["2D Data Parser"]:::runtime
            Data3D["3D Data Parser"]:::runtime
            EMG["EMG Parser"]:::runtime
            Events["Events Parser"]:::runtime
            F3D["Force 3D Parser"]:::runtime
            FPlatCal["Force Platforms Calibration Parser"]:::runtime
            FPlatData["Force Platforms Data Parser"]:::runtime
            Optical["Optical System Parser"]:::runtime
            Types["Data Types Module"]:::runtime
        end
        Utils["Utility Module"]:::runtime
    end

    %% Storage and External
    FileSystem["File System"]:::external
    subgraph "Distribution"
        direction TB
        PyPI["TestPyPI"]:::external
    end

    %% Development & CI/CD
    subgraph "Development & CI/CD"
        direction TB
        Docs["Documentation Generator Output"]:::dev
        Tests["Unit Tests Suite"]:::dev
        Poetry["Poetry Config (pyproject.toml)"]:::dev
        Tox["Test & Lint Config (tox.ini)"]:::dev
        CI_Test["CI: Test Pipeline"]:::external
        CI_Publish["CI: Publish-to-TestPyPI"]:::external
    end

    %% Read Flow
    Client -->|"read_tdf()"| IO
    IO -->|"raw bytes"| Engine
    Engine -->|"interpret header"| Utils
    Engine -->|"dispatch to"| BlockBase
    Engine --> BlockBase & Calib & Data2D & Data3D & EMG & Events & F3D & FPlatCal & FPlatData & Optical
    BlockBase & Calib & Data2D & Data3D & EMG & Events & F3D & FPlatCal & FPlatData & Optical -->|"produce data objects"| Types
    Types --> Engine
    Engine -->|"return TDF object"| Client

    %% Write Flow
    Client -->|"write_tdf()"| Engine
    Engine -->|"serialize data"| BlockBase & Calib & Data2D & Data3D & EMG & Events & F3D & FPlatCal & FPlatData & Optical
    Engine --> IO
    IO -->|write bytes| FileSystem

    %% CI/CD Flows
    CI_Test --> Tests
    CI_Test -->|"runs on push"| Engine
    CI_Publish -->|"on tag"| PyPI

    %% Docs Flow
    Engine -->|"docstrings"| Docs

    %% Click Events
    click Client "https://github.com/marnunez/basictdf/blob/master/src/basictdf/basictdf.py"
    click IO "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfUtils.py"
    click Engine "https://github.com/marnunez/basictdf/blob/master/src/basictdf/basictdf.py"
    click BlockBase "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfBlock.py"
    click Calib "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfCalibrationData.py"
    click Data2D "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfData2D.py"
    click Data3D "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfData3D.py"
    click EMG "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfEMG.py"
    click Events "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfEvents.py"
    click F3D "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfForce3D.py"
    click FPlatCal "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfForcePlatformsCalibration.py"
    click FPlatData "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfForcePlatformsData.py"
    click Optical "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfOpticalSystem.py"
    click Types "https://github.com/marnunez/basictdf/blob/master/src/basictdf/tdfTypes.py"
    click Tests "https://github.com/marnunez/basictdf/tree/master/tests/"
    click Docs "https://github.com/marnunez/basictdf/tree/master/docs/"
    click CI_Test "https://github.com/marnunez/basictdf/blob/master/.github/workflows/test.yml"
    click CI_Publish "https://github.com/marnunez/basictdf/blob/master/.github/workflows/publish-to-test-pypi.yml"
    click Poetry "https://github.com/marnunez/basictdf/blob/master/pyproject.toml"
    click Tox "https://github.com/marnunez/basictdf/blob/master/tox.ini"

    %% Styles
    classDef runtime fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef external fill:#E6FFEA,stroke:#28A745,stroke-width:1px
    classDef dev fill:#FFF5B1,stroke:#D4A017,stroke-width:1px
```
