Endurain

Endurain is a self‑hosted, privacy‑first fitness tracking platform that mirrors the core functionality of commercial services such as Strava while giving developers full control over data, scaling, and integration. At its heart, the application exposes a clean RESTful API built with FastAPI, allowing developers to programmatically create, read, update, and delete activities, users, and metadata. The API is documented via OpenAPI/Swagger, enabling instant SDK generation in any language that supports HTTP clients.

Technical Stack & Architecture

• Frontend: A single‑page application written in Vue.js 3, augmented with Notivue for toast notifications and styled with Bootstrap CSS. The Vue router handles client‑side navigation, while the state is managed through Pinia (Vue’s lightweight store).
• Backend: Powered by Python 3.11+ and FastAPI, the service uses SQLAlchemy ORM for database interactions, with Alembic handling schema migrations. Business logic is split into modular routers (e.g., /api/activities, /api/users) and services that encapsulate external integrations.
• External Integrations: The backend leverages stravalib and python-garminconnect to sync data from Strava and Garmin Connect respectively. File imports are supported via gpxpy, tcxreader, and fitdecode.
• Database: Supports MariaDB or PostgreSQL, chosen for their mature transaction support and scalability. Connection pooling is managed by SQLAlchemy’s pool settings, while read replicas can be added for heavy analytics workloads.
• Observability: Jaeger is integrated for distributed tracing, exposing /openapi.json and /docs endpoints that automatically propagate trace context.
• Containerization: A single Docker image is provided, with a docker‑compose.yml.example that demonstrates multi‑container deployment (app, DB, Jaeger). Environment variables drive configuration—everything from database credentials to third‑party API keys.

Core Capabilities & Developer APIs

• Activity CRUD: Create activities from raw GPX/Tcx/FIT files or via Strava/Garmin sync. Each activity exposes metrics (distance, elevation, heart‑rate), tags, and visibility flags.
• User Management: OAuth2 password flow with JWT tokens; roles (admin, user) are enforced via FastAPI dependencies.
• Webhooks: Endurain can emit events (e.g., activity.created) to external services. Developers can subscribe via a simple webhook endpoint and receive JSON payloads with optional authentication headers.
• Plugin Architecture: The backend loads extensions defined in a plugins directory. Each plugin implements a standard interface (register_routes, on_activity_import) and can be activated via environment variables, enabling custom analytics or third‑party integrations without touching core code.
• Data Export: Endpoints for CSV/JSON exports, plus a GraphQL endpoint (experimental) that allows complex queries over activities and users.

Deployment & Infrastructure

The application is designed for self‑hosting on any Linux distribution that supports Docker. For scaling, each component can be replicated: the FastAPI service behind a reverse proxy (Traefik/NGINX), a clustered PostgreSQL instance, and a Jaeger backend for high‑volume tracing. Horizontal scaling is straightforward due to statelessness of the API layer; user sessions are JWT‑based and thus cookie‑less. Backups can be automated via pg_dump or MariaDB’s mysqldump, and the database credentials are stored in Docker secrets for production deployments.

Integration & Extensibility

• REST API: Fully typed, with OpenAPI docs for auto‑generation of client libraries.
• Webhooks & Callbacks: Configure callback URLs in the admin UI; the payload includes activity metadata and optional raw files.
• Plugin System: Developers can write Python modules that register new routes or hook into activity ingestion. The plugin loader scans a designated folder and imports any modules that expose the expected interface, making it trivial to add custom analytics or export formats.
• Multi‑Tenant Support: By scoping JWT tokens to a tenant ID and adding a tenant_id column to key tables, developers can host a single instance that serves multiple isolated user groups.

Developer Experience

Configuration is driven by environment variables, with sensible defaults and clear documentation in docs/hosting-guide.md. The codebase follows PEP‑8 standards, and tests are written with pytest and httpx. The community is active on Discord and GitHub issues; contributors are encouraged to open PRs against the develop branch. Documentation is hosted at docs.endurain.com and includes a “Developer Guide” section with example payloads, authentication flows, and plugin templates.

Use Cases

• Personal Fitness Platform: A solo developer wants a private Strava‑like service for their own data.
• Corporate Wellness: An organization hosts Endurain to aggregate employee activity while keeping data on-premises.
• IoT Integration: A hobbyist builds a custom device that pushes GPX data to Endurain via