How stancld/strava-zones works
Project type and purpose
• This is a full-stack web-based enhancement: a Chrome Extension (“frontend”) that augments the Strava web UI, paired with a Django/Django REST Framework backend (“backend”) for authentication, data processing, and storage.
• Goal: surface weekly/monthly heart-rate zone summaries on the Strava Training Calendar by fetching raw activity data from Strava’s API, aggregating time-in-zone, then injecting a visualization into the browser.
File structure
• Top-level:
• backend/ – Django project (“strava_zones_backend”), REST API endpoints in api/
• frontend/ – Chrome Extension assets (HTML, JS, CSS, manifest.json)
• docker-compose.yml – orchestration for local dev (likely PostgreSQL + Django)
• data/ – sample JSON for testing
• .github/, CI workflows
• backend/api/ –
• admin.py, models.py, serializers.py, views.py → standard DRF MVC layers
• urls.py → endpoint routing
• strava_client.py → Strava HTTP client, encapsulates OAuth/REST calls
• worker.py & utilities → background processing or synchronous “sync-activities” logic
• backend/strava_zones_backend/ – Django settings, ASGI/WSGI launchers
• backend/tools/ – shell scripts for bootstrapping, database seeding, HTTPS server, etc.
Key architectural insights from README
• OAuth2 flow: extension triggers login → backend /api/auth/strava/ → Strava → /api/auth/strava/callback/
• Data sync: /api/strava/sync-activities/ fetches raw HR streams, processes zones
• Data storage: PostgreSQL holds users, custom HR-zone configs, aggregated summaries
• Extension‐to‐backend: REST endpoints under /api/…, returns JSON or HTML snippets
• Visualization: extension injects HTML/CSS (popup.html or calendar overlay)
Main components & interactions (
a. Chrome Extension (Content Script & Popup)
• Detects the Strava calendar view
• Makes HTTP(S) requests to your Django API
• Injects SVG/HTML summaries into the page
b. Django REST API
• REST controllers (views.py)
• Business logic: strava_client, worker, utils
• ORM models for users, zones, summaries
• Templates for HTML endpoints (hr_zone_display)
c. PostgreSQL Database
• Persistent storage of users, OAuth tokens, HR zone definitions, aggregated metrics
d. External Strava API
• OAuth2 endpoints (authorization, token exchange)
• Data endpoints (activity streams, user profile)
Relationships & data flow
1. User clicks “Authorize” in extension → extension opens /api/auth/strava/
2. User authenticates with Strava → Strava redirects to /api/auth/strava/callback/ → backend stores tokens
3. Extension calls /api/strava/sync-activities/ → backend fetches raw HR streams from Strava → aggregates time-in-zone → saves to DB
4. Extension calls /api/zones/?period=… → backend reads aggregated data from DB → returns JSON
Architectural patterns & principles
• Client-Server (separation of concerns: UI vs. business logic & data)
• MVC on the backend (Django’s views/models/templates)
• RESTful API design
• OAuth2 for authentication/authorization
• Asynchronous or scheduled sync (worker.py can be invoked by CRON or on‐demand)
• Configurable via shell scripts and Docker for reproducible dev environments