TagTune

graph TD
    subgraph DP["1. Python DSP and Ingestion Pipeline"]
        A["YT Playlist"] -->|ytmusicapi| B["prepare_metadata.py"]
        B -->|"Batch Raw Meta"| C["Gemini 3.5 Flash Tagger"]
        C -->|"Genre and Cover Metadata"| B
        B -->|"Description Regex and Search"| D["Original Song Resolver"]
        B -->|"Metadata Output"| E["songs_to_review.json"]
        E -->|"audio_pipeline.py"| F["yt-dlp Downloader"]
        F -->|"Essentia TensorFlow pb"| G["DSP Feature Extractor"]
        E -->|"Gemini Embedding API"| H["Semantic Text Embeddings"]
        G -->|"Save JSON"| I["audio_features_output.json"]
        H -->|"Save JSON"| I
        E -->|"import_to_db.py"| J[("Supabase PostgreSQL")]
        I -->|"audio_db_insert.py"| J
    end

    subgraph WA["2. Next.js 15 Web Application"]
        K["React Client UI"] -->|"1. Submit Seed URL"| L["GET /api/songs"]
        L -->|"Query Track and Genre RPC"| J
        K -->|"2. Generate Recommendations"| M["POST /api/recommend"]
        M -->|"Apply Hard Filters"| J
        M -->|"Compute Weighted Similarity"| N["Scoring Engine"]
        N -->|"Candidate JSON List"| K
        K -->|"3. Sync Playlist"| O["POST /api/playlist/push"]
        O -->|"OAuth Access Token"| P["YouTube Data API v3"]
        P -->|"Create and Populate"| Q["User YouTube Account"]
    end
                        

erDiagram
    songs {
        int song_index PK
        varchar title
        int original_song_id FK
        int artist_id FK
        int album_id FK
        int group_id FK
        int release_year
        varchar url
        varchar language
    }
    artists {
        int artist_id PK
        varchar name
    }
    groups {
        int group_id PK
        varchar name
    }
    albums {
        int album_id PK
        varchar title
        int artist_id FK
    }
    genres {
        int genre_id PK
        varchar name
        int level
    }
    song_genres {
        int song_id FK
        int primary_genre_id FK
        int sub_genre_id FK
        int micro_genre_id FK
    }
    song_audio_features {
        int song_id FK
        float tempo
        float energy
        float valence
        float danceability
        float acousticness
    }
    song_vectors {
        int song_id FK
        vector artist_vector
        vector audio_vector
    }

    songs ||--o{ song_genres : has
    songs ||--o| song_audio_features : has_features
    songs ||--o| song_vectors : has_vectors
    songs }o--|| artists : main_artist
    songs }o--|| groups : "group"
    songs }o--|| albums : album