first commit

docs/PROGRESS.md

@@ -0,0 +1,414 @@
+# Implementation Progress — Desi Clans
+
+**Last updated:** 2026-04-04 (Phase 13 visual refinement)
+
+This file tracks delivery against [ARCHITECTURE.md](./ARCHITECTURE.md) phases.
+
+---
+
+## Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| ✅ | Done |
+| 🟡 | Partial |
+| ⬜ | Not started |
+
+---
+
+## Phase 0 — Constitution
+
+| Item | Status | Notes |
+|------|--------|-------|
+| PRD.md | ✅ | v1.0 |
+| ARCHITECTURE.md | ✅ | v1.0 |
+| DESIGN_SYSTEM.md | ✅ | v1.0 |
+| API_SPEC.md | ✅ | v1.0 |
+| DATABASE.md | ✅ | v1.0 |
+| PROGRESS.md | ✅ | This file |
+| README.md | ✅ | Root readme |
+
+---
+
+## Phase 1a — Project foundation
+
+### Monorepo & tooling
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Root `.gitignore` | ✅ | Node, Python, env, uploads |
+| `docker-compose.yml` | ✅ | PostgreSQL 16 for local dev |
+| Dev scripts (`scripts/*.ps1`, `*.sh`) | ✅ | Backend + frontend |
+| Root README setup | ✅ | Quick start |
+
+### Backend foundation
+
+| Item | Status | Notes |
+|------|--------|-------|
+| FastAPI app entry | ✅ | CORS, optional `/media` mount |
+| `app/config.py` (Pydantic Settings) | ✅ | `.env` driven |
+| `app/database.py` | ✅ | SQLAlchemy engine + session |
+| `app/storage.py` | ✅ | Local + S3 backends |
+| `requirements.txt` | ✅ | Pinned ranges |
+| `backend/.env.example` | ✅ | Documented variables |
+| `backend/README.md` | ✅ | Setup + scripts |
+| Alembic + migrations | ✅ | Existing revisions (models in repo) |
+| Health endpoint only in `main` | ✅ | `GET /api/public/health` |
+| `tests/test_health.py` | ✅ | FastAPI TestClient |
+| `create_all` removed from `main` | ✅ | Use Alembic for schema |
+
+### Frontend foundation
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Vite + React (JSX) | ✅ | `frontend/` |
+| Tailwind CSS v3 | ✅ | Design tokens in config |
+| React Router | ✅ | Home + 404, `AppLayout` |
+| Axios client | ✅ | `src/api/client.js` |
+| GSAP setup | ✅ | `src/animations/gsap.js` + hero fade |
+| Lucide React | ✅ | Home page icon |
+| Folder structure | ✅ | api, components, hooks, layouts, pages, styles, utils, animations |
+| `frontend/.env.example` | ✅ | `VITE_API_URL` |
+| Vite dev proxy `/api` | ✅ | `vite.config.js` |
+| `frontend/README.md` | ✅ | |
+
+### Business features (deferred — next step)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Mount public/admin/auth routers | ⬜ | Code exists under `app/routers/` |
+| Public event pages (UI) | ⬜ | |
+| Admin dashboard (UI) | ⬜ | |
+| Wire Axios to editions API | ⬜ | |
+
+---
+
+## Phase 1b — Public site + admin content
+
+### Backend (routers to enable)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| JWT admin auth | 🟡 | `app/auth.py` + `routers/auth.py` |
+| Public editions API | 🟡 | `routers/public.py` |
+| Admin CRUD + media | 🟡 | `routers/admin.py` |
+| Analytics, share, subscribers | 🟡 | Routers present, not mounted |
+
+### Frontend
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Events list + detail pages | ⬜ | |
+| Admin dashboard UI | ⬜ | |
+| SEO meta per route | 🟡 | Default in `index.html` only |
+
+### DevOps
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Docker backend image | 🟡 | `backend/Dockerfile` |
+| CI lint/test | ⬜ | |
+
+---
+
+## Phase 2 — Design system (UI primitives)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Tailwind tokens (color, type, spacing, radius, shadow) | ✅ | `tailwind.config.js` |
+| Typography components (`Heading`, `Text`, `Eyebrow`) | ✅ | Fluid display scale |
+| `Button`, `Badge`, `Card`, `Container` | ✅ | `src/components/ui/` |
+| `Section`, `SectionHeader`, `SectionSplit` | ✅ | Editorial layouts |
+| `Navbar`, `NavLink`, `SiteFooter` | ✅ | Mobile menu + sticky header |
+| `EventCard` | ✅ | Image-led, minimal radius |
+| `Skeleton`, `Spinner`, `EmptyState` | ✅ | Loading & empty patterns |
+| Barrel exports | ✅ | `src/components/index.js` |
+| Showcase route `/system` | ✅ | Responsive verification + breakpoint hook |
+| `npm run build` | ✅ | Verified |
+
+---
+
+## Phase 3 — Public homepage (mock data)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| `MarketingLayout` + overlay nav | ✅ | Scroll-solid header, anchor links |
+| Cinematic `HomeHero` | ✅ | Full-viewport, parallax image, GSAP entrance |
+| Upcoming events + `EventCard` grid | ✅ | `src/data/homeMock.js` |
+| Featured edition section | ✅ | Editorial split layout |
+| Cultural categories | ✅ | Image tiles, ink section |
+| Bengaluru venues list | ✅ | `#venues` |
+| Immersive gallery | ✅ | Horizontal snap mobile, grid desktop |
+| Brand story | ✅ | `SectionSplit` + pull quote |
+| Final CTA + mock subscribe form | ✅ | No API |
+| Premium `MarketingFooter` | ✅ | |
+| GSAP ScrollTrigger reveals | ✅ | `useHomeScrollAnimations`, gallery stagger |
+| `prefers-reduced-motion` | ✅ | Animations skipped |
+| `overflow-x-hidden` / responsive gutters | ✅ | |
+| `npm run build` | ✅ | |
+
+**Not in scope:** backend API, ticketing, auth.
+
+---
+
+## Phase 4 — Event details (mock data)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Route `/events/:slug` | ✅ | `EventDetailsPage` |
+| Mock catalog `eventsMock.js` + `getEventBySlug` | ✅ | 5 editions incl. long title / no cover |
+| Reusable `components/event/*` sections (10 blocks) | ✅ | Hero → CTA |
+| Invalid slug empty state | ✅ | Tested `/events/does-not-exist` |
+| Homepage cards → event routes | ✅ | `EventCard` `to` prop |
+| Mobile sticky ticket bar | ✅ | Hidden `lg+` |
+| Document title per edition | ✅ | `useDocumentTitle` |
+| Payments / checkout | ⬜ | Deferred |
+| API-driven editions | ⬜ | Replace mock |
+
+---
+
+## Phase 5 — FastAPI backend foundation
+
+| Item | Status | Notes |
+|------|--------|-------|
+| `app/core/` config, deps, errors | ✅ | Pydantic Settings, DI, handlers |
+| `app/db/` session + Base | ✅ | PostgreSQL via `DATABASE_URL` |
+| `app/models/` package | ✅ | Entities for Alembic |
+| `app/schemas/` package | ✅ | `HealthResponse` + domain schemas |
+| `app/api/routes/health.py` | ✅ | `GET /api/health` + DB ping |
+| `app/main.py` factory | ✅ | CORS, static media, router mount |
+| Legacy `app/routers/` | 🟡 | Not mounted yet |
+| `pytest` health test | ✅ | 200 or 503 with DB fields |
+| API_SPEC.md | ✅ | `/api/health` documented |
+
+---
+
+## Phase 6 — Event & venue data layer
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Models: `Venue`, `Event`, `EventMedia`, `TicketType` | ✅ | `app/models/catalog.py` |
+| Alembic `20260404_0005` | ✅ | FKs, indexes, enums |
+| `GET /api/events` + filters | ✅ | category, status, upcoming |
+| `GET /api/events/{slug}` | ✅ | Detail + media + tickets |
+| `GET /api/venues`, `/api/venues/{id}` | ✅ | |
+| Pydantic `schemas/catalog.py` | ✅ | |
+| `scripts/seed_catalog.py` | ✅ | Holi, Garba, Dandiya |
+| API tests `test_catalog_api.py` | ✅ | 8 pytest total passing |
+| DATABASE.md / API_SPEC.md | ✅ | |
+| Frontend wired to API | ✅ | Phase 7 — see below |
+
+---
+
+## Phase 7 — Frontend API integration
+
+| Item | Status | Notes |
+|------|--------|-------|
+| `src/services/api.js` | ✅ | Axios client, `ApiError`, health |
+| `src/services/events.js` | ✅ | List, slug, view mappers |
+| `src/services/venues.js` | ✅ | List + row mapper |
+| `useAsyncQuery` + domain hooks | ✅ | `useEventsList`, `useEventDetail`, `useVenuesList` |
+| Homepage → events + venues API | ✅ | Loading / error / empty / retry |
+| Event details → slug API | ✅ | 404 empty, error retry |
+| Presentation vs data separation | ✅ | Sections receive props; no fetch in UI |
+| `RequestState` / skeletons | ✅ | Shared loading & error UI |
+| Vitest service tests | ✅ | Success, network, empty, 404 slug |
+| `npm run build` | ✅ | Production bundle |
+| Static hero/brand/categories | 🟡 | Still `homeMock.js` (non-catalog) |
+
+---
+
+## Phase 8 — Authentication
+
+| Item | Status | Notes |
+|------|--------|-------|
+| `User` model + Alembic `20260404_0006` | ✅ | `users` table, bcrypt hashes only |
+| `POST /api/auth/register` | ✅ | Validation, 409 on duplicate |
+| `POST /api/auth/login` | ✅ | JWT `type: user` |
+| `GET /api/auth/me` | ✅ | `CurrentUser` dependency |
+| `app/core/security.py` | ✅ | Hash, verify, encode/decode JWT |
+| Config: `SECRET_KEY`, token TTL | ✅ | Production strength checks |
+| Frontend `services/auth.js` + `token.js` | ✅ | Bearer interceptor on API client |
+| `AuthProvider` + `useAuth` | ✅ | Bootstrap via `/me` |
+| Login / register / account pages | ✅ | Marketing layout |
+| `ProtectedRoute` (`/account`) | ✅ | Redirect to `/login` |
+| Navbar sign in / sign out | ✅ | |
+| Backend tests `test_auth`, `test_security` | ✅ | |
+| Frontend vitest `auth.test.js` | ✅ | |
+| Admin RBAC | ⬜ | Deferred — legacy routers not mounted |
+
+---
+
+## Phase 9 — Ticket inventory & orders
+
+| Item | Status | Notes |
+|------|--------|-------|
+| `Order`, `OrderItem`, `Ticket` + migration `0007` | ✅ | Inventory reservation, unique codes |
+| Catalog `TicketType` inventory | ✅ | `FOR UPDATE`, oversell checks |
+| `GET /api/events/{id}/tickets` | ✅ | |
+| `POST /api/orders`, `GET` order/tickets | ✅ | Server-side pricing |
+| Concurrency tests | ✅ | `test_orders.py` |
+
+---
+
+## Phase 10 — Payment integration
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Razorpay server SDK + env secrets | ✅ | `razorpay` package |
+| `PAYMENT_PROVIDER` mock / razorpay | ✅ | Mock for local & CI |
+| Pending order → verified `paid` | ✅ | Tickets issued after confirm |
+| `POST …/payment/verify` | ✅ | Signature verification |
+| Webhooks + idempotency table | ✅ | `0008`, duplicate safe |
+| Cancel / timeout / failed payment | ✅ | Inventory release |
+| `Idempotency-Key` on checkout | ✅ | |
+| Frontend checkout (no secrets) | ✅ | `useCheckout`, Razorpay.js |
+| Tests `test_payments.py` | ✅ | verify, webhook, cancel |
+| Garba category image fix | ✅ | `homeMock` + seed alt media |
+
+---
+
+## Phase 12 — Admin dashboard
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Admin JWT (`type: admin`) separate from attendees | ✅ | `decode_admin_access_token` |
+| `POST /api/admin/auth/login`, `GET /api/admin/auth/me` | ✅ | |
+| RBAC `editor` / `super_admin` deps | ✅ | `EditorAdmin`, `SuperAdmin` |
+| Dashboard metrics API | ✅ | Revenue, tickets, orders, attendance |
+| Events / venues / ticket types CRUD | ✅ | Admin catalog services |
+| Orders & payments lists | ✅ | |
+| Admin ticket verify | ✅ | Reuses gate logic |
+| Event statistics | ✅ | Per-event breakdown |
+| Admin SPA `/admin/*` | ✅ | Tables, forms, filters |
+| `scripts/seed_admin.py` | ✅ | |
+| `test_admin_api.py` | ✅ | Attendee blocked |
+
+---
+
+## Phase 11 — Digital tickets
+
+| Item | Status | Notes |
+|------|--------|-------|
+| `qr_token` + QR PNG generation | ✅ | Issued on payment; migration `0009` |
+| `GET /api/tickets/{id}` detail | ✅ | Owner-only digital pass |
+| `POST /api/tickets/verify` | ✅ | Check-in key, atomic `used` |
+| Ticket states `valid` / `used` / `cancelled` | ✅ | Renamed from `redeemed` |
+| React `DigitalTicket` + `/tickets/:id` | ✅ | Branding, QR, metadata |
+| Account ticket list | ✅ | Links to pass |
+| Tests `test_digital_tickets.py` | ✅ | QR detail + reuse prevention |
+
+---
+
+## Phase 15 — Security audit
+
+| Item | Status | Notes |
+|------|--------|-------|
+| `docs/SECURITY.md` | ✅ | Assumptions, controls, prod checklist |
+| Production settings validation | ✅ | Gate key, Razorpay, CORS, admin password |
+| Mock webhook gated to development | ✅ | |
+| Admin verify requires gate key | ✅ | Constant-time key compare |
+| Auth rate limits (in-process) | ✅ | login/register/verify/payment |
+| Login password min length aligned | ✅ | 8 chars attendee + admin |
+
+---
+
+## Phase 14 — Production performance audit
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Route code splitting (marketing, admin, auth) | ✅ | `App.jsx` lazy routes |
+| Dynamic GSAP load | ✅ | `loadGsap.js` |
+| API cache + deferred featured detail | ✅ | `queryCache.js`, idle fetch |
+| Responsive Unsplash `srcSet` | ✅ | `utils/mediaUrl.js` |
+| Navbar scroll rAF throttle | ✅ | |
+| `docs/PERFORMANCE.md` | ✅ | Audit + targets |
+
+---
+
+## Phase 13b — Hero WebGL atmosphere (single 3D touchpoint)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Home hero festival dust (Three.js) | ✅ | `src/webgl/hero-atmosphere/` only |
+| Lazy load + idle defer | ✅ | `React.lazy`, `requestIdleCallback`, separate chunk |
+| Desktop / WebGL / reduced-motion gates | ✅ | `eligibility.js` + vitest |
+| Mobile & no-WebGL fallback | ✅ | Layer not mounted; hero unchanged |
+| Offscreen pause (IntersectionObserver) | ✅ | Stops rAF when hero scrolls away |
+
+---
+
+## Phase 13 — Visual refinement (public site)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Typography, spacing, cards (`rounded-2xl`, shadows) | ✅ | Buttons, `EventCard`, tiers, ticket pass |
+| Nav / hover / section rhythm | ✅ | Editorial nav underline, fade into content |
+| GSAP: home stagger groups + event detail reveals | ✅ | `useEventDetailAnimations`, parallax heroes |
+| `prefers-reduced-motion` CSS + GSAP guards | ✅ | `index.css`, hooks skip motion |
+| Image cropping (`object` focal) + `sizes` | ✅ | Hero, gallery, cards |
+| Vite chunk split (GSAP) | ✅ | `manualChunks` |
+| Lighthouse pass (local preview) | 🟡 | Home perf ~86, a11y 96 (preview build); LCP tuned via hero preload + no opacity-hiding H1 |
+
+---
+
+## Phase 2b — Polish & performance
+
+| Item | Status |
+|------|--------|
+| GSAP ScrollTrigger sections | ✅ | Phase 13 |
+| `prefers-reduced-motion` (beyond GSAP init) | ✅ | Phase 13 |
+| Image lazy load on real event pages | ✅ | Lazy below fold; hero `fetchPriority` |
+| Accessibility audit (WCAG AA) | ⬜ |
+| Lighthouse performance pass | 🟡 | Chunking + LCP hints; audit ongoing |
+
+---
+
+## Phase 3 — Native ticketing
+
+| Item | Status |
+|------|--------|
+| DB: ticket_tiers, orders, tickets | ✅ | Phase 9 |
+| Attendee users + auth | ✅ | Phase 8 |
+| Checkout + payment webhook | ✅ | Phase 10 |
+| QR generation + ticket page | ✅ | Phase 11 |
+| Staff check-in API + UI | ⬜ |
+| Email ticket delivery | ⬜ |
+
+---
+
+## Phase 4 — Hardening
+
+| Item | Status |
+|------|--------|
+| E2E tests (critical paths) | ⬜ |
+| Rate limiting / WAF | ⬜ |
+| Production CDN for media | ⬜ |
+| Runbooks + monitoring | ⬜ |
+
+---
+
+## Current focus (recommended)
+
+1. Mount existing API routers in `app/main.py` and verify against PostgreSQL.  
+2. Add admin SPA routes and auth token handling.  
+3. GSAP polish, a11y audit, Lighthouse pass (Phase 2b).
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-04-04 | Initial constitution docs |
+| 2026-04-04 | Phase 1a foundation: frontend scaffold, backend config/database/storage, health API, docker-compose, dev scripts |
+| 2026-04-04 | Phase 2 design system: Tailwind tokens, React primitives, `/system` showcase |
+| 2026-04-04 | Phase 3 public homepage: mock data, marketing sections, GSAP motion |
+| 2026-04-04 | Phase 4 event details: `/events/:slug`, reusable sections, mock catalog |
+| 2026-04-04 | Phase 5 backend: layered app layout, `/api/health`, PostgreSQL check |
+| 2026-04-04 | Phase 6 catalog: venues/events/media/tickets API + seed |
+| 2026-04-04 | Phase 7: services layer, hooks, homepage + event detail API wiring, vitest |
+| 2026-04-04 | Phase 8: attendee auth API, JWT, React auth flow, tests |
+| 2026-04-04 | Phase 9–10: orders, Razorpay/mock payments, webhooks, checkout UI |
+| 2026-04-04 | Phase 11: QR digital passes, verify API, ticket UI |
+| 2026-04-04 | Phase 13: design-system visual polish, motion, perf chunking |