# Product Requirements Document — Desi Clans

**Version:** 1.0  
**Status:** Constitution (pre-build)  
**Last updated:** 2026-04-04  
**Owner:** Product / Engineering

---

## 1. Vision

Desi Clans is a **premium, Bengaluru-first** platform for discovering and attending **Indian cultural celebrations**—Holi, Garba, Dandiya, and related festivities. The experience should feel **cinematic and editorial**, not like a generic ticket aggregator or concert listing site.

**In scope:** Cultural events, curated editions, venues across Bengaluru (Palace Grounds, KTPO Whitefield, HSR Layout, and similar).  
**Out of scope:** Concerts, generic nightlife listings, multi-city expansion beyond Bengaluru in v1.

---

## 2. Goals

| Goal | Success signal |
|------|----------------|
| Premium brand perception | Editorial layouts, strong typography, intentional motion |
| Mobile-first attendance | ≥60% traffic on mobile; core flows usable one-handed |
| Fast | LCP < 2.5s on 4G; API p95 < 300ms for public reads |
| Accessible | WCAG 2.1 AA for public UI; keyboard + screen reader paths |
| SEO | Indexable event URLs, share previews, structured data |
| Operable | Admin can publish editions, media, and ticket inventory without deploys |
| Trustworthy ticketing | Clear pricing, issued tickets with QR, reliable check-in |

---

## 3. Personas

### 3.1 Attendee (primary)

- Discovers events via search, social, or word of mouth.
- Needs date, venue, vibe, gallery, and a frictionless path to buy or hold tickets.
- Expects mobile ticket (QR) at the gate.

### 3.2 Organizer / Desi Clans ops

- Publishes event editions, hero media, copy, and SEO fields.
- Manages ticket tiers, capacity, and sales window.
- Monitors outbound or native sales and gate check-in.

### 3.3 Gate staff

- Scans QR codes quickly; sees valid / already used / invalid states.
- Works on mobile browsers in variable network conditions.

### 3.4 Platform admin

- Manages admin users (roles), site links, newsletter subscribers, and analytics.

---

## 4. User stories (v1)

### Discovery & content

- As an attendee, I can browse **published** event editions filtered by type and date.
- As an attendee, I can open an **event detail page** with cover, gallery, venue, calendar add, and ticket CTA.
- As an attendee, I can share an event; recipients see a **rich preview** (title, image, description).

### Accounts (ticketing phase)

- As an attendee, I can register / log in to purchase and view **my tickets**.
- As an attendee, I receive a **confirmation** with ticket QR(s) after purchase.

### Ticketing

- As ops, I define **ticket tiers** (name, price, quantity, sale window) per edition.
- As an attendee, I can **purchase** tickets (native checkout in target architecture; see phases).
- As gate staff, I can **scan** a QR and mark entry once per ticket.

### Admin

- As an editor, I can CRUD editions, upload cover and gallery media, set publish/featured flags.
- As super admin, I can manage admin users and view click / sales summaries.
- As ops, I can export subscriber list and send alerts (email) for new editions (batch, not real-time chat).

### Newsletter

- As a visitor, I can subscribe with email and optional neighborhood.

---

## 5. Functional requirements

### 5.1 Public site

- Home: featured edition(s), upcoming list, brand story strip.
- Event listing with filters: `event_type`, date range, featured.
- Event detail: slug URL, `meta_description`, Open Graph via share route or SSR meta injection.
- Outbound ticket links (BookMyShow, District, etc.) **or** native checkout when enabled per edition.
- Calendar download (`.ics`) for edition start time.
- Newsletter signup.

### 5.2 Authentication

- **Admin:** JWT (access token), bcrypt passwords, role-based access (`super_admin`, `editor`).
- **Attendees (ticketing phase):** JWT for account + order history; separate from admin namespace.

### 5.3 Admin dashboard

- Secure login; session via Bearer token stored in memory (not localStorage for admin if avoidable; httpOnly cookie acceptable future enhancement).
- Edition editor, media manager, platform links, subscribers, analytics (outbound clicks; order stats when native ticketing live).
- Check-in view for authorized staff (role or edition-scoped permission).

### 5.4 Ticketing model (target)

- **Edition** → one or more **ticket tiers** → **orders** → **tickets** (unique code + QR payload).
- Inventory enforced at order creation ( pessimistic row lock or atomic decrement ).
- QR encodes signed token or opaque ticket id verified server-side (no PII in QR).
- States: `issued`, `checked_in`, `cancelled`, `refunded` (refund workflow optional v1.1).

### 5.5 Payments (phased)

- **Phase A:** Outbound links only (no payment on Desi Clans).
- **Phase B:** Native orders with payment provider webhook (e.g. Razorpay)—documented in architecture, implemented only when product enables it.

### 5.6 Non-functional

- API version prefix: `/api/...`
- PostgreSQL as system of record; Alembic migrations required for schema changes.
- Media: local disk in dev; S3-compatible object storage in production (optional boto3—already present in environment).
- No concert content types in taxonomy.

---

## 6. Event taxonomy

| `event_type` | Description |
|--------------|-------------|
| `holi` | Holi celebrations |
| `garba` | Garba nights |
| `dandiya` | Dandiya events |
| `bhajan_clubbing` | Curated devotional / club fusion (brand-specific) |
| `special` | Other Indian cultural celebrations (not concerts) |

---

## 7. Out of scope (v1)

- Multi-language UI (English only v1).
- Native mobile apps.
- Seat maps / reserved seating.
- Secondary resale marketplace.
- Live streaming.
- User-generated reviews or forums.
- Concert and non-cultural listings.

---

## 8. Risks & mitigations

| Risk | Mitigation |
|------|------------|
| Double ticket sale | DB transactions, unique constraints, idempotent payment webhooks |
| QR forgery | Signed payloads, server validation, rate limits on scan |
| Admin token theft | Short JWT TTL, HTTPS only, minimal CORS origins |
| Heavy media hurting LCP | Responsive images, lazy load, CDN for production assets |

---

## 9. Acceptance criteria (MVP public site)

- [ ] Published editions render from API on home, list, and detail routes.
- [ ] Event pages include correct meta for SEO and social sharing.
- [ ] Mobile layout passes manual QA on iOS Safari and Chrome Android.
- [ ] Admin can publish an edition with cover and gallery without code changes.
- [ ] Lighthouse accessibility score ≥ 90 on event detail (lab).

**MVP ticketing (later phase):** purchase flow, email with QR, successful check-in scan.

---

## 10. References

- [ARCHITECTURE.md](./ARCHITECTURE.md) — system design and phases  
- [API_SPEC.md](./API_SPEC.md) — endpoints  
- [DATABASE.md](./DATABASE.md) — entities  
- [DESIGN_SYSTEM.md](./DESIGN_SYSTEM.md) — UI principles  
- [PROGRESS.md](./PROGRESS.md) — implementation status