# stancld/strava-zones architecture

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

- Interactive diagram: https://gitdiagram.com/stancld/strava-zones
- Repository: https://github.com/stancld/strava-zones

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    User((User)):::user

    subgraph "Browser / Extension"
        direction TB
        Manifest["Manifest.json"]:::frontend
        Popup["Popup UI\n(popup.html,\npopup.js,\npopup.css)"]:::frontend
        Content["Content Script\n(content.js)"]:::frontend
    end

    subgraph "Backend / Server"
        direction TB
        subgraph "API Layer"
            Views["Django REST API Views\n(views.py)"]:::backend
            URLs["API URL Routing\n(urls.py)"]:::backend
            TemplateCB["Auth Callback Template\n(auth_callback.html)"]:::backend
            TemplateHR["HR Zone Display Template\n(hr_zone_display.html)"]:::backend
        end
        subgraph "Business Logic"
            Client["Strava OAuth2 & HTTP Client\n(strava_client.py)"]:::logic
            Worker["Data Sync Worker\n(worker.py)"]:::logic
            HRProc["HR Zone Processing Logic\n(hr_processing.py)"]:::logic
            Utils["Utility Functions\n(utils.py)"]:::logic
        end
        subgraph "Data Layer"
            Models["ORM Models\n(models.py)"]:::data
            Serializers["DRF Serializers\n(serializers.py)"]:::data
            Admin["Admin Config\n(admin.py)"]:::data
            Migrations["DB Migrations\n(migrations/)"]:::data
        end
        Settings["Project Settings\n(settings.py)"]:::infra
        ASGI["ASGI Launcher\n(asgi.py)"]:::infra
        WSGI["WSGI Launcher\n(wsgi.py)"]:::infra
    end

    subgraph "Database"
        DB[(PostgreSQL)]:::database
    end

    ExternalStrava[(Strava API)]:::external

    User -->|"Interacts"| Popup
    User -->|"Strava Page View"| Content

    Popup -->|"GET /api/auth/strava\nOAuth2 Redirect"| URLs
    URLs -->|"routes to"| Views
    Views -->|"OAuth2 Flow"| ExternalStrava
    ExternalStrava -->|"Callback"| TemplateCB
    TemplateCB -.->|"store tokens"| Models

    Content -->|"GET /api/strava/sync-activities"| Views
    Views -->|"calls"| Client
    Client -->|"fetch HR streams"| ExternalStrava
    Client -->|"passes data to"| HRProc
    HRProc -->|"aggregates zones"| Models

    Views -->|"reads/writes"| DB

    Content -->|"GET /api/zones?period=…\nREST-JSON"| Views
    Views -->|"serialize data"| Serializers
    Views -->|"return JSON"| Content

    Content -->|"Inject SVG/CSS"| PageDOM["Strava Page DOM"]:::frontend

    Settings --> Views
    Settings --> Client
    Settings --> Models
    ASGI --> Views
    WSGI --> Views

    Worker -->|"on-demand sync"| HRProc
    Worker -->|"uses"| Client
    Worker -->|"persists"| Models

    Tools["Shell Scripts & Tooling\n(tools/*.sh)"]:::infra
    Docker["Docker Compose & Dev\n(docker-compose.yml,\nDockerfile.dev)"]:::infra

    Tools --> Settings
    Docker --> Settings
    Docker --> DB

    click Content "https://github.com/stancld/strava-zones/blob/master/frontend/content.js"
    click Popup "https://github.com/stancld/strava-zones/blob/master/frontend/popup.html"
    click Manifest "https://github.com/stancld/strava-zones/blob/master/frontend/manifest.json"
    click Views "https://github.com/stancld/strava-zones/blob/master/backend/api/views.py"
    click URLs "https://github.com/stancld/strava-zones/blob/master/backend/api/urls.py"
    click Client "https://github.com/stancld/strava-zones/blob/master/backend/api/strava_client.py"
    click Worker "https://github.com/stancld/strava-zones/blob/master/backend/api/worker.py"
    click HRProc "https://github.com/stancld/strava-zones/blob/master/backend/api/hr_processing.py"
    click Utils "https://github.com/stancld/strava-zones/blob/master/backend/api/utils.py"
    click Models "https://github.com/stancld/strava-zones/blob/master/backend/api/models.py"
    click Serializers "https://github.com/stancld/strava-zones/blob/master/backend/api/serializers.py"
    click Admin "https://github.com/stancld/strava-zones/blob/master/backend/api/admin.py"
    click TemplateCB "https://github.com/stancld/strava-zones/blob/master/backend/api/templates/api/auth_callback.html"
    click TemplateHR "https://github.com/stancld/strava-zones/blob/master/backend/api/templates/api/hr_zone_display.html"
    click Migrations "https://github.com/stancld/strava-zones/tree/master/backend/api/migrations/"
    click Settings "https://github.com/stancld/strava-zones/blob/master/backend/strava_zones_backend/settings.py"
    click ASGI "https://github.com/stancld/strava-zones/blob/master/backend/strava_zones_backend/asgi.py"
    click WSGI "https://github.com/stancld/strava-zones/blob/master/backend/strava_zones_backend/wsgi.py"
    click Tools "https://github.com/stancld/strava-zones/tree/master/backend/tools/"
    click Docker "https://github.com/stancld/strava-zones/blob/master/docker-compose.yml"

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#98FB98,stroke:#000,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFD700,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef database fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke-dasharray: 5 5
    classDef user fill:#FFFFFF,stroke:#000,stroke-width:1px
```
