Whole-project development plan

Executive summary

Ardh Kumbh 2027 is a pilgrimage services platform: ritual bookings (puja, Aarti, Pind Pradanam), Shahi Snan packages, Veda Mineral Water orders, stall discovery, and end-to-end payments via Stripe. Delivery uses a Turborepo monorepo — Next.js 15 (web), Expo (iOS/Android), Node + Hono (API), shared Drizzle schema and Zod validators — deployed to Vercel, Fly.io, and app stores, with Neon, R2, and Resend as core infrastructure.

The programme runs in two-week sprints, with design-first weeks, then parallel client + API build, then integration hardening before a December–early January production cutover buffer ahead of peak pilgrimage traffic.

Goals, non-goals, success measures

Primary goals

• Pilgrims can discover, configure (pilgrim / ancestor details), pay, and receive confirmation (email + WhatsApp when live) with auditable booking state.
• Operational staff can fulfil bookings without manual spreadsheet chaos (admin path: minimal internal tools or integrated admin API — decide and implement by sprint 10).
• Web + mobile parity on core commerce: catalog → detail → cart → checkout → confirmation → “my bookings”.
• Find nearest stall works on mobile (GPS + maps) and web (embed + consent).

Non-goals (initial programme)

• Building a generic OTA for non-Kumbh inventory.
• Multi-gateway payments (Stripe-only is intentional).
• Flutter client (Expo-only per programme decision).
• Heavy custom CMS — prefer MDX/content layer or headless CMS only if editorial demand is proven.

Success measures (KPIs)

Scope matrix & business rules

Technical constraints

• Single Stripe webhook ingress on the Hono API — verify signature once; no duplicate Next + API handlers.
• Validators live in packages/validators; API imports them; web and mobile reuse for client-side parity.
• Better Auth: one documented session strategy for web and mobile (cookies vs bearer); avoid split identity tables.
• packages/ui is web-only bespoke UI; do not import into Expo without RN Web — see design language.
• Region: API on Fly (e.g. Singapore); tune Neon pool and cold-start budgets for checkout paths.

Workstreams & dependencies

These streams run in parallel after Phase 1; critical path is Auth → Catalog → Booking draft → Stripe → Webhook → Confirmation.

Phased roadmap (0–5)

Each phase has entry criteria (what must be true to start) and exit criteria (what must be true to advance).

Phase 0 Discovery & alignment (1–2 weeks)

• Confirm Shahi Snan date list, package SKUs, pricing model, cancellation rules.
• Choose WhatsApp BSP / Meta Cloud path; start any verification early.
• Exit: signed scope doc, RACI, communication rhythm (e.g. weekly demo).

Phase 1 Experience design (2–4 weeks)

• All critical screens: marketing, services, PDP, cart, checkout, auth, dashboard, stall, water.
• Component and token specs for culturally rooted UI; mobile parallel wireframes with the same visual system.
• Exit: design freeze + annotated handoff; URL map stable.

Phase 2 Foundation build (4–6 weeks)

• Monorepo, Neon, Drizzle migrations, users/packages/bookings/pilgrims/payments.
• Better Auth E2E on web; mobile session parity spike.
• Exit: staging deploy; health check; one vertical slice behind feature flag optional.

Phase 3 Parallel feature build (8–12 weeks)

• Web + Expo consume same endpoints; cart + checkout + Stripe + webhook path.
• Domain depth: ancestors, shahi date validation, water orders, reviews.
• Exit: feature-complete against v1 scope checklist; no P0 bugs in checkout.

Phase 4 Integration & hardening (4 weeks)

• E2E (Playwright web); mobile smoke + detox/Maestro if adopted.
• Load on checkout; webhook chaos testing; secret rotation drill.
• Exit: release candidate signed off; privacy + content pages live.

Phase 5 Launch & in-season ops (Jan–Apr 2027)

• Production cutover; monitoring; on-call; hotfix process (Expo Updates for eligible JS fixes).
• Exit: orderly ramp-down; post-mortem; archive costs (R2, Neon).

Sprint calendar (2-week cadence)

Sixteen sprints ≈ eight months from mid-2026; adjust start date to your real kickoff. Each sprint ends with a demo, retro, and backlog refinement.

Quality, testing, definition of done

Definition of Done (representative)

• Types strict; no any in new code paths.
• Zod validation on API boundary; same schemas used in UI where applicable.
• Unit tests for pricing / date / pilgrim count rules in API service layer.
• Critical path E2E: login → add package → pay (Stripe test) → confirmed state.
• Accessibility: keyboard nav and focus order on checkout; color contrast on marketing.
• Observability: structured logs for payment and webhook events (redact PII).

Test pyramid

• Many unit tests (pure rules, validators).
• Some integration tests (API + test DB or containers).
• Few E2E flows (stable, run in CI on main).
• Manual device matrix for maps, payments, and low-network conditions.

Environments & release train

Versioning: API under /v1; additive changes preferred. Mobile uses EAS channels (e.g. staging / production). Web deploys continuously with guardrails.

Integration programme

Order reflects dependency risk — parallelise where rows do not block.

1. Neon + Drizzle — P0; block everything.
2. Stripe test — P0; unblock checkout development.
3. Resend — P0 for confirmations.
4. R2 — P1 for marketing assets and package imagery.
5. Google Maps — P1; billing account + key restrictions.
6. WhatsApp — P1; template approval lead time.
7. Sentry / analytics — P2 once core flows stable.

Risk register & mitigations

Milestone gates & launch

• M1 — Design freeze: all checkout and auth flows approved.
• M2 — First paid booking (staging): end-to-end with test cards.
• M3 — Beta: limited real users; production Stripe with low traffic cap optional.
• M4 — General availability: marketing push allowed; app stores live.
• M5 — Event readiness (by ~7 Jan 2027): on-call rota, frozen deps unless critical CVE.

In-season operations (Jan–Apr 2027)

• Monitoring: error rate, checkout funnel, API latency, DB connections.
• Support: defined SLAs for booking issues; manual override path in admin.
• Change control: freeze except P0 during peak Snan windows if agreed.
• Expo Updates: eligible JS fixes only; native changes via store when required.
• Incident response: severity levels, comms template, Stripe dashboard links.

Appendix · documentation map

Detailed specs live in sibling pages — keep this plan as the orchestration layer; update those pages when contracts change.

• Architecture — repo tree, principles.
• Design language — cultural UI for web and Expo.
• Web application — Next.js routes and UI.
• Mobile (Expo) — native concerns.
• Backend API — Hono, webhooks, services.
• Database — Drizzle schema reference.
• API reference — REST catalogue.
• Delivery & operations — sprint detail, MVP slice, CI/CD.