# tderflinger/tcx-ls architecture

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

- Interactive diagram: https://gitdiagram.com/tderflinger/tcx-ls
- Repository: https://github.com/tderflinger/tcx-ls

## Overview

##### Project type and purpose
- This is a single‐executable command‐line tool, written in TypeScript for the Deno runtime, that reads Garmin TCX XML files, computes activity metrics (distance, time, speed, cadence), and either prints them to the console or exports them as GeoJSON or CSV.

##### File structure
- Top‐level:
- main.ts            – CLI entry point
- deno.json, deno.lock – Deno config & dependency lock
- README.md, doc/... – Project documentation
- .github/workflows – CI/CD for building/releasing binary
- src/ folder: core modules
- tcx-reader.ts      – reads & parses the raw XML
- parse-tcx-xml.ts   – XML→in-memory AST of TCX
- calculations.ts    – computes aggregates & statistics
- tcx-console-printer.ts – formats and prints to terminal
- geojson-writer.ts  – serializes trackpoints to GeoJSON
- laps-csv-writer.ts – serializes lap records to CSV
- tests/: automated tests for output formatting

##### Key insights from README
- CLI options trigger different exporters (console, geojson, csv).
- Written for Deno – uses Deno.run, --allow-read, --allow-write.
- No external microservices – pure local file processing.

##### Main components
a. CLI Layer (main.ts + Deno runtime)
b. Input subsystem – TCX Reader & XML parser
c. Processing subsystem – Calculations & Metrics Engine
d. Output subsystem – Console Printer, GeoJSON Writer, CSV Writer
e. File System / OS – read .tcx, write .json/.csv

##### Relationships and data flow
1. User invokes `main.ts` with flags and file path.
2. CLI Layer parses arguments, passes file path + mode to Input subsystem.
3. TCX Reader loads file → hands raw XML to XML Parser.
4. Parser outputs structured data (arrays of laps, trackpoints).
5. Calculations module ingests structured data → computes time/distance/speed/cadence.
6. Depending on flags:
– Console Printer reads calc results → writes to stdout.
– GeoJSON Writer takes trackpoints → writes GeoJSON file.
– CSV Writer takes lap records → writes CSV file.
7. Deno runtime handles file I/O permissions.

##### Architectural patterns & design principles
- Modular single‐process pipeline
- Separation of concerns: parsing / computing / formatting
- Dependency injection by passing data structures between layers
- Easily extensible: add new writer modules (e.g., KML writer)

##### Technologies & frameworks
- Deno (runtime, permission model, built-in testing)
- TypeScript modules
- Standard Deno file and stream APIs
- GitHub Actions for building and releasing native binaries

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    User["User"]:::external

    subgraph "Deno Runtime"
        direction TB

        subgraph "Input Layer"
            direction TB
            CLI["CLI & Arg Parser"]:::input
            Reader["TCX Reader"]:::input
            Parser["XML Parser"]:::input
        end

        subgraph "Processing Layer"
            direction TB
            Calc["Calculations Engine"]:::process
        end

        subgraph "Output Layer"
            direction TB
            Printer["Console Printer"]:::output
            GeoJSON["GeoJSON Writer"]:::output
            CSV["CSV Writer"]:::output
            NewExp["+ New Exporter"]:::output
        end
    end

    FS[(File System)]:::external
    Stdout["Stdout"]:::external

    %% Data flow
    User -->|invoke CLI with flags| CLI
    CLI -->|file path + mode| Reader
    Reader -->|"raw XML"| Parser
    Parser -->|"ActivityData"| Calc
    Calc -->|"print metrics"| Printer
    Calc -->|"trackpoints"| GeoJSON
    Calc -->|"lap records"| CSV
    Calc -->|extension point| NewExp

    Reader -->|read .tcx| FS
    GeoJSON -->|write .geojson| FS
    CSV -->|write .csv| FS
    Printer --> Stdout

    %% Click Events
    click CLI "https://github.com/tderflinger/tcx-ls/blob/main/main.ts"
    click Reader "https://github.com/tderflinger/tcx-ls/blob/main/src/tcx-reader.ts"
    click Parser "https://github.com/tderflinger/tcx-ls/blob/main/src/parse-tcx-xml.ts"
    click Calc "https://github.com/tderflinger/tcx-ls/blob/main/src/calculations.ts"
    click Printer "https://github.com/tderflinger/tcx-ls/blob/main/src/tcx-console-printer.ts"
    click GeoJSON "https://github.com/tderflinger/tcx-ls/blob/main/src/geojson-writer.ts"
    click CSV "https://github.com/tderflinger/tcx-ls/blob/main/src/laps-csv-writer.ts"
    click User "https://github.com/tderflinger/tcx-ls/blob/main/README.md"
    click FS "https://github.com/tderflinger/tcx-ls/blob/main/deno.json"
    click FS "https://github.com/tderflinger/tcx-ls/blob/main/deno.lock"
    click NewExp "https://github.com/tderflinger/tcx-ls/tree/main/doc/"
    click .github "https://github.com/tderflinger/tcx-ls/blob/main/.github/workflows/deploy.yml"
    click Tests "https://github.com/tderflinger/tcx-ls/blob/main/tests/print-data_test.ts"

    %% Styles
    classDef input fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef process fill:#DFF5D8,stroke:#28A745,color:#28A745
    classDef output fill:#FFF4D0,stroke:#E69500,color:#E69500
    classDef external fill:#F0F0F0,stroke:#888888,color:#888888
    class CLI,Reader,Parser input
    class Calc process
    class Printer,GeoJSON,CSV,NewExp output
    class User,FS,Stdout external
```
