Statistics for Strava

Statistics for Strava is a self‑hosted analytics platform that ingests data from the Strava API and presents it through an interactive, feature‑rich dashboard. From a developer’s standpoint, the application is designed to be modular, container‑friendly, and easily extensible. The core goal is to expose Strava’s raw telemetry—activities, gear, segments, and more—in a way that can be queried programmatically, visualized on the web, or integrated into third‑party services.

Key Features

• Granular Data Aggregation: Pulls raw activity, gear, and segment data via OAuth‑protected endpoints, normalizes timestamps, and stores them in a relational schema optimized for analytical queries.
• Custom Gear & Maintenance: Allows users to define custom gear setups and track maintenance schedules. These are stored as JSON blobs in the database, enabling flexible querying without schema changes.
• Heatmaps & Calendar Views: Utilizes GeoJSON and time‑series data to render heat maps in the browser, leveraging WebGL for performance.
• AI Workout Assistant: Exposes a lightweight inference endpoint that consumes historical performance metrics and returns personalized training suggestions, built on top of a pre‑trained model hosted within the same container.
• PWA & Badge Generation: Generates embeddable SVG badges and serves the app as a Progressive Web App, allowing offline access and native‑app feel on mobile.

Technical Stack

• Language & Framework: The backend is written in Go, chosen for its concurrency model and static binaries, which simplify containerization. The web front end uses React with Vite for fast dev cycles and tree‑shaking.
• Database: A PostgreSQL 15 instance stores structured data; optional Redis is used for caching OAuth tokens and rate‑limit counters.
• Containerization: A single Docker image (robiningelbrecht/strava-statistics) contains the Go binary, Node runtime for building assets, and a lightweight Nginx reverse proxy. The image size is under 200 MB, facilitating quick deployments on Docker‑based hosts.
• CI/CD: GitHub Actions run unit tests, linting, and build the Docker image on every push. The CI badge in the README reflects this pipeline.

Architecture

The application follows a micro‑service‑within‑a‑container pattern. The Go service exposes two main HTTP endpoints:

1. API Gateway (/api/*) – Handles authentication, data ingestion jobs, and serves the RESTful API for external consumers.
2. Static Asset Server – Serves the React SPA, which consumes the API via fetch.

Data ingestion is triggered by a scheduled job (cron‑like) that calls Strava’s /athlete/activities endpoint, paginates results, and writes them to PostgreSQL. The job can be paused or resumed via the admin UI, providing fine‑grained control over API usage.

Deployment & Infrastructure

• Self‑hosting: The application can run on any host that supports Docker, including bare metal, VMs, or cloud providers. A single docker-compose.yml file exposes the database, Redis (optional), and application services.
• Scalability: For high‑volume athletes, the ingestion layer can be horizontally scaled by running multiple worker containers behind a load balancer; each worker uses a unique OAuth token to avoid rate limits.
• Observability: Integration with Prometheus metrics and optional OpenTelemetry tracing (via Blackfire) allows developers to monitor query latency, ingestion throughput, and error rates.

Integration & Extensibility

Developers can extend the platform in several ways:

• Plugin System: A simple Go plugin API lets third‑party modules register new endpoints or background jobs. The core exposes a RegisterPlugin hook that accepts HTTP handlers and cron expressions.
• Webhooks: The API can emit events (e.g., new activity added) to external services via configurable webhook URLs.
• Custom Dashboards: The React front end is built with a component registry, enabling developers to drop in custom visualizations that consume the public API.

Developer Experience

The project’s documentation is hosted on a dedicated site (statistics-for-strava-docs.robiningelbrecht.be) and includes sections for configuration, custom gear, maintenance tracking, and API reference. The codebase follows idiomatic Go conventions, with clear module boundaries (pkg/api, pkg/ingest, pkg/ui). Community support is active on Discord, where contributors can ask questions and propose features. The open‑source license (MIT) removes any commercial barriers, making it attractive for both hobbyists and enterprise teams.

Use Cases

• Personal Analytics: Athletes who want a deeper dive into their Strava data without relying on the official dashboard.
• Coaching Platforms: Coaches can host the service for clients, pulling in activity data and generating custom training plans via the AI assistant.
• Event Organizers: Clubs can embed badge generators on their websites, allowing members to showcase achievements.
• Research Projects: Data scientists can export the PostgreSQL schema and run custom analyses on activity patterns or gear usage.

Advantages

• Performance: Go’s lightweight concurrency and PostgreSQL’s indexing make data queries fast even with thousands of activities.
• Flexibility: The plugin architecture and JSON‑based gear configurations let developers tailor the app to niche requirements without touching core code