414 lines
15 KiB
Markdown
414 lines
15 KiB
Markdown
# 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 |
|