# sibyx/phpgpx architecture

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

- Interactive diagram: https://gitdiagram.com/sibyx/phpgpx
- Repository: https://github.com/sibyx/phpgpx

## Overview

##### Project Type and Purpose
- This is a stand-alone PHP library (“open-source tool”) called **phpGPX** for reading, manipulating, and writing GPX (GPS Exchange Format) files.
- There is no frontend/backend web app; it’s a pure library with:
- a facade entry point (`phpGPX\phpGPX`)
- a Parser subsystem to read GPX/XML/JSON into objects
- a Model subsystem representing GPX constructs (File, Track, Segment, Point, Metadata, Extensions)
- a set of Helpers for stats, date/time, geo calculations, serialization
- an output subsystem to emit XML or JSON

##### File-Structure Analysis
- **src/phpGPX**
- `phpGPX.php` – public facade class
- **Parsers** – classes under `src/phpGPX/Parsers` for each GPX element (BoundsParser, RouteParser, TrackParser, etc.) and extension parsers
- **Models** – classes under `src/phpGPX/Models` representing GPX types (GpxFile, Track, Segment, Point, Metadata, plus AbstractExtension, TrackPointExtension)
- **Helpers** – utility classes for statistics calculation, date/time formatting, geo formulas, serialization logic
- **example/** – sample usage scripts
- **tests/** – PHPUnit test suites for parsers, helpers, integration
- **docs/** – Jekyll-generated documentation

##### README Insights
- Confirms layered architecture:
- instantiate `new phpGPX()`
- `->load(…)` invokes Parsers → builds Model graph
- manipulate `Model` objects (e.g. recalc stats)
- `->save(…, XML|JSON)` uses SerializationHelper to emit output
- Stats flags and configuration constants in facade

##### Main Components & How to Illustrate Them
a. **Facade / API Layer**
- `phpGPX\phpGPX`
- Exposes `load()`, `save()`, static config flags
b. **Parser Layer**
- Package: `phpGPX\Parsers`
- Individual Parsers (PointParser, TrackParser, etc.)
- **Dependency**: each Parser uses Models to instantiate objects; extension parsers plug in via ExtensionParser
c. **Model Layer**
- Package: `phpGPX\Models`
- Core classes: `GpxFile`, `Track`, `Segment`, `Point`, `Metadata`, `Route`, `Bounds`, `Link`, `Email`, etc.
- **Stats**: `Stats`, `StatsCalculator` attached to Track, Segment
- **Extensions**: AbstractExtension, TrackPointExtension
d. **Helper / Service Layer**
- Package: `phpGPX\Helpers`
- Utilities: `DateTimeHelper`, `GeoHelper`, `BoundsCalculator`, `DistanceCalculator`, `ElevationGainLossCalculator`, `SerializationHelper`
- **Usage**: invoked by Parsers and by Model methods (e.g., `recalculateStats()`)
e. **Serialization / Output Layer**
- Formats: XML and JSON
- Implemented by `SerializationHelper` in Helpers and by `Model::toXML()`, `Model::toJSON()`
f. **Examples & Tests** (supporting components)
- `example/` scripts show integration usage
- `tests/` show unit tests per Parser/Helper

##### Relationships & Interactions
- Parser(s) → instantiate → **Model Layer** objects
- Model objects → call → **Helper Layer** (stats, serialization)
- Model objects → returned to → **Caller**
- Caller → **Facade** → save → **Serialization** → writes XML/JSON

##### Architectural Patterns & Principles
- **Layered Architecture**: clear separation of concerns
- **Package by Responsibility**: Parsers, Models, Helpers
- **Facade Pattern**: single entrypoint (`phpGPX`) hiding complexity
- **Open/Closed for Extensions**: extension parsers and model extensions
- **Dependency Injection** (light): Parsers receive raw data and output models

##### Detail Level
- Be exhaustive in labeling each package and major class group
- **all** architectural elements: entrypoint, all three layers, extension subsystem, config flags, supported output formats
- Do not clutter with CI/config files—they lie outside the runtime architecture

## Diagram (Mermaid)

```mermaid
graph TB
    Facade["phpGPX (Facade/API)"]:::facade
    ParserLayer["Parser Layer"]:::parser
    ModelLayer["Model Layer"]:::model
    HelperLayer["Helper/Service Layer"]:::helper
    Output["Serialization Output\n(XML/JSON)"]:::serialization

    subgraph "Parser Layer"
        BP["BoundsParser"]:::parser
        RP["RouteParser"]:::parser
        TP["TrackParser"]:::parser
        SP["SegmentParser"]:::parser
        PoP["PointParser"]:::parser
        WP["WaypointParser"]:::parser
        LiP["LinkParser"]:::parser
        MP["MetadataParser"]:::parser
        PerP["PersonParser"]:::parser
        EmP["EmailParser"]:::parser
        CP["CopyrightParser"]:::parser
        ExP["ExtensionParser"]:::parser
        TExP["TrackPointExtensionParser"]:::parser
    end

    subgraph "Model Layer"
        GF["GpxFile"]:::model
        T["Track"]:::model
        Sg["Segment"]:::model
        Pt["Point"]:::model
        R["Route"]:::model
        M["Metadata"]:::model
        B["Bounds"]:::model
        L["Link"]:::model
        Pe["Person"]:::model
        Em["Email"]:::model
        St["Stats"]:::model
        SC["StatsCalculator"]:::model
        SU["Summarizable"]:::model
        Col["Collection"]:::model
        AbsE["AbstractExtension"]:::model
        TEx["TrackPointExtension"]:::model
    end

    subgraph "Helper/Service Layer"
        DTH["DateTimeHelper"]:::helper
        GH["GeoHelper"]:::helper
        BC["BoundsCalculator"]:::helper
        DC["DistanceCalculator"]:::helper
        EG["ElevationGainLossCalculator"]:::helper
        SH["SerializationHelper"]:::helper
    end

    Facade -->|"load() parse"| ParserLayer
    ParserLayer -->|"instantiate"| ModelLayer
    ModelLayer -->|"calcStats()/toXML()"| HelperLayer
    HelperLayer -->|"emit XML/JSON"| Output
    Facade -->|"save()"| Output

    click Facade "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/phpGPX.php"

    click ParserLayer "https://github.com/sibyx/phpgpx/tree/master/src/phpGPX/Parsers/"
    click BP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/BoundsParser.php"
    click RP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/RouteParser.php"
    click TP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/TrackParser.php"
    click SP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/SegmentParser.php"
    click PoP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/PointParser.php"
    click WP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/WaypointParser.php"
    click LiP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/LinkParser.php"
    click MP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/MetadataParser.php"
    click PerP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/PersonParser.php"
    click EmP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/EmailParser.php"
    click CP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/CopyrightParser.php"
    click ExP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/ExtensionParser.php"
    click TExP "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Parsers/Extensions/TrackPointExtensionParser.php"

    click ModelLayer "https://github.com/sibyx/phpgpx/tree/master/src/phpGPX/Models/"
    click GF "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/GpxFile.php"
    click T "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Track.php"
    click Sg "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Segment.php"
    click Pt "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Point.php"
    click R "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Route.php"
    click M "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Metadata.php"
    click B "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Bounds.php"
    click L "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Link.php"
    click Pe "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Person.php"
    click Em "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Email.php"
    click St "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Stats.php"
    click SC "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/StatsCalculator.php"
    click SU "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Summarizable.php"
    click Col "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Collection.php"
    click AbsE "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Extensions/AbstractExtension.php"
    click TEx "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Models/Extensions/TrackPointExtension.php"

    click HelperLayer "https://github.com/sibyx/phpgpx/tree/master/src/phpGPX/Helpers/"
    click DTH "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Helpers/DateTimeHelper.php"
    click GH "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Helpers/GeoHelper.php"
    click BC "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Helpers/BoundsCalculator.php"
    click DC "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Helpers/DistanceCalculator.php"
    click EG "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Helpers/ElevationGainLossCalculator.php"
    click SH "https://github.com/sibyx/phpgpx/blob/master/src/phpGPX/Helpers/SerializationHelper.php"

    classDef facade fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef parser fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef model fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef helper fill:#e2d6f3,stroke:#333,stroke-width:1px;
    classDef serialization fill:#ffe5b4,stroke:#333,stroke-width:1px;
```
