# rdmm404/smoodi architecture

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

- Interactive diagram: https://gitdiagram.com/rdmm404/smoodi
- Repository: https://github.com/rdmm404/smoodi

## Overview

##### Main components
- Frontend: Built in React (with Vite and Tailwind CSS), it is responsible for displaying the UI and handling client-side routing (pages like HomePage, AfterLoginPage, BlendifyPage, etc.). It lives chiefly in the src/frontend directory.
- Backend: A Flask web server that handles API endpoints, authentication (OAuth 2.0), and the main business logic (e.g., playlist blending). Look into src/backend (with dedicated files for the API such as blender.py and users.py, along with error handlers and commands).
- Redis Database: Acts as a temporary data store for user tokens and session information. Its configuration and Docker setup can be found under build/dev/redis.
- Spotify API Integration: The backend calls the Spotify API using a custom client found in src/core/client/spotify (which includes models and the spotify_client). This part is responsible for interacting with Spotify’s endpoints.
- Docker and Deployment: The project uses Docker (with Dockerfiles in build/dev/ and build/prd directories) and docker-compose (docker-compose.yml) to orchestrate the containers (frontend, backend, and Redis).
- Testing components: Located in src/tests, these files ensure backend (and to some extent core functions, e.g., the Blender logic) behave as expected.

##### Relationships and interactions
- The User’s Browser communicates with the frontend React app.
- The React app sends HTTP requests (or API calls) to the Flask backend server.
- The Flask backend handles authentication with Spotify using OAuth 2.0. It then uses the custom Spotify client to invoke Spotify’s API for retrieving top tracks and other data.
- The backend also interacts with Redis to store user session tokens/data temporarily (with expiry, as mentioned in the README).
- The entire setup is containerized – with separate containers for the frontend, backend, and Redis managed by Docker Compose.
- There’s a clear data flow: User → Frontend → Backend → [Redis and Spotify API].

##### Architectural patterns and frameworks
- Separation of Concerns: The project cleanly separates frontend responsibilities (UI, routing, state management) from backend responsibilities (API endpoints, authentication, business logic).
- Microservice-like Dockerization: Each core component (frontend, backend, Redis) is containerized.
- Use of industry-standard frameworks and patterns – React (component-based architecture) and Flask (modular API design).
- OAuth 2.0 is used for secure authentication and token management.
- Testing is done using pytest for the backend.

##### Relevant technologies to incorporate
- Frontend: React, Vite, Tailwind CSS, and TypeScript (see tsconfig.json and .tsx files).
- Backend: Python (Flask), Redis (for caching session data), and associated Python modules.
- Deployment: Docker (Dockerfiles, docker-compose.yml) specifying development and production builds.
- External Integration: Spotify API and OAuth 2.0 flows.

- Use clear labels for each component and service.
- Incorporate annotations where extra clarity is needed (e.g., “OAuth 2.0 Authentication”, “Ephemeral token storage”, “Containerized via Docker”).
- Separation between development and production aspects if necessary (e.g., slow debugging mode vs. production configuration in Docker Compose and build directories).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interaction"
        U["Browser User"]:::user
    end

    subgraph "Frontend Container"
        FE["React Frontend (Vite) [Port 5001]\n(Pages, UI Components, Routing)"]:::frontend
    end

    subgraph "Backend Container"
        BE["Flask Backend [Port 5000]"]:::backend
        BE_API_Blender["API: blender.py"]:::backend
        BE_API_Users["API: users.py"]:::backend
        BE_Auth["OAuth Authentication (auth.py)"]:::backend
        BE_Commands["Commands (commands.py)"]:::backend
        BE_Error["Error Handlers (error_handlers.py)"]:::backend
        BE_Business["Business Logic (Playlist Blending)"]:::backend
    end

    subgraph "Data Storage"
        RED["Redis (Ephemeral Session Storage)"]:::redis
        RED_Docker["Dockerfile: Redis"]:::redis
        RED_Config["redis.conf"]:::redis
    end

    subgraph "External Service"
        SPOT["Spotify API & OAuth Flow"]:::external
        SPOT_Client["spotify_client.py"]:::external
        SPOT_Models["models.py"]:::external
    end

    subgraph "Orchestration"
        DOCKER_CC["docker-compose.yml"]:::docker
        DOCKER_FE["Dockerfile: Frontend"]:::docker
        DOCKER_BE["Dockerfile: Server"]:::docker
        DOCKER_RE["Dockerfile: Redis"]:::docker
        DOCKER_PR["Dockerfile: Production"]:::docker
        PROD_ENV["Production Env (.env_fe)"]:::docker
        PROD_REQ["Production Requirements (requirements.txt)"]:::docker
    end

    subgraph "Testing"
        TEST["Backend & Core Tests (pytest)"]:::test
    end

    U -->|"Accesses"| FE
    FE -->|"SendsAPICalls"| BE
    BE -->|"Calls_blender"| BE_API_Blender
    BE -->|"Calls_users"| BE_API_Users
    BE -->|"PerformsOAuth"| BE_Auth
    BE -->|"ExecutesCommands"| BE_Commands
    BE -->|"HandlesErrors"| BE_Error
    BE -->|"ExecutesBusinessLogic"| BE_Business
    BE -->|"StoresTokens"| RED
    BE -->|"CallsSpotify"| SPOT
    SPOT -->|"UsesClient"| SPOT_Client
    SPOT -->|"UsesModels"| SPOT_Models
    DOCKER_CC --> FE
    DOCKER_CC --> BE
    DOCKER_CC --> RED
    DOCKER_FE --> FE
    DOCKER_BE --> BE
    DOCKER_RE --> RED
    DOCKER_PR --> BE
    DOCKER_PR --> FE
    PROD_ENV --> DOCKER_PR
    PROD_REQ --> DOCKER_PR
    TEST --> BE

    %% Click Events
    click FE "https://github.com/rdmm404/smoodi/tree/main/src/frontend"
    click BE "https://github.com/rdmm404/smoodi/tree/main/src/backend"
    click BE_API_Blender "https://github.com/rdmm404/smoodi/blob/main/src/backend/api/blender.py"
    click BE_API_Users "https://github.com/rdmm404/smoodi/blob/main/src/backend/api/users.py"
    click BE_Auth "https://github.com/rdmm404/smoodi/blob/main/src/backend/auth.py"
    click BE_Commands "https://github.com/rdmm404/smoodi/blob/main/src/backend/commands.py"
    click BE_Error "https://github.com/rdmm404/smoodi/blob/main/src/backend/error_handlers.py"
    click RED "https://github.com/rdmm404/smoodi/tree/main/build/dev/redis"
    click RED_Docker "https://github.com/rdmm404/smoodi/tree/main/build/dev/redis/Dockerfile"
    click RED_Config "https://github.com/rdmm404/smoodi/blob/main/build/dev/redis/redis.conf"
    click SPOT "https://github.com/rdmm404/smoodi/tree/main/src/core/client/spotify"
    click SPOT_Client "https://github.com/rdmm404/smoodi/blob/main/src/core/client/spotify/spotify_client.py"
    click SPOT_Models "https://github.com/rdmm404/smoodi/blob/main/src/core/client/spotify/models.py"
    click DOCKER_CC "https://github.com/rdmm404/smoodi/blob/main/docker-compose.yml"
    click DOCKER_FE "https://github.com/rdmm404/smoodi/tree/main/build/dev/frontend/Dockerfile"
    click DOCKER_BE "https://github.com/rdmm404/smoodi/tree/main/build/dev/server/Dockerfile"
    click DOCKER_RE "https://github.com/rdmm404/smoodi/tree/main/build/dev/redis/Dockerfile"
    click DOCKER_PR "https://github.com/rdmm404/smoodi/tree/main/build/prd/Dockerfile"
    click PROD_ENV "https://github.com/rdmm404/smoodi/blob/main/build/prd/.env_fe"
    click PROD_REQ "https://github.com/rdmm404/smoodi/blob/main/build/prd/requirements.txt"
    click TEST "https://github.com/rdmm404/smoodi/tree/main/src/tests"

    %% Styling
    classDef user fill:#f9c,stroke:#333,stroke-width:2px;
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#bfb,stroke:#333,stroke-width:2px;
    classDef redis fill:#dfd,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
    classDef docker fill:#ffd,stroke:#333,stroke-width:2px;
    classDef test fill:#efe,stroke:#333,stroke-width:2px;
```
