# runi8240/dsc-project architecture

> Architecture diagram of the GitHub repository runi8240/dsc-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/runi8240/dsc-project
- Repository: https://github.com/runi8240/dsc-project

## Overview

**TempoMind** is a **local, containerized, event-driven orchestrator** that connects:
- **Garmin BLE heart-rate telemetry** (captured on the host via Python ingestion)
- **Redis Streams** (telemetry transport / buffer)
- A **Python backend web app** (UI + REST + Socket.IO) that:
- persists to **SQLite**
- stores artifacts in **MinIO (S3-compatible object storage)**
- calls **Spotify APIs** and drives playback via **Spotify Web Playback SDK**
- A lightweight **feedback → recommender loop** (like/dislike/neutral) that updates per-user preferences and avoids repeats.

Use the file tree as your source of truth for what is deployable vs library code:

##### Host-side process (critical boundary)
- **Ingestion service**: `ingestion/ingestion_service.py`
- Reads from **Garmin BLE**
- Writes telemetry either to:
- **Redis Stream** (preferred): `REDIS_URL` + stream key `telemetry`
- Or fallback **HTTP POST /telemetry** to backend (`BACKEND_TELEMETRY_URL`)
- Optional: uploads raw telemetry snapshots to MinIO (storage mirroring)

##### Docker-compose services (network boundary)
From README + `docker-compose.yml` (even though content not shown, README describes the stack):
- **Backend container**: `backend/` (Dockerfile)
- Entry likely `backend/api_backend.py`
- HTML templates in `backend/templates/` (`index.html`, `login.html`, `signup.html`)
- Business logic modules:
- `backend/services/recommender_service.py`
- `backend/services/feedback_service.py`
- `backend/services/storage_service.py`
- Stream consumer:
- `backend/redis_consumer.py` (consumes telemetry from Redis, persists/broadcasts)
- Persistence:
- `backend/db.py` → SQLite `data/app.db`
- **Redis container**: Telemetry stream transport (`telemetry`)
- **MinIO container**: object storage for artifacts (bucket `dsc-artifacts`)
- Tracks seed CSV mirrored: `data/data.csv` ↔ object storage
- Upload endpoints: `POST /storage/upload`
- **Volumes** mounted into backend container: `./data`, `./config`, `./storage`

##### External third-party system
- **Spotify**
- Backend uses Spotify credentials from `config/spotify_credentials.txt` (client id/secret/refresh token)
- Browser UI uses **Spotify Web Playback SDK** (front-end runs as templates served by backend)

##### Backend → Socket.IO: pushes updates to connected web clients (real-time UI)

**Alternative path** (if Redis not set):
- Ingestion → Backend **HTTP POST /telemetry** → SQLite + Socket.IO

##### Backend recommendation endpoint (implied) uses
- latest telemetry (heart rate intensity)
- user profile (rest/max HR)
- seed tracks (`data/data.csv`)
- per-user preference state:
- likes snapshot features → running average “target vector”
- blacklist (never recommend again)
- session history (avoid repeats; `SESSION_HISTORY_LIMIT`)

##### Flow 3 — Artifact/storage pipeline
- Backend on boot:
- mirrors `data/data.csv` into MinIO
- if local CSV missing, downloads from MinIO
- Ingestion optionally uploads raw telemetry snapshots to MinIO (`raw-telemetry/`)
- Backend stores per-user recommendations/feedback artifacts by user id prefixes

##### Architectural patterns/design principles to highlight

- **Event-driven ingestion** via **Redis Streams** (decouples BLE sampling from backend availability and load).
- **Backend as a modular monolith**:
- Web/API layer (`api_backend.py`)
- Service layer (`services/*`)
- Persistence (`db.py`)
- Async-ish stream consumer (`redis_consumer.py`)
- **Stateful recommendation loop**:
- running preference aggregation (likes)
- safety constraints (blacklist + session history)
- **Polyglot persistence**:
- SQLite for relational operational state
- MinIO for artifact/blob style storage and reproducible datasets

