# muktihari/fit architecture

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

- Interactive diagram: https://gitdiagram.com/muktihari/fit
- Repository: https://github.com/muktihari/fit

## Overview

##### Project Type and Purpose
- This is a Go‐based SDK for the Garmin FIT protocol plus a suite of command-line tools (fitactivity, fitconv, fitprint, fitdump).
- Its main responsibilities are:
- Decoding binary FIT files into messages or CSV/text formats
- Encoding messages or CSV back into FIT
- Offering a library API for Go programs to read/write FIT protocol messages with full semantics (message order, unknown/developer fields)
- Providing code-generation and runtime-registration mechanisms for custom/manufacturer‐specific messages

A. CLI Layer (cmd/)
- fitactivity (combine, conceal, reduce/remove messages)
- fitconv (FIT ⇄ CSV)
- fitprint (human-readable TXT dump)
- fitdump (hex/segmented dump)
B. Core FIT SDK
1. decoder/
– ReadBuffer → bits → raw frames → Listener → protocol messages
2. encoder/
– Validator → LRU caching → WriteBuffer → binary FIT stream
3. proto/
– Message/value marshal/unmarshal, versioning, validation
4. profile/ (generated code)
– basetype, filedef, mesgdef, typedef, untyped → Go structs & constants representing every FIT message/field
5. kit/ & internal/
– Utilities (datetime, hash, semicírculos, sliceutil) & internal command helpers (benchfit, csvdiff, fitgen, testgen)
C. Code-Generation Subsystem (internal/cmd/fitgen + docs/)
- Parser reads Profile.xlsx, generator templates produce profile/mesgdef and profile/typedef
- Provides: custom‐SDK generation, runtime registration API (factory package)
D. Data Sources & Sinks
- Input: .fit files, .csv files, Profile.xlsx (for codegen)
- Output: new .fit files, .csv dumps, .txt reports, benchmarks

##### Relationships & Data Flow
- CLI Tool → invokes Core SDK API
- Core SDK Decode: FIT file → decoder → proto → profile messages → CLI prints or converts to CSV/TXT
- Core SDK Encode: CSV (or Go structs) → profile messages → proto marshal → encoder → FIT file
- Codegen tool (fitgen) → reads Profile.xlsx → outputs Go code (profile/) → included in Core SDK build
- internal/cmd/benchfit → uses Core SDK to benchmark against third-party library

##### Architectural Patterns & Principles
- Layered design: CLI → Core Library → lower-level wire/frame processing
- Separation of concerns: decoder vs. proto vs. encoder vs. profile data
- Code generation for protocol definitions (DRY & maintainability)
- Pluggable/customizable profiles via runtime registration or codegen

##### Final Advice
- Both the static structure (packages/modules) and dynamic data flow (FIT → CSV → FIT; codegen → profile)
- Use layering (top = CLI, mid = core, bottom = low-level frame processing) to make the architecture immediately clear
- Review README and docs/usage.md to ensure all features (developer fields, compressed timestamps, benchmarks) are represented

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Sources
    subgraph "External Files" 
        direction TB
        FIT[".fit file"]:::external
        CSV[".csv file"]:::external
        TXT[".txt report"]:::external
        XLSX["Profile.xlsx"]:::external
    end

    %% Code-Generation Subsystem
    subgraph "Code-Generation Subsystem" 
        direction TB
        FITGEN["fitgen"]:::codegen
        FACTORY["factory (runtime registration)"]:::codegen
    end

    %% Core FIT Engine
    subgraph "Core FIT Engine" 
        direction TB
        DECODER["decoder"]:::core
        PROTO["proto"]:::core
        PROFILE["profile (generated)"]:::core
        ENCODER["encoder"]:::core
    end

    %% CLI Applications
    subgraph "CLI Apps" 
        direction TB
        FITACT["fitactivity"]:::cli
        FITCONV["fitconv"]:::cli
        FITPRINT["fitprint"]:::cli
        FITDUMP["fitdump"]:::cli
    end

    %% Utilities & Internal Tools
    subgraph "Utilities & Internal Tools"
        direction TB
        KIT["kit"]:::utility
        INTERNAL["internal tools"]:::utility
    end

    %% Data Flow: Codegen
    XLSX -->|reads Profile.xlsx| FITGEN
    FITGEN -->|generates Go code| PROFILE
    PROFILE -->|includes factory API| FACTORY

    %% Data Flow: Decode Path
    FIT -->|input FIT| FITCONV
    FITCONV -->|decode| DECODER
    DECODER -->|raw frames| PROTO
    PROTO -->|messages| PROFILE
    PROFILE -->|Go structs| FITCONV
    FITCONV -->|output CSV| CSV

    %% Data Flow: Encode Path
    CSV -->|input CSV| FITCONV
    FITCONV -->|encode| ENCODER
    ENCODER -->|binary stream| PROFILE
    PROFILE -->|Go structs| ENCODER
    ENCODER -->|output FIT| FIT

    %% Other CLI Tools
    FITACT -->|uses Core SDK| DECODER
    FITACT -->|uses Core SDK| ENCODER
    FITPRINT -->|uses Core SDK| DECODER
    FITPRINT -->|outputs TXT| TXT
    FITDUMP -->|uses Core SDK| DECODER
    FITDUMP -->|outputs hex dump| TXT

    %% Utilities Relationships
    KIT -->|helpers| DECODER
    KIT -->|helpers| ENCODER
    INTERNAL -->|benchfit| DECODER
    INTERNAL -->|csvdiff| DECODER
    INTERNAL -->|testgen| ENCODER

    %% Click Events
    click FITACT "https://github.com/muktihari/fit/tree/master/cmd/fitactivity"
    click FITCONV "https://github.com/muktihari/fit/tree/master/cmd/fitconv"
    click FITPRINT "https://github.com/muktihari/fit/tree/master/cmd/fitprint"
    click FITDUMP "https://github.com/muktihari/fit/tree/master/cmd/fitdump"
    click DECODER "https://github.com/muktihari/fit/tree/master/decoder/"
    click ENCODER "https://github.com/muktihari/fit/tree/master/encoder/"
    click PROTO "https://github.com/muktihari/fit/tree/master/proto/"
    click PROFILE "https://github.com/muktihari/fit/tree/master/profile/"
    click KIT "https://github.com/muktihari/fit/tree/master/kit/"
    click INTERNAL "https://github.com/muktihari/fit/tree/master/internal/"
    click FITGEN "https://github.com/muktihari/fit/tree/master/internal/cmd/fitgen"
    click FACTORY "https://github.com/muktihari/fit/tree/master/profile/factory"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#007bff,color:#004085,stroke-width:1px;
    classDef core fill:#d4edda,stroke:#28a745,color:#155724,stroke-width:1px;
    classDef codegen fill:#fff3cd,stroke:#ffc107,color:#856404,stroke-width:1px;
    classDef utility fill:#e2e3e5,stroke:#6c757d,color:#1b1e21,stroke-width:1px;
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#1b1e21,stroke-width:1px,shape:parallelogram;
```
