# thomasparistech/pretty-gpx architecture

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

- Interactive diagram: https://gitdiagram.com/thomasparistech/pretty-gpx
- Repository: https://github.com/thomasparistech/pretty-gpx

## Overview

##### Project type and purpose
- **Type**: A full-stack, Python-based web application (monolithic server) with a browser-based UI.
- **Purpose**: Users upload GPX tracks and generate printable route posters in “city” or “mountain” modes, leveraging external map/elevation services.

##### File structure
- **Top-level**
- `.devcontainer`, `.github`, CI/CD configs → development environment & pipelines
- `pretty_gpx/` → application code
- `scripts/` → helper/deploy/lint/test scripts
- **`pretty_gpx/` structure**
- `main.py` → entry point (starts NiceGUI server)
- `ui/` → UI layer (pages, widgets, NiceGUI bindings)
- `common/` → shared utilities: GPX I/O, drawing primitives, layout, logging, caching, path utils
- `rendering_modes/` → mode-specific logic
– `city/` and `mountain/` and `multi_mountain/` subfolders
– each defines data loaders, drawer components, parameters
- `simplify_gpx.py`, `explore_color_themes.py`, `fly/` → CLI and deployment setup
- `test/` → automated tests
- **External config**
- `pyproject.toml`, Dockerfiles, `fly.toml` → packaging & deployment

##### Extract architectural insights from the README
- **UI Framework**: NiceGUI (Python server renders HTML/JS to browser)
- **Core services**:
- Overpass API (OpenStreetMap data)
- Copernicus DEM (elevation data)
- **Workflow**:
1. User uploads GPX → parsed & simplified
2. Data fetched (OSM, DEM) via `common/request` modules with caching
3. Track + background drawn with `drawing` utils and mode-specific drawers
4. Poster rendered in browser; user can customize parameters → triggers re-render
5. Download as SVG/PNG

##### Components & interactions
a. **Frontend (Browser)**
- NiceGUI‐generated pages (upload form, controls, canvas)
b. **Backend (Python Server)**
- **UI Controller** (`ui/`): maps HTTP & WebSocket calls → business logic
- **GPX Parser** (`common/gpx`): reads & simplifies GPX tracks
- **Renderer**
- **Drawing utils** (`common/drawing/utils`)
- **Components** (`common/drawing/components`)
- **Mode‐specific drawers** (`rendering_modes/*/drawing`)
- **Data Fetcher** (`common/request`): Overpass & DEM requests + caching
- **Layout Manager** (`common/layout`): paper sizes & text allocation
- **Helpers** (`common/utils`): logging, paths, configuration
c. **External Services**
- Overpass API (OSM)
- Copernicus DEM
d. **Storage & Cache**
- Local file cache for tiles, OSM extracts, elevation tiles
- Temporary GPX uploads

##### Relationships & data flow
1. Browser → (upload GPX + UI events) → UI Controller
2. UI Controller → GPX Parser & Simplifier
3. Parser → Data Fetcher (for background)
4. Data Fetcher ↔ External APIs (Overpass, DEM) → caches responses
5. Renderer (Drawing utils + Mode drawer) ← GPX & fetched data
6. Renderer → Canvas in Browser
7. Browser “Download” → static export endpoint → file download

##### Architectural patterns & principles
- **Layered architecture**: UI → business logic → data access → external services
- **Separation of concerns**: Distinct packages for parsing, drawing, data fetching, and UI
- **Plugin-style rendering modes**: Each mode implements same interface (data loader + drawer)
- **Caching**: Avoids redundant Overpass/DEM calls

##### Additional elements
- **CI/CD pipeline**: GitHub Actions (check.yml, validate-pr-title) → Docker build → deploy (fly.toml)
- **Dev environment**: `.devcontainer`
- **Tests**: test suite invokes core logic independently

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Client
  subgraph "Client (Browser)"
    direction TB
    UI["NiceGUI UI Controller"]:::frontend
  end

  %% Server
  subgraph "Server (pretty_gpx)"
    direction TB
    Main["main.py"]:::core

    subgraph "UI Layer"
      Controller["pretty_gpx/ui/"]:::frontend
    end

    subgraph "Parsing & Simplification"
      Parser["pretty_gpx/common/gpx/"]:::core
    end

    subgraph "Data Access"
      Fetcher["pretty_gpx/common/request/"]:::data
      Cache["Local File Cache"]:::storage
    end

    subgraph "Rendering"
      subgraph "Drawing Utils"
        DU["pretty_gpx/common/drawing/utils/"]:::core
      end
      subgraph "Drawing Components"
        DC["pretty_gpx/common/drawing/components/"]:::core
      end
      subgraph "Mode Renderers"
        City["pretty_gpx/rendering_modes/city/"]:::core
        Mountain["pretty_gpx/rendering_modes/mountain/"]:::core
        MultiMtn["pretty_gpx/rendering_modes/multi_mountain/"]:::core
      end
    end

    subgraph "Layout & Utils"
      Layout["pretty_gpx/common/layout/"]:::core
      Utils["pretty_gpx/common/utils/"]:::core
    end
  end

  %% External Services
  CloudOverpass["Overpass API"]:::external
  CloudDEM["Copernicus DEM"]:::external

  %% Infra
  DevContainer[".devcontainer/"]:::infra
  GitHubActions[".github/workflows/"]:::infra
  FlyIO["fly.toml & pretty_gpx/fly/"]:::infra

  %% Data Flows
  UI -->|"GPX Upload & Controls"| Main
  Main --> Controller
  Controller -->|"Parse GPX"| Parser
  Parser --> Fetcher
  Parser --> DU
  Fetcher -->|"OSM Data"| CloudOverpass
  Fetcher -->|"DEM Data"| CloudDEM
  CloudOverpass -.-> Cache
  CloudDEM -.-> Cache
  Cache --> Fetcher
  DU --> DC
  DC --> City
  DC --> Mountain
  DC --> MultiMtn
  City --> DU
  Mountain --> DU
  MultiMtn --> DU
  DU --> Layout
  Layout --> Controller
  Controller -->|"Render Canvas"| UI
  UI -->|"Download SVG/PNG"| Main

  %% Infra Flows
  GitHubActions -->|CI/CD| Main
  DevContainer --> Main
  FlyIO --> Main

  %% Click Events
  click Controller "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/ui/"
  click Main "https://github.com/thomasparistech/pretty-gpx/blob/main/pretty_gpx/main.py"
  click Parser "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/common/gpx/"
  click Fetcher "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/common/request/"
  click DU "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/common/drawing/utils/"
  click DC "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/common/drawing/components/"
  click Layout "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/common/layout/"
  click Utils "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/common/utils/"
  click City "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/rendering_modes/city/"
  click Mountain "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/rendering_modes/mountain/"
  click MultiMtn "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/rendering_modes/multi_mountain/"
  click DevContainer "https://github.com/thomasparistech/pretty-gpx/tree/main/.devcontainer/"
  click GitHubActions "https://github.com/thomasparistech/pretty-gpx/tree/main/.github/workflows/"
  click FlyIO "https://github.com/thomasparistech/pretty-gpx/tree/main/pretty_gpx/fly/"

  %% Styles
  classDef frontend fill:#D6EAF8,stroke:#2980B9;
  classDef core fill:#D5F5E3,stroke:#27AE60;
  classDef data fill:#FCF3CF,stroke:#F1C40F;
  classDef storage fill:#AED6F1,stroke:#5499C7;
  classDef external fill:#EAEDF0,stroke:#95A5A6,stroke-dasharray:5 5;
  classDef infra fill:#F4ECF7,stroke:#8E44AD;
```