##### Labels
- **Name** (e.g., “Ingestion Service”)
- **File/Module** (e.g., `ingestion/ingestion_service.py`)
- **Runtime** (Host vs Container)
- “Redis Streams: HR sample {ts, bpm, session_id?}”
- “HTTP POST /auth/login”
- “Socket.IO: telemetry_update / recommendation_update”
- “S3 PUT raw-telemetry/*”

- Use **two-way** only where it’s truly request/response (browser↔backend, backend↔Spotify APIs)

**“Dislike triggers immediate next recommendation”**
Actors: Browser → Backend API → FeedbackService → DB → RecommenderService → Spotify SDK playback.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 0 — System Context
  %% =========================
  subgraph "Level 0 — System Context"
    direction TB
    User["User (Browser)"]:::actor
    Garmin["Garmin BLE HR Device"]:::device
    Spotify["Spotify Cloud\n(Web API + Playback)"]:::external

    TempoMind["TempoMind System"]:::system
  end

  Garmin -->|"BLE:heart_rate_samples"| TempoMind
  User <-->|"HTTP:pages+REST\nSocket.IO:realtime_updates"| TempoMind
  TempoMind <-->|"SpotifyWebAPI:recommendations+control\nWebPlaybackSDK:playback"| Spotify
  User -->|"Feedback:like/dislike/neutral"| TempoMind

  %% =======================================
  %% Level 1 — Container / Deployment Diagram
  %% =======================================
  subgraph "Level 1 — Containers & Runtime Boundaries"
    direction TB

    subgraph "Host OS (BLE reliability boundary)"
      direction TB
      HostIngest["Ingestion Service\n(Host Process)"]:::service
      HostBLE["BLE Adapter / Stack"]:::device
    end

    subgraph "Docker Compose Network"
      direction TB

      subgraph "Backend Container (Python Web App)"
        direction TB
        Backend["Backend Web App\n(UI + REST + Socket.IO)"]:::service
        Consumer["Redis Stream Consumer\n(telemetry reader)"]:::service
      end

      Redis[("Redis\nStreams:telemetry")]:::datastore
      MinIO[("MinIO\nS3 bucket:dsc-artifacts")]:::datastore

      subgraph "Mounted Volumes"
        direction TB
        DataVol[("data/ (volume)")]:::volume
        SeedCSV[("Seed Dataset\n(data/data.csv)")]:::dataset
        SQLite[("SQLite\n(data/app.db)")]:::datastore
      end
    end
  end

  %% Host ingestion primary path
  HostBLE -->|"BLE:heart_rate_samples"| HostIngest
  HostIngest -->|"RedisStreams:XADD telemetry {ts,bpm,...}"| Redis
  Redis -->|"RedisStreams:XREADGROUP telemetry"| Consumer

  %% Backend persistence + realtime
  Consumer -->|"DB:insert telemetry"| SQLite
  Consumer -->|"Socket.IO:telemetry_update"| User

  %% Fallback path (no Redis)
  HostIngest -.->|"HTTPPOST:/telemetry (fallback)"| Backend
  Backend -->|"DB:insert telemetry"| SQLite
  Backend -->|"Socket.IO:telemetry_update"| User

  %% Web UI/API and feedback loop
  User <-->|"HTTP:auth+recommendation+feedback"| Backend
  Backend -->|"Socket.IO:recommendation_update"| User

  %% Storage pipeline
  Backend <-->|"S3API:mirror seed CSV + artifacts"| MinIO
  HostIngest -.->|"S3PUT:raw-telemetry/* (optional)"| MinIO
  SeedCSV <-->|"mirror to/from"| MinIO
  Backend -->|"reads/writes"| DataVol
  SQLite -->|"stored_in"| DataVol
  SeedCSV -->|"stored_in"| DataVol

  %% Spotify interactions
  Backend <-->|"SpotifyWebAPI:search/recommend/playback_control"| Spotify
  User <-->|"WebPlaybackSDK:stream/playback_state"| Spotify

  %% ==========================================
  %% Level 2 — Backend Internal Component Diagram
  %% ==========================================
  subgraph "Level 2 — Backend Components (inside Backend Container)"
    direction TB

    API["Web/API Layer\n(api_backend.py)"]:::service
    Templates["Server-rendered Templates\n(index/login/signup)"]:::ui

    subgraph "Service Layer (backend/services/)"
      direction TB
      Reco["Recommender Service\n(next-track;avoid repeats/blacklist)"]:::service
      Feedback["Feedback Service\n(like/dislike/neutral)"]:::service
      Storage["Storage Service\n(MinIO S3 client;mirroring)"]:::service
    end

    DB["Persistence Layer\n(db.py)"]:::service

    subgraph "Operational Tables (SQLite)"
      direction TB
      Tusers[("users")]:::table
      Ttelemetry[("telemetry")]:::table
      Trecs[("recommendations")]:::table
      Tfb[("feedback")]:::table
      Tlikes[("user_likes")]:::table
      Tblack[("user_blacklist")]:::table
    end
  end

  %% Internal wiring
  Backend -->|"routes_to"| API
  Backend -->|"renders"| Templates
  Consumer -->|"writes+emits via"| API

  API -->|"calls"| Reco
  API -->|"calls"| Feedback
  API -->|"calls"| Storage
  API -->|"DB ops"| DB

  Reco -->|"query telemetry+history"| DB
  Reco -->|"reads seed tracks"| SeedCSV
  Reco -->|"optional artifacts"| Storage

  Feedback -->|"record feedback\nupdate likes+blacklist"| DB
  Feedback -->|"dislike_triggers_next"| Reco

  Storage -->|"S3API"| MinIO
  Storage -->|"seed CSV mirroring"| SeedCSV

  DB -->|"SQLite CRUD"| SQLite
  DB --> Tusers
  DB --> Ttelemetry
  DB --> Trecs
  DB --> Tfb
  DB --> Tlikes
  DB --> Tblack

  Templates -->|"Spotify SDK integration\nclient playback"| User

  %% =========================
  %% Optional: developer tooling
  %% =========================
  subgraph "Appendix — Developer Tooling (non-prod)"
    direction TB
    Extra["extra/ (debug+experiments)"]:::tooling
  end

  Extra -.->|"offline experiments"| Backend

  %% =========================
  %% Click events (mapped paths)
  %% =========================
  click HostIngest "https://github.com/runi8240/dsc-project/blob/main/ingestion/ingestion_service.py"
  click Backend "https://github.com/runi8240/dsc-project/blob/main/backend/api_backend.py"
  click API "https://github.com/runi8240/dsc-project/blob/main/backend/api_backend.py"
  click Consumer "https://github.com/runi8240/dsc-project/blob/main/backend/redis_consumer.py"
  click DB "https://github.com/runi8240/dsc-project/blob/main/backend/db.py"
  click Reco "https://github.com/runi8240/dsc-project/blob/main/backend/services/recommender_service.py"
  click Feedback "https://github.com/runi8240/dsc-project/blob/main/backend/services/feedback_service.py"
  click Storage "https://github.com/runi8240/dsc-project/blob/main/backend/services/storage_service.py"
  click Templates "https://github.com/runi8240/dsc-project/blob/main/backend/templates/index.html"
  click SeedCSV "https://github.com/runi8240/dsc-project/blob/main/data/data.csv"
  click DataVol "https://github.com/runi8240/dsc-project/tree/main/data/"
  click Extra "https://github.com/runi8240/dsc-project/tree/main/extra/"

  %% Container definitions / stack definition (as nodes for clickability)
  Compose["Compose Stack Definition"]:::config
  IngestDocker["Ingestion Container Definition\n(optional)"]:::config
  BackendDocker["Backend Container Definition"]:::config

  Compose -.->|"defines"| Backend
  Compose -.->|"defines"| Redis
  Compose -.->|"defines"| MinIO
  IngestDocker -.->|"optional build"| HostIngest
  BackendDocker -.->|"builds"| Backend

  click Compose "https://github.com/runi8240/dsc-project/blob/main/docker-compose.yml"
  click IngestDocker "https://github.com/runi8240/dsc-project/tree/main/ingestion/Dockerfile"
  click BackendDocker "https://github.com/runi8240/dsc-project/tree/main/backend/Dockerfile"
  click Templates "https://github.com/runi8240/dsc-project/blob/main/backend/templates/index.html"
  click Templates "https://github.com/runi8240/dsc-project/blob/main/backend/templates/login.html"
  click Templates "https://github.com/runi8240/dsc-project/blob/main/backend/templates/signup.html"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
  classDef device fill:#FFF8E1,stroke:#F9A825,stroke-width:1.5px,color:#5D4037
  classDef external fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20
  classDef system fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1.5px,color:#4A148C
  classDef service fill:#E1F5FE,stroke:#0277BD,stroke-width:1.5px,color:#01579B
  classDef datastore fill:#FFF3E0,stroke:#EF6C00,stroke-width:1.5px,color:#E65100
  classDef table fill:#FFE0B2,stroke:#E65100,stroke-width:1.2px,color:#BF360C
  classDef ui fill:#E8EAF6,stroke:#3949AB,stroke-width:1.5px,color:#1A237E
  classDef volume fill:#FCE4EC,stroke:#AD1457,stroke-width:1.5px,color:#880E4F
  classDef dataset fill:#F1F8E9,stroke:#558B2F,stroke-width:1.5px,color:#33691E
  classDef config fill:#ECEFF1,stroke:#455A64,stroke-width:1.5px,color:#263238
  classDef tooling fill:#FAFAFA,stroke:#616161,stroke-width:1.2px,color:#212121
```
