Initial MVP: full-stack music discovery app

Backend (FastAPI):
- User auth with email/password and Spotify OAuth
- Spotify playlist import with audio feature extraction
- AI recommendation engine using Claude API with taste profiling
- Save/bookmark recommendations
- Rate limiting for free tier (10 recs/day, 1 playlist)
- PostgreSQL models with Alembic migrations
- Redis-ready configuration

Frontend (React 19 + TypeScript + Vite + Tailwind):
- Landing page, auth flows (email + Spotify OAuth)
- Dashboard with stats and quick discover
- Playlist management and import from Spotify
- Discover page with custom query support
- Recommendation cards with explanations and save toggle
- Taste profile visualization
- Responsive layout with mobile navigation
- PWA-ready configuration

Infrastructure:
- Docker Compose with PostgreSQL, Redis, backend, frontend
- Environment-based configuration

backend/app/models/playlist.py

@@ -0,0 +1,28 @@
+from datetime import datetime, timezone
+
+from sqlalchemy import String, Integer, DateTime, ForeignKey, JSON, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class Playlist(Base):
+    __tablename__ = "playlists"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)
+    name: Mapped[str] = mapped_column(String(500))
+    platform_source: Mapped[str] = mapped_column(String(50))  # spotify, manual, etc.
+    external_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    track_count: Mapped[int] = mapped_column(Integer, default=0)
+    taste_profile: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    imported_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+    user: Mapped["User"] = relationship(back_populates="playlists")
+    tracks: Mapped[list["Track"]] = relationship(back_populates="playlist", cascade="all, delete-orphan")
+
+
+from app.models.user import User  # noqa: E402, F811
+from app.models.track import Track  # noqa: E402

backend/app/models/recommendation.py

@@ -0,0 +1,38 @@
+from datetime import datetime, timezone
+
+from sqlalchemy import String, Integer, Float, DateTime, ForeignKey, Text, Boolean
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class Recommendation(Base):
+    __tablename__ = "recommendations"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)
+    playlist_id: Mapped[int | None] = mapped_column(ForeignKey("playlists.id", ondelete="SET NULL"), nullable=True)
+
+    # Recommended track info
+    title: Mapped[str] = mapped_column(String(500))
+    artist: Mapped[str] = mapped_column(String(500))
+    album: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    spotify_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    preview_url: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    image_url: Mapped[str | None] = mapped_column(String(500), nullable=True)
+
+    # AI explanation
+    reason: Mapped[str] = mapped_column(Text)
+    score: Mapped[float | None] = mapped_column(Float, nullable=True)
+    query: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    # User interaction
+    saved: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+    user: Mapped["User"] = relationship(back_populates="recommendations")
+
+
+from app.models.user import User  # noqa: E402, F811

backend/app/models/track.py

@@ -0,0 +1,33 @@
+from sqlalchemy import String, Integer, Float, ForeignKey, JSON
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class Track(Base):
+    __tablename__ = "tracks"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    playlist_id: Mapped[int] = mapped_column(ForeignKey("playlists.id", ondelete="CASCADE"), index=True)
+    title: Mapped[str] = mapped_column(String(500))
+    artist: Mapped[str] = mapped_column(String(500))
+    album: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    spotify_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    isrc: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    preview_url: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    image_url: Mapped[str | None] = mapped_column(String(500), nullable=True)
+
+    # Audio features from Spotify
+    tempo: Mapped[float | None] = mapped_column(Float, nullable=True)
+    energy: Mapped[float | None] = mapped_column(Float, nullable=True)
+    danceability: Mapped[float | None] = mapped_column(Float, nullable=True)
+    valence: Mapped[float | None] = mapped_column(Float, nullable=True)
+    acousticness: Mapped[float | None] = mapped_column(Float, nullable=True)
+    instrumentalness: Mapped[float | None] = mapped_column(Float, nullable=True)
+
+    genres: Mapped[list | None] = mapped_column(JSON, nullable=True)
+
+    playlist: Mapped["Playlist"] = relationship(back_populates="tracks")
+
+
+from app.models.playlist import Playlist  # noqa: E402, F811

backend/app/models/user.py

@@ -0,0 +1,32 @@
+from datetime import datetime, timezone
+
+from sqlalchemy import String, Boolean, DateTime, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    name: Mapped[str] = mapped_column(String(255))
+    hashed_password: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    is_pro: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+    # Spotify OAuth
+    spotify_id: Mapped[str | None] = mapped_column(String(255), nullable=True, unique=True)
+    spotify_access_token: Mapped[str | None] = mapped_column(Text, nullable=True)
+    spotify_refresh_token: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    # Relationships
+    playlists: Mapped[list["Playlist"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+    recommendations: Mapped[list["Recommendation"]] = relationship(back_populates="user", cascade="all, delete-orphan")
+
+
+from app.models.playlist import Playlist  # noqa: E402
+from app.models.recommendation import Recommendation  # noqa: E402