# soma-bionics/movedb-core architecture

> Architecture diagram of the GitHub repository soma-bionics/movedb-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/soma-bionics/movedb-core
- Repository: https://github.com/soma-bionics/movedb-core

## Overview

##### Project Type and Purpose
- This is a Python-based core library (not a standalone web or desktop app) for motion capture data operations (“MoveDB Core”).
- It focuses on reading C3D files, processing time-series and force-platform data, validating it, and exporting to OpenSim formats.

##### Top-Level Architectural Components
a. User Application Layer
- Client code or scripts (e.g., a researcher's Python script, CLI wrappers, notebooks) that import `movedb.core.Trial`.
b. Public API Layer (`src/movedb`)
- movedb.core – Domain classes (Trial, Points, Analogs, Event, ForcePlatform, enums)
- movedb.file_io – I/O adapters (C3DLoader using `ezc3d`, OpenSimExporter using `opensim` SDK)
- movedb.utils – Pure-Python helper functions (data normalization, logging, validation utilities)
c. External Dependencies
- ezc3d – Native C library bindings for C3D I/O
- opensim (OpenSim-org SDK) – For model export and inverse kinematics
- pydantic – Data validation and type safety

##### Data Flow and Component Interactions
1. The User Application invokes:
Trial.from_c3d_file(path)
↓
2. C3DLoader (in movedb.file_io)
- Reads binary C3D → produces raw trajectories & analog frames
↓
3. movedb.core.Trial constructor
- Instantiates data classes: Points (time-series), Analogs, Event, EZC3DForcePlatform
- Uses movedb.utils for gap detection, validation (Pydantic)
↓
4. Business Logic
- Data transformations (units, coordinate systems)
- Force platform processing (filtering, mappings)
↓
5. Export / Downstream Services
- Trial.to_trc(), to_mot(), to_xml() via OpenSimExporter → writes TRC/MOT/XML
- Optionally: run_opensim_ik() calls opensim API to compute IK results

##### Architectural Patterns & Design Principles
- Modular layering: clear separation of I/O (movedb.file_io), domain model (movedb.core), helpers (movedb.utils).
- Dependency inversion: core classes depend on abstracted loader/exporter interfaces.
- Single responsibility: each submodule has isolated concerns (I/O vs. model vs. utils).
- Type safety via Pydantic models for all core data containers.

##### Detail Without Overthinking
- Every logical component (core classes, file-io adapters, utils, external libs).
- Directional data flow from file input through processing to file output.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    Client["Client Scripts / Notebooks"]:::external
    ezc3d["ezc3d"]:::external
    pydantic["pydantic"]:::external
    opensim["OpenSim SDK"]:::external
    FileSystem[("File System<br/>(C3D, TRC, MOT, XML)")]:::storage

    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        subgraph "movedb.core"
            direction TB
            Trial["Trial"]:::core
            TimeSeries["Points & Analogs"]:::core
            Event["Event"]:::core
            ForcePlatform["ForcePlatform"]:::core
            Enums["Enums"]:::core
            Sentinels["Sentinels"]:::core
        end

        subgraph "movedb.file_io"
            direction TB
            C3DLoader["C3DLoader"]:::io
            OpenSimExporter["OpenSimExporter"]:::io
        end

        subgraph "movedb.utils"
            direction TB
            Utils["Utils"]:::utils
        end
    end

    %% Data Flow
    Client -->|"Trial.from_c3d_file()"| Trial
    Trial -->|"load()"| C3DLoader
    C3DLoader -->|"binary C3D I/O"| ezc3d
    ezc3d -->|"raw trajectories & analogs"| Trial
    Trial -->|"validate() / gap detect"| Utils
    Trial -->|"Pydantic models"| pydantic
    Trial -->|"to_trc()/to_mot()/to_xml()"| OpenSimExporter
    OpenSimExporter -->|"export API"| opensim
    OpenSimExporter -->|"write files"| FileSystem

    %% Click Events
    click Trial "https://github.com/soma-bionics/movedb-core/blob/main/src/movedb/core/trial.py"
    click TimeSeries "https://github.com/soma-bionics/movedb-core/blob/main/src/movedb/core/time_series.py"
    click Event "https://github.com/soma-bionics/movedb-core/blob/main/src/movedb/core/events.py"
    click ForcePlatform "https://github.com/soma-bionics/movedb-core/blob/main/src/movedb/core/force_platforms.py"
    click Enums "https://github.com/soma-bionics/movedb-core/blob/main/src/movedb/core/enums.py"
    click Sentinels "https://github.com/soma-bionics/movedb-core/blob/main/src/movedb/core/sentinels.py"
    click C3DLoader "https://github.com/soma-bionics/movedb-core/blob/main/src/movedb/file_io/c3d_io.py"
    click OpenSimExporter "https://github.com/soma-bionics/movedb-core/blob/main/src/movedb/file_io/opensim_exporters.py"
    click Utils "https://github.com/soma-bionics/movedb-core/blob/main/src/movedb/utils/utils.py"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1,stroke-width:1px
    classDef io fill:#c8e6c9,stroke:#388e3c,color:#1b5e20,stroke-width:1px
    classDef utils fill:#fff9c4,stroke:#fbc02d,color:#f57f17,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#616161,color:#212121,stroke-width:1px
    classDef storage fill:#d1c4e9,stroke:#5e35b1,color:#311b92,stroke-width:1px
```
