🎵 ArtistCollabMap 🎵

An interactive, high-performance, and visually stunning web application that maps artist collaborations using the Spotify API and showcases relationships in a fluid, physics-based network graph.

This application has been migrated from a monolithic Flask/Dash + Plotly setup to a modern, decoupled architecture:

• Backend: Python (FastAPI) - Lightweight, asynchronous, and robust. Restructured to use Spotify Client Credentials Flow (removing browser redirects and login bottlenecks).
• Frontend: Angular (v19+) - Built using standalone components, reactive signals, and custom glassmorphism styling.
• Visualization: vis-network - Multi-node canvas visualization with real-time physics simulation (nodes bounce, avoid collisions, and can be dragged/zoomed dynamically).

---

🏗️ Project Structure

ArtistCollabMap/
├── backend/                  # FastAPI Web Server
│   ├── main.py               # REST API Endpoints & Graph structuring
│   ├── spoManager.py         # Spotify API client (Spotipy) & Local cache
│   ├── utilities.py          # Value normalization & Genre-to-color mapping
│   ├── requirements.txt      # Python dependencies
│   ├── .env.template         # Environment variables template
│   └── data/                 # Local Cache directory for Spotify responses
└── frontend/                 # Angular Standalone Single-Page App
    ├── src/app/              # Component code & styling
    │   ├── app.ts            # Component logic (signals, search, audio)
    │   ├── app.html          # Dynamic HTML (floating search, glass player)
    │   ├── app.css           # Custom neon/glass dark design system
    │   └── services/         # Angular services (Spotify REST client)
    └── package.json          # Node dependencies

---

🛠️ Getting Started

1. Spotify API Credentials Setup

To query the Spotify catalog, you need an API Client ID and Secret:

1. Go to the Spotify Developer Dashboard.
2. Log in and click Create App.
3. Name your app (e.g. ArtistCollabMap) and provide any description.
4. In the app details, copy the Client ID and Client Secret.
5. Create a .env file in the backend/ directory and fill in your keys:

   clientID=YOUR_SPOTIFY_CLIENT_ID
   clientSecret=YOUR_SPOTIFY_CLIENT_SECRET
   SPOTIFY_COUNTRY=ES

---

2. Run the FastAPI Backend

1. Navigate to the backend/ directory:

   cd backend

2. (Optional but recommended) Create and activate a Python virtual environment:

   python3 -m venv venv
   source venv/bin/activate

3. Install the required libraries:

   pip install -r requirements.txt

4. Start the FastAPI server:

   python main.py
   # or: uvicorn main:app --port 8088 --reload

   The API will be available at http://localhost:8088.

---

3. Run the Angular Frontend

1. Open a new terminal and navigate to the frontend/ directory:

   cd frontend

2. Install dependencies using pnpm (already configured):

   pnpm install

3. Start the local development server:

   pnpm run start

4. Open your browser and navigate to http://localhost:4200.

---

🚀 Key Features & Interactions

• 🔍 Smart Autocomplete Search: Search by artist name, or paste a Spotify artist URL. Results load dynamically with profile pictures and genres.
• 💫 Fluid Physics Graph: Nodes can be clicked to inspect details or dragged to organize. Double-click or click Pivot Graph Here in the sidebar to regenerate the network around the selected collaborator.
• 🔊 Hover Track Audio Previews: Move your mouse over any song card in the sidebar list to play a 30-second Spotify preview instantly. Move the mouse away to stop.
• 📻 Glowing Floating Player: An equalizer widget lights up in the corner when audio is active, displaying track title and cover art.
• 📊 Local Caching: The server saves data under backend/data/<artist_id>/ so repeated searches load instantly.