# kcharvi/resonique architecture

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

- Interactive diagram: https://gitdiagram.com/kcharvi/resonique
- Repository: https://github.com/kcharvi/resonique

## Overview

##### Project Type and Purpose
- Resonique is a full-stack, AI-powered music discovery web application built with Streamlit (Python).
- It supports two major flows:
a. Multimodal Song Retrieval (text/image → Gemini AI → Pinecone → Spotify API)
b. Emotion-Based Audio Retrieval (local Emotify dataset → Pinecone → Supabase storage)

##### File Structure
- Top-level files:
- streamlit_app.py – Streamlit entrypoint (UI layer)
- requirements.txt, .streamlit/config.toml – dependency and config
- Directories:
- views/ – “controllers” implementing each user flow (landing_page, ingest_emotify, ingest_spotify, query_gemini, search_audio)
- utils/ – service connectors (connect.py handles Pinecone, Gemini, Spotify, Supabase)
- data/ – offline Emotify dataset and precomputed embeddings
- Dev/CI: .devcontainer/ for containerized dev environment

##### README Insights
- Tech stack: Streamlit, Google Gemini AI, Pinecone Vector DB, Supabase (storage & DB), Spotify API
- Two distinct pipelines (ingest vs. query) with embedding and vector-search at their core
- Credentials stored in .streamlit/secrets.toml

##### Main Components and Interactions
a. User Interface (Streamlit)
– Entrypoint: streamlit_app.py loads views
– Presents upload fields (image/text/emotion) and displays results (songs or audio clips)
b. Controller Layer (views/*.py)
– Landing page orchestration
– Ingestion scripts: ingest_emotify.py, ingest_spotify.py
– Query handlers: query_gemini.py (multimodal), search_audio.py (emotion)
c. Service Layer (utils/connect.py)
– Abstracts API calls and client instantiation for:
- Google Gemini (text/image embeddings)
- Pinecone (vector DB read/write)
- Spotify (track metadata)
- Supabase (audio file storage retrieval)
d. Data Stores & External Services
– Pinecone indexes (song embeddings, emotion embeddings)
– Supabase storage bucket (Emotify audio clips)
– Spotify API (playlist and track metadata)

##### Architectural Patterns & Design Principles
- Layered architecture: UI → Controllers → Services → External systems
- Separation of concerns: ingestion vs. query flows kept in separate view modules
- Dependency injection via utils/connect (single place for all external-service clients)
- Vector-search as core design principle (mpnet embeddings, cosine similarity)

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Layer
    User["User Browser"]:::ui

    %% UI Layer
    Streamlit["Streamlit App"]:::ui

    %% Controller Layer
    Landing["Landing Page"]:::controller
    IngestEmo["Emotify Ingestion"]:::controller
    IngestSpot["Spotify Ingestion"]:::controller
    QueryGem["Multimodal Query"]:::controller
    SearchAudio["Emotion Audio Search"]:::controller

    %% Service Layer
    Connect["Service Connector"]:::service

    %% External Systems
    Gemini["Google Gemini AI"]:::external
    Pinecone["Pinecone Vector DB"]:::external
    SpotifyAPI["Spotify API"]:::external
    Supabase["Supabase Storage"]:::external

    %% Data Sources
    EmotifyData["Local Emotify Dataset"]:::data
    Embeddings["Precomputed Embeddings"]:::data
    Assets["Static Assets"]:::data
    Config["Streamlit Config"]:::data
    Requirements["requirements.txt"]:::data
    DevContainer[".devcontainer/devcontainer.json"]:::data

    %% Relationships
    User --> Streamlit
    Streamlit --> Landing

    Landing --> IngestEmo
    Landing --> IngestSpot
    Landing --> QueryGem
    Landing --> SearchAudio

    IngestEmo -.->|"batch ingestion"| EmotifyData
    IngestEmo -->|"call service"| Connect
    IngestSpot -->|"call service"| Connect

    QueryGem -->|"get embedding"| Connect
    SearchAudio -->|"search vector"| Connect

    Connect -->|"text/image embedding"| Gemini
    Connect -->|"vector upsert/query"| Pinecone
    Connect -->|"fetch track metadata"| SpotifyAPI
    Connect -->|"retrieve audio files"| Supabase

    Gemini -->|embedding| Connect
    Pinecone -->|vectors| Connect
    SpotifyAPI -->|metadata| Connect
    Supabase -->|audio URLs| Connect

    QueryGem --> Streamlit
    SearchAudio --> Streamlit

    %% Click Events
    click Streamlit "https://github.com/kcharvi/resonique/blob/main/streamlit_app.py"
    click Landing "https://github.com/kcharvi/resonique/blob/main/views/landing_page.py"
    click IngestEmo "https://github.com/kcharvi/resonique/blob/main/views/ingest_emotify.py"
    click IngestSpot "https://github.com/kcharvi/resonique/blob/main/views/ingest_spotify.py"
    click QueryGem "https://github.com/kcharvi/resonique/blob/main/views/query_gemini.py"
    click SearchAudio "https://github.com/kcharvi/resonique/blob/main/views/search_audio.py"
    click Connect "https://github.com/kcharvi/resonique/blob/main/utils/connect.py"
    click EmotifyData "https://github.com/kcharvi/resonique/tree/main/data/Emotify_Dataset/"
    click Embeddings "https://github.com/kcharvi/resonique/tree/main/data/Audio_and_Text_Embeddings/"
    click Assets "https://github.com/kcharvi/resonique/tree/main/assets/"
    click Config "https://github.com/kcharvi/resonique/blob/main/.streamlit/config.toml"
    click Requirements "https://github.com/kcharvi/resonique/blob/main/requirements.txt"
    click DevContainer "https://github.com/kcharvi/resonique/blob/main/.devcontainer/devcontainer.json"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef controller fill:#E6FFEA,stroke:#28a745,color:#28a745
    classDef service fill:#E8FFF4,stroke:#2c973a,color:#2c973a
    classDef external fill:#FFEFD5,stroke:#d2691e,color:#d2691e
    classDef data fill:#F0F0F0,stroke:#6a737d,color:#6a737d
```
