# robiningelbrecht/statistics-for-strava architecture

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

- Interactive diagram: https://gitdiagram.com/robiningelbrecht/statistics-for-strava
- Repository: https://github.com/robiningelbrecht/statistics-for-strava

## Overview

##### Project type and purpose
- “Statistics for Strava” is a full-stack, self-hosted dashboard application built on Symfony (PHP).
- It fetches data from the Strava API, persists it locally, and renders interactive HTML pages (PWA) and badges.

##### Top-level components
- Dockerized services (docker-compose.yml):
- app (nginx + php-fpm)
- php-cli (for cron/console commands)
- database (MySQL/PostgreSQL) – not shown in the tree but implied
- Symfony application (Kernel.php, config/, src/, templates/, public/)
- Database (via Doctrine DBAL/migrations)
- CI/CD (GitHub Actions workflows)

##### Key interactions & flows
a. HTTP requests
- User browser → Nginx (docker/app) → PHP-FPM → Symfony HTTP kernel
- Controllers (AppRequestHandler, StravaOAuthRequestHandler) dispatch Query/Command via CQRS buses
- Handlers fetch data from repositories (Dbal*) or KeyValueStore, then render Twig templates → HTML/CSS/JS delivered to browser
b. Data import & site build
- Cron or manual trigger: php-cli container runs bin/console ImportStravaDataConsoleCommand → pulls from Strava API → persists via Doctrine → dispatches domain events if needed
- After import: bin/console BuildAppConsoleCommand (and other Build* commands) generate static HTML pages into a build directory → deployed under public/
c. External integrations
- Strava API (OAuth refresh, activities, segments, challenges)
- AI providers via Domain/Integration/AI (e.g., OpenAI, NeuronAI)
- Geocoding (Nominatim), Weather (OpenMeteo), Notifications (ntfy)
- Zwift (domain calculations only)

##### Architectural patterns & principles
- Layered architecture:
- Presentation: Controllers → Twig templates (templates/html, templates/svg)
- Application (Console commands + HTTP handlers) orchestrating CQRS commands/queries
- Domain: business models, command/query handlers under src/Domain
- Infrastructure: abstracted services (DBAL repositories, file system, event bus, serialization, Twig extensions) under src/Infrastructure
- CQRS: In-memory CommandBus & QueryBus decouple write vs read operations
- Dependency Injection & Symfony service container (config/services.yaml)
- Doctrine migrations for schema management

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Legend
  subgraph "Legend"
    LEG1["Frontend/UI (Green)"]:::frontend
    LEG2["Backend/Symfony & Domain (Blue)"]:::backend
    LEG3["Infrastructure (Gray)"]:::infra
    LEG4["External Services (Orange)"]:::external
  end

  %% User Browser
  Browser["User Browser\n(PWA/SPA Assets)"]:::frontend

  %% Docker Host and Services
  subgraph "Docker Host" 
    direction TB
    DockerCompose["Docker Compose"]:::infra
    subgraph "app service\n(Nginx + PHP-FPM)" 
      direction TB
      AppNginx["Nginx"]:::infra
      PHPFPM["PHP-FPM"]:::infra
      subgraph "Symfony App" 
        direction TB
        Kernel["HTTP Kernel & Bootstrapping"]:::backend
        Controllers["HTTP Controllers\n(CQRS Handlers)"]:::backend
        Buses["CommandBus & QueryBus"]:::backend
        Domain["Domain Layer"]:::backend
        Infra["Infrastructure Layer"]:::infra
        Templates["Twig Templates\n(HTML & SVG)"]:::frontend
      end
    end
    subgraph "php-cli service\n(Cron & Console)" 
      direction TB
      Cron["Cron Scheduler"]:::infra
      ConsoleCmds["Console Commands\n(Import & Build)"]:::backend
    end
    DB["Database"]:::infra
  end

  %% External APIs
  subgraph "External APIs"
    direction TB
    StravaAPI["Strava API"]:::external
    AI["AI Provider(s)"]:::external
    Geo["Geocoding (Nominatim)"]:::external
    Weather["Weather (OpenMeteo)"]:::external
    Notify["Notification (ntfy)"]:::external
  end

  %% Public Assets
  Public["Public Assets & PWA\n(build output)"]:::infra

  %% Flows - HTTP request
  Browser -->|"HTTP"| AppNginx
  AppNginx -->|"FastCGI"| PHPFPM
  PHPFPM -->|"handles"| Kernel
  Kernel -->|"dispatch(Request)"| Controllers
  Controllers -->|"QueryBus.dispatch()"| Buses
  Buses -->|"DB read"| Infra
  Infra -->|"Doctrine DBAL"| DB
  DB -->|"DB read result"| Buses
  Buses -->|"returns"| Controllers
  Controllers -->|"render"| Templates
  Templates -->|"HTML/CSS/JS"| Browser

  %% Flows - Cron & Import
  Cron -->|"cron"| ConsoleCmds
  ConsoleCmds -->|"API call"| StravaAPI
  StravaAPI -->|"data"| Domain
  Domain -->|"persist"| Infra
  Infra -->|"Doctrine"| DB

  %% Flows - Static Build
  ConsoleCmds -->|"build handlers"| Domain
  Domain -->|"generate files"| Public
  Public -->|"served via Nginx"| AppNginx

  %% External Integrations (optional)
  Infra -.->|"AI calls"| AI
  Infra -.->|"geocode"| Geo
  Infra -.->|"weather"| Weather
  Infra -.->|"notify"| Notify

  %% Click Events
  click DockerCompose "https://github.com/robiningelbrecht/statistics-for-strava/blob/master/docker-compose.yml"
  click AppNginx "https://github.com/robiningelbrecht/statistics-for-strava/tree/master/docker/app/Dockerfile"
  click Cron "https://github.com/robiningelbrecht/statistics-for-strava/tree/master/docker/php-cli/Dockerfile"
  click Kernel "https://github.com/robiningelbrecht/statistics-for-strava/blob/master/Kernel.php"
  click Controllers "https://github.com/robiningelbrecht/statistics-for-strava/blob/master/src/Controller/AppRequestHandler.php"
  click ConsoleCmds "https://github.com/robiningelbrecht/statistics-for-strava/blob/master/src/Console/ImportStravaDataConsoleCommand.php"
  click Domain "https://github.com/robiningelbrecht/statistics-for-strava/tree/master/src/Domain/"
  click Infra "https://github.com/robiningelbrecht/statistics-for-strava/tree/master/src/Infrastructure/CQRS/"
  click Templates "https://github.com/robiningelbrecht/statistics-for-strava/tree/master/templates/html/"
  click Public "https://github.com/robiningelbrecht/statistics-for-strava/blob/master/public/index.php"

  %% Styles
  classDef frontend fill:#ccffcc,stroke:#333,stroke-width:1px
  classDef backend fill:#cce5ff,stroke:#333,stroke-width:1px
  classDef infra fill:#e0e0e0,stroke:#333,stroke-width:1px
  classDef external fill:#ffe0b2,stroke:#333,stroke-width:1px
```
