# me-sarvar/emo_drive architecture

> Architecture diagram of the GitHub repository me-sarvar/emo_drive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/me-sarvar/emo_drive
- Repository: https://github.com/me-sarvar/emo_drive

## Overview

##### Project type and purpose
- EmoDrive is a full-stack web application. The frontend is built with Flutter (Dart) and compiled to a web app. The backend is a Flask (Python) service.
- Purpose: capture passenger facial expressions in real time, detect emotion (using OpenCV), then fetch and recommend Spotify music matching that emotion.

##### File structure
- Top level:
- README.md, LICENSE.md, .gitignore
- backend/
- ui/
- backend/ directory:
- app.py – main Flask server with REST endpoints
- opencv.py – face/emotion detection logic
- autodelete.py – cleanup script (e.g., temporary files or sessions)
- templates/ and static/ – standard Flask folder layout for any server-rendered pages (index.html, CSS)
- requirements.txt, .env – Python deps and environment variables (Spotify credentials)
- ui/ directory:
- pubspec.yaml, lib/ – Flutter app source code
- lib/main.dart – app entry point
- lib/*.dart – screens (home, Google Map, Spotify page, weather), helpers (map_helpers, logger, opencv integration)
- ui/backend/app.py and ui/backend/venv – likely a small local shim or test script (isolated Flask or proxy)
- web/ – compiled web assets (index.html, manifest)

##### Extract additional insights from README
- Tech stack: Flutter Web, Flask, Spotify API, facial recognition (OpenCV).
- Data flow described: frontend ↔ Flask ↔ Spotify.
- No persistent database is listed; state is ephemeral or held in memory/files.

a. Main components:
– Flutter Web App (client)
– Flask Backend Service (server)
– Emotion-Detection Module (OpenCV library, part of backend)
– Spotify API (external service)
– (Optional) Autodelete/Cleanup Script
b. Relationships and interactions:
1. User’s browser runs Flutter Web App.
2. Flutter captures webcam frames and sends HTTP requests (REST or WebSocket) to Flask endpoints.
3. Flask receives image data, invokes the OpenCV module to detect emotion.
4. Flask uses Spotify API (OAuth2 tokens from .env) to query or control playback, based on the detected emotion.
5. Flask returns playlist metadata or playback URLs to the Flutter app.
6. Flutter renders the recommended playlist and controls playback via embedded Spotify web player or API calls.
7. Autodelete module may periodically purge temporary files or reset sessions.
c. Architectural patterns / design principles:
– Two-tier client-server architecture
– Strict separation of concerns: UI logic in Flutter, business logic in Flask, detection logic in OpenCV
– RESTful API contract between Flutter and Flask
– Environment-driven configuration for credentials (.env)
d. Key technologies & libraries:
– Flutter / Dart (UI)
– Flask (Python web framework)
– OpenCV (emotion detection)
– Spotify Web API (recommendations, playback)
– Standard web protocols (HTTP, JSON)

##### Detail
- That every significant piece (assets, helper libraries, setup scripts) is shown if it impacts data flow or deployment.
- Environment configuration (.env) feeding into the Flask service.
- Cleanup/autodelete as either a cron job or server-side thread.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Flutter Web)"
        direction TB
        FE_Main["Main Entry (ui/lib/main.dart)"]:::frontend
        FE_Home["Home Screen (ui/lib/home.dart)"]:::frontend
        FE_Map["Google Map Screen (ui/lib/google_map_screen.dart)"]:::frontend
        FE_SpotifyUI["Spotify Page (ui/lib/spotify/spotify_page.dart)"]:::frontend
        FE_Weather["Weather Page (ui/lib/weather/weather_page.dart)"]:::frontend
        FE_MapHelper["Map Helpers (ui/lib/map_helpers.dart)"]:::frontend
        FE_Logger["Logger Utility (ui/lib/logger.dart)"]:::frontend
        FE_OpencvStub["OpenCV Integration Stub (ui/lib/opencv.dart)"]:::frontend
        FE_Assets["UI Assets (ui/assets)"]:::frontend
        FE_WebIndex["Compiled Web Host - Index (ui/web/index.html)"]:::frontend
        FE_WebManifest["Compiled Web Host - Manifest (ui/web/manifest.json)"]:::frontend
        FE_BackendShim["Local UI Backend Shim (ui/backend/app.py)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Flask Service)"
        direction TB
        BE_App["API Layer (backend/app.py)"]:::backend
        BE_Opencv["Emotion Detection Module (backend/opencv.py)"]:::backend
        BE_Env["Environment Credentials (.env)"]:::backend
        BE_Autodelete["Cleanup Service (backend/autodelete.py)"]:::backend
        BE_Template["Flask Template (backend/templates/index.html)"]:::backend
        BE_Static["Flask Static Assets (backend/static/style.css)"]:::backend
    end

    %% External Services
    SpotifyAPI["Spotify Web API"]:::external

    %% Data Flow
    FE_WebIndex -->|"loads Flutter App"| FE_Main
    FE_Main -->|"renders UI Screens"| FE_Home
    FE_Main --> FE_Map
    FE_Main --> FE_SpotifyUI
    FE_Main --> FE_Weather
    FE_Main --> FE_MapHelper
    FE_Main --> FE_Logger
    FE_Main --> FE_OpencvStub
    FE_Main -->|"uses assets"| FE_Assets

    FE_Main -->|"HTTP POST image frame"| BE_App
    BE_App -->|"calls detect_emotion()"| BE_Opencv
    BE_App -->|"reads credentials"| BE_Env
    BE_App -->|"HTTP GET playlist"| SpotifyAPI
    SpotifyAPI -->|"JSON {playlist}"| BE_App
    BE_App -->|"JSON {playlist}"| FE_Main

    BE_Autodelete -.->|"cron purge"| BE_App

    FE_BackendShim -->|"dev proxy"| BE_App

    %% Click Events
    click FE_Main "https://github.com/me-sarvar/emo_drive/blob/main/ui/lib/main.dart"
    click FE_Home "https://github.com/me-sarvar/emo_drive/blob/main/ui/lib/home.dart"
    click FE_Map "https://github.com/me-sarvar/emo_drive/blob/main/ui/lib/google_map_screen.dart"
    click FE_SpotifyUI "https://github.com/me-sarvar/emo_drive/blob/main/ui/lib/spotify/spotify_page.dart"
    click FE_Weather "https://github.com/me-sarvar/emo_drive/blob/main/ui/lib/weather/weather_page.dart"
    click FE_MapHelper "https://github.com/me-sarvar/emo_drive/blob/main/ui/lib/map_helpers.dart"
    click FE_Logger "https://github.com/me-sarvar/emo_drive/blob/main/ui/lib/logger.dart"
    click FE_OpencvStub "https://github.com/me-sarvar/emo_drive/blob/main/ui/lib/opencv.dart"
    click FE_Assets "https://github.com/me-sarvar/emo_drive/tree/main/ui/assets"
    click FE_WebIndex "https://github.com/me-sarvar/emo_drive/blob/main/ui/web/index.html"
    click FE_WebManifest "https://github.com/me-sarvar/emo_drive/blob/main/ui/web/manifest.json"
    click FE_BackendShim "https://github.com/me-sarvar/emo_drive/blob/main/ui/backend/app.py"
    click BE_App "https://github.com/me-sarvar/emo_drive/blob/main/backend/app.py"
    click BE_Opencv "https://github.com/me-sarvar/emo_drive/blob/main/backend/opencv.py"
    click BE_Env "https://github.com/me-sarvar/emo_drive/blob/main/backend/.env"
    click BE_Autodelete "https://github.com/me-sarvar/emo_drive/blob/main/backend/autodelete.py"
    click BE_Template "https://github.com/me-sarvar/emo_drive/blob/main/backend/templates/index.html"
    click BE_Static "https://github.com/me-sarvar/emo_drive/blob/main/backend/static/style.css"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
```
