# 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 |