TrackWatch Project

This skill provides expert guidance for working with TrackWatch, a full-stack application that integrates with Spotify to track favorite artists and automatically manage music releases.

Project Overview

TrackWatch connects to Spotify accounts to notify users of new releases and automatically add them to an auto-generated playlist. The application is split into a React frontend and Django REST Framework backend.

Architecture

Frontend (`/frontend`)

- `spotify/` - Direct Spotify API calls

- `trackwatch/` - Backend API calls

Backend (`/backend`)

- `app/views/` - REST API endpoints

- `app/services/` - Business logic layer (use cases)

- `app/clients/` - External API wrappers (Spotify, Resend email)

Key Features

Working with the Codebase

Running the Application

**Frontend** (in `/frontend`):

```bash

npm run dev # Start dev server on :5173

npm run build # Type check + production build

npm run lint # ESLint check

npm run preview # Preview production build

```

**Backend** (in `/backend`):

```bash

python manage.py runserver # Start dev server on :8000

python manage.py migrate # Run database migrations

python manage.py makemigrations # Create new migrations

```

API Endpoints

| Endpoint | Method | Description |

|----------|--------|-------------|

| `/ping` | GET | Health check |

| `/users/register` | POST | Register new user |

| `/users/me` | GET | Get current user |

| `/artists/follow` | POST | Follow an artist |

| `/artists/unfollow` | POST | Unfollow an artist |

| `/actions/generate` | POST | Generate artist playlist |

| `/actions/releases` | POST | Update new releases |

Authentication Flow

Database Models

Environment Variables

**Frontend**: Uses `VITE_*` prefixed variables

**Backend**: Requires:

Development Guidelines

1. **Frontend Changes**:

- Components should be in their own directories with co-located styles

- Use TypeScript for type safety

- API calls should go through service modules in `src/services/`

- Token management is centralized in `useTokenManager` hook

2. **Backend Changes**:

- Business logic belongs in `app/services/` use cases

- External API calls belong in `app/clients/`

- Views should be thin - delegate to services

- Followed artists are now managed via Spotify API (no local `UserFollowedArtist` model)

3. **Database Migrations**:

- Always run `makemigrations` after model changes

- Test migrations on dev environment before production

- Remember that User model uses Spotify ID as primary key

Recent Architecture Changes

Technology Stack

Usage Examples

Creating a New API Endpoint

1. Define the view in `backend/app/views/`

2. Create business logic in `backend/app/services/` as a use case

3. Add the route to `backend/app/urls.py`

4. Create corresponding service function in `frontend/src/services/trackwatch/`

5. Call from React components using the service function

Adding a New Spotify API Integration

1. Create or update client in `backend/app/clients/spotify/`

2. Ensure required OAuth scopes are requested during authentication

3. Use token headers: `X-Spotify-Access-Token` and `X-Spotify-Refresh-Token`

4. Handle token refresh on frontend via `useTokenManager`

Working with Followed Artists

Since followed artists are now managed via Spotify API: