# nauqh/resonance architecture

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

- Interactive diagram: https://gitdiagram.com/nauqh/resonance
- Repository: https://github.com/nauqh/resonance

## Overview

##### Main Components

a) Data Layer:
- Spotify Million Playlist Dataset Storage
- PostgreSQL Database
- Raw Data Storage (JSON/CSV files)
- Processed Data Storage

b) Backend Components:
- FastAPI Web Server
- Recommendation Engine
- Music Taste Analyzer
- Song Recommender (KNN-based)
- OpenAI LLM Integration
- Data Processing Pipeline

c) Frontend Components:
- React Application
- User Interface Components
- API Integration Layer

**┌─ User Interface Layer ─────────────────────┐**
- React Components                           │
- Music Preference Input                   │
- Playlist Integration                     │
- Results Display                         │
- ┬───────────────────────┘
- ↕
**┌─ API Layer ───────┴───────────────────────┐**
- FastAPI Endpoints                          │
- /analysis                               │
- /songs                                  │
- /artists                                │
- ┬───────────────────────┘
- ↕
**┌─ Processing Layer ┴───────────────────────┐**
- Recommendation Engine                      │
- ┌─────────────────┐    ┌────────────────┐ │
- Music Taste    │    │     Song       │ │
- Analyzer      │    │  Recommender   │ │
- ┘    └────────────────┘ │
- OpenAI LLM Integration                     │
- ┬───────────────────────┘
- ↕
**┌─ Data Layer ──────┴───────────────────────┐**
- ┌─────────────┐  ┌──────────────────────┐ │
- Raw Data   │→│    Data Pipeline      │ │
- ┘  │ - Extraction         │ │
- ┌─────────────┐  │ - Transformation     │ │
- PostgreSQL  │←│ - Loading             │ │
- ┘  └──────────────────────┘ │
- ┘

##### Important Flows to Highlight

a) Data Processing Flow:
- Spotify Million Playlist Dataset → Data Pipeline → PostgreSQL
- User Playlist → Spotify API → Feature Extraction → Recommendation Engine

b) Recommendation Flow:
- User Input → API → Recommendation Engine → Results
- Playlist Analysis → KNN Algorithm → Similar Songs

##### Additional Elements

Specific technical details in annotations:
- Python 3.10
- React/TypeScript
- FastAPI
- PostgreSQL
- Docker containers
- AWS deployment

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph UI["User Interface Layer"]
        direction TB
        RC["React Components"]
        MPI["Music Preference Input"]:::frontend
        PI["Playlist Integration"]:::frontend
        RD["Results Display"]:::frontend
        MP["Music Player"]:::frontend
    end

    subgraph API["API Layer"]
        direction TB
        FE["FastAPI Endpoints"]:::api
        AR["/artists"]:::api
        SR["/songs"]:::api
        AN["/analysis"]:::api
    end

    subgraph PL["Processing Layer"]
        direction TB
        RE["Recommendation Engine"]
        MTA["Music Taste Analyzer"]:::processing
        SRE["Song Recommender"]:::processing
        LLM["OpenAI LLM Integration"]:::external
    end

    subgraph DL["Data Layer"]
        direction TB
        RDS["Raw Data Storage"]:::storage
        PDS["Processed Data Storage"]:::storage
        PG["PostgreSQL Database"]:::database
        DP["Data Pipeline"]:::processing
        DM["Database Models"]:::database
        DS["Data Schemas"]:::database
    end

    %% Connections
    RC --> MPI
    RC --> PI
    RC --> RD
    RC --> MP

    MPI --> FE
    PI --> FE
    FE --> AR
    FE --> SR
    FE --> AN

    AR --> RE
    SR --> RE
    AN --> RE

    RE --> MTA
    RE --> SRE
    RE --> LLM

    RDS --> DP
    DP --> PDS
    DP --> PG
    PG --> DM
    DM --> DS

    %% Click Events
    click RDS "https://github.com/nauqh/resonance/tree/master/assets/data/Million Playlist Dataset/raw/"
    click PDS "https://github.com/nauqh/resonance/tree/master/assets/data/Million Playlist Dataset/processed/"
    click PG "https://github.com/nauqh/resonance/blob/master/backend/app/database.py"
    click FE "https://github.com/nauqh/resonance/blob/master/backend/app/main.py"
    click LLM "https://github.com/nauqh/resonance/blob/master/backend/src/llm.py"
    click DP "https://github.com/nauqh/resonance/blob/master/backend/src/utils/make_dataset.py"
    click RC "https://github.com/nauqh/resonance/tree/master/frontend/src/components/"
    click PI "https://github.com/nauqh/resonance/blob/master/frontend/src/api.ts"
    click RD "https://github.com/nauqh/resonance/tree/master/frontend/src/pages/"
    click MTA "https://github.com/nauqh/resonance/tree/master/assets/output/"
    click DM "https://github.com/nauqh/resonance/blob/master/backend/app/models.py"
    click AR "https://github.com/nauqh/resonance/tree/master/backend/app/routers/"
    click DS "https://github.com/nauqh/resonance/blob/master/backend/app/schemas.py"
    click MP "https://github.com/nauqh/resonance/blob/master/frontend/src/components/Playlist/Playlist.tsx"
    click MPI "https://github.com/nauqh/resonance/tree/master/frontend/src/pages/Diagnose/"

    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef api fill:#2ecc71,stroke:#27ae60,color:white
    classDef processing fill:#f1c40f,stroke:#f39c12,color:black
    classDef storage fill:#9b59b6,stroke:#8e44ad,color:white
    classDef database fill:#8e44ad,stroke:#6c3483,color:white
    classDef external fill:#e74c3c,stroke:#c0392b,color:white

    %% Legend
    subgraph Legend
        F[Frontend]:::frontend
        A[API]:::api
        P[Processing]:::processing
        S[Storage]:::storage
        D[Database]:::database
        E[External Services]:::external
    end
```
