How runi8240/dsc-project works
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.