I lowkey forgot to commit

docs/01-setup.md

@@ -0,0 +1,32 @@
+# Setup
+
+## Prerequisites
+- Docker + Docker Compose
+- Spotify Developer account (for a Client ID/Secret)
+
+## Start services
+```bash
+docker compose up -d --build
+```
+
+## Database
+```bash
+docker compose exec php php bin/console doctrine:database:create --if-not-exists
+docker compose exec php php bin/console doctrine:migrations:diff --no-interaction
+docker compose exec php php bin/console doctrine:migrations:migrate --no-interaction
+```
+
+## Admin user
+```bash
+docker compose exec php php bin/console app:promote-admin you@example.com
+```
+
+## Spotify credentials
+- Prefer admin UI: open `/admin/settings` and enter Client ID/Secret.
+- Fallback to env vars:
+```bash
+export SPOTIFY_CLIENT_ID=your_client_id
+export SPOTIFY_CLIENT_SECRET=your_client_secret
+```
+
+

docs/02-features.md

@@ -0,0 +1,14 @@
+# Features
+
+- Spotify album search with Advanced filters (album, artist, year range)
+- Album page with details, list of reviews, and inline new review
+- Review rating slider (1–10) with live badge
+- Per-album aggregates: average rating and total review count
+- Auth modal (Login/Sign up) with remember-me cookie
+- Role-based access (author vs admin)
+- Admin Site Settings to manage Spotify credentials
+- User Dashboard for profile changes (email, display name, password)
+- Light/Dark theme toggle (cookie-backed)
+- Bootstrap UI
+
+

docs/03-auth-and-users.md

@@ -0,0 +1,19 @@
+# Authentication & Users
+
+## Modal auth
+- Login and registration happen in a Bootstrap modal.
+- AJAX submits keep users on the same page; state updates after reload.
+- Remember-me cookie keeps users logged in across sessions.
+
+## Roles
+- `ROLE_USER`: default for registered users.
+- `ROLE_ADMIN`: promoted via console `app:promote-admin`.
+
+## Password changes
+- On `/dashboard`, users can change email/display name.
+- To set a new password, the current password must be provided.
+
+## Logout
+- `/logout` (link in user menu).
+
+

docs/04-spotify-integration.md

@@ -0,0 +1,19 @@
+# Spotify Integration
+
+## Credentials
+- Prefer configuring via `/admin/settings` (stored in DB).
+- Fallback to environment variables `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`.
+
+## API client
+- `src/Service/SpotifyClient.php`
+  - Client Credentials token fetch (cached)
+  - `searchAlbums(q, limit)`
+  - `getAlbum(id)` and `getAlbums([ids])`
+  - Centralized request pipeline: throttling, 429 backoff, response caching
+
+## Advanced search
+- The search page builds Spotify fielded queries:
+  - `album:"..."`, `artist:"..."`, `year:YYYY` or `year:YYYY-YYYY`
+  - Optional free-text added to the query
+
+

docs/05-reviews-and-albums.md

@@ -0,0 +1,16 @@
+# Reviews & Albums
+
+## Album page
+- Shows album artwork, metadata, average rating and review count.
+- Lists reviews newest-first.
+- Logged-in users can submit a review inline.
+
+## Permissions
+- Anyone can view.
+- Authors can edit/delete their own reviews.
+- Admins can edit/delete any review.
+
+## UI
+- Rating uses a slider (1–10) with ticks; badge shows current value.
+
+

docs/06-admin-and-settings.md

@@ -0,0 +1,17 @@
+# Admin & Settings
+
+## Site settings (ROLE_ADMIN)
+- URL: `/admin/settings`
+- Manage Spotify credentials stored in DB.
+
+## User management
+- Promote an admin:
+```bash
+docker compose exec php php bin/console app:promote-admin user@example.com
+```
+
+## Appearance
+- `/settings` provides a dark/light mode toggle.
+- Preference saved in a cookie; applied via `data-bs-theme`.
+
+

docs/07-rate-limits-and-caching.md

@@ -0,0 +1,23 @@
+# Rate Limits & Caching
+
+## Throttling
+- Requests are throttled per window (default 30s) to avoid bursts.
+- Separate caps for sensitive endpoints.
+- Configure via env:
+```bash
+SPOTIFY_RATE_WINDOW_SECONDS=30
+SPOTIFY_RATE_MAX_REQUESTS=50
+SPOTIFY_RATE_MAX_REQUESTS_SENSITIVE=20
+```
+
+## 429 handling
+- If Spotify returns 429, respects `Retry-After` and retries (up to 3 attempts).
+
+## Response caching
+- GET responses cached: search ~10 minutes, album ~1 hour.
+- Token responses are cached separately.
+
+## Batching
+- `getAlbums([ids])` provided for batch lookups.
+
+

docs/08-troubleshooting.md

@@ -0,0 +1,19 @@
+# Troubleshooting
+
+## Cannot find template or routes
+- Clear cache: `docker compose exec php php bin/console cache:clear`
+- List routes: `docker compose exec php php bin/console debug:router`
+
+## Missing vendors
+- Install: `docker compose exec php composer install --no-interaction --prefer-dist`
+
+## .env not read in container
+- Ensure we mount `.env` or set env vars in compose; we mount `.env` in `docker-compose.yml`.
+
+## Login modal shows blank
+- Make sure Bootstrap JS loads before the modal script (handled in `base.html.twig`).
+
+## Rate limits / 429
+- Client backs off using `Retry-After`. Reduce concurrent requests; increase window env vars if needed.
+
+