How thomasparistech/pretty-gpx works
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