mirror of https://github.com/bnair123/MusicAnalyser.git synced 2026-02-25 11:46:07 +00:00

Files

bnair123 272148c5bf feat: migrate to PostgreSQL and enhance playlist curation

- Migrate database from SQLite to PostgreSQL (100.91.248.114:5433)
- Fix playlist curation to use actual top tracks instead of AI name matching
- Add /playlists/history endpoint for historical playlist viewing
- Add Playlist Archives section to frontend with expandable history
- Add playlist-modify-* scopes to Spotify OAuth for playlist creation
- Rewrite Genius client to use official API (fixes 403 scraping blocks)
- Ensure playlists are created on Spotify before curation attempts
- Add DATABASE.md documentation for PostgreSQL schema
- Add migrations for PlaylistConfig and composition storage

2025-12-30 22:24:56 +04:00

3.3 KiB

Raw Permalink Blame History

PROJECT KNOWLEDGE BASE

Generated: 2025-12-30 Branch: main

OVERVIEW

Personal music analytics dashboard polling Spotify 24/7. Core stack: Python (FastAPI, SQLAlchemy, PostgreSQL) + React (Vite, Tailwind, AntD). Integrates AI (Gemini) for listening narratives.

STRUCTURE

.
├── backend/            # FastAPI API & Spotify polling worker
│   ├── app/            # Core logic (services, models, schemas)
│   ├── alembic/        # DB migrations
│   └── tests/          # Pytest suite
├── frontend/           # React application
│   └── src/            # Components & application logic
├── docs/               # Technical & architecture documentation
└── docker-compose.yml  # Production orchestration

WHERE TO LOOK

Task	Location	Notes
Modify API endpoints	`backend/app/main.py`	FastAPI routes
Update DB models	`backend/app/models.py`	SQLAlchemy ORM
Change polling logic	`backend/app/ingest.py`	Worker & ingestion logic
Add analysis features	`backend/app/services/stats_service.py`	Core metric computation
Update UI components	`frontend/src/components/`	React/AntD components
Adjust AI prompts	`backend/app/services/narrative_service.py`	LLM integration

CODE MAP (KEY SYMBOLS)

Symbol	Type	Location	Role
`SpotifyClient`	Class	`backend/app/services/spotify_client.py`	API wrapper & token management
`StatsService`	Class	`backend/app/services/stats_service.py`	Metric computation & report generation
`NarrativeService`	Class	`backend/app/services/narrative_service.py`	LLM (Gemini/OpenAI) integration
`ingest_recently_played`	Function	`backend/app/ingest.py`	Primary data ingestion entry
`Track`	Model	`backend/app/models.py`	Central track entity with metadata
`PlayHistory`	Model	`backend/app/models.py`	Immutable log of listening events

Module Dependencies

[run_worker.py] ───> [ingest.py] ───> [spotify_client.py]
                                  └───> [reccobeats_client.py]
[main.py] ─────────> [services/] ───> [models.py]

CONVENTIONS

Single Container Multi-Process: backend/entrypoint.sh starts worker + API (Docker anti-pattern, project-specific).
PostgreSQL Persistence: Production uses PostgreSQL on internal server (100.91.248.114:5433, database: music_db).
Deduplication: Ingestion checks (track_id, played_at) unique constraint before insert.
Frontend State: Minimal global state; primarily local component state and API fetching.

ANTI-PATTERNS (THIS PROJECT)

Manual DB Edits: Always use Alembic migrations for schema changes.
Sync in Async: Avoid blocking I/O in FastAPI routes (GeniusClient is currently synchronous).
Hardcoded IDs: Avoid hardcoding Spotify/Playlist IDs; use .env configuration.

COMMANDS

# Backend
cd backend && uvicorn app.main:app --reload
python backend/run_worker.py

# Frontend
cd frontend && npm run dev

# Tests
cd backend && pytest tests/

NOTES

Multi-arch Docker builds (amd64, arm64) automated via GHA.
ReccoBeats service used for supplemental audio features (energy, valence).
Genius API used as fallback for lyrics and artist images.

3.3 KiB Raw Permalink Blame History