bis0908/gender-reveal

Purpose and Runtime

A Next.js 15 App Router application for creating and sharing personalized online gender-reveal events. TypeScript, Tailwind/shadcn UI, and Framer Motion power the browser experience; Vercel is the intended deployment target. The root shell and public landing entry are app/layout.tsx and app/page.tsx.

Reveal Creation and Token Boundary

The creation flow gathers parent, baby, schedule, D-day, and animation choices, then produces a shareable signed token rather than exposing event data directly. Primary UI orchestration is in components/reveal-form/reveal-form.tsx, with token issuance at app/api/generate-token/route.ts and verification at app/api/verify-token/route.ts. JWT configuration and server-only environment access are centralized in lib/config.ts and lib/env.server.ts; JWT_SECRET is the core trust boundary.

Shared Countdown and Reveal Experience

Recipients open /countdown/[token], where token-derived event state drives a live countdown, voting/waiting states, and redirect to the reveal. The route is composed in app/countdown/[token]/page.tsx, with timed client behavior in app/countdown/[token]/components/CountdownTimer.tsx. The final reveal route is app/reveal/page.tsx, which renders staged loading, intro, animation, and result views through app/reveal/components/RevealAnimation.tsx and app/reveal/components/RevealResults.tsx.

Animation Rendering

Animation choice is a data-to-component dispatch boundary: event configuration selects an implementation, while the renderer isolates the presentation contract. components/animation-renderer.tsx and components/animation-selection.tsx connect form selection to animations such as components/animations/reveal-animation.tsx, components/animations/balloonpop-animation.tsx, and components/animations/fireworks-animation.tsx. This keeps visual variants separate from token, D-day, and voting logic.

D-Day Coordination and Voting

D-day events use server API routes to create event records, expose reveal-safe data, and accept votes: app/api/dday/create/route.ts, app/api/dday/reveal-data/route.ts, and app/api/dday/vote/route.ts. Input contracts live in lib/schemas/dday-schema.ts; timing and event transformations are in lib/dday-utils.ts. Client vote state is handled by hooks/useVoteStatus.ts, with cookie/device-style protections implied by the API boundary.

Persistence, Limits, and Integrations

Supabase is the durable analytics/database layer, represented by server/client adapters in lib/supabase/server.ts and lib/supabase/client.ts, plus migration supabase/migrations/20260721233853_reveal_generation_metrics.sql. Redis/Upstash is used for rate limiting via lib/redis.ts and lib/services/generation-rate-limit.ts. Generation metrics flow through lib/services/generation-metrics.ts; feedback enters through app/api/feedback/route.ts and may integrate with Google Sheets and email through lib/services/google-sheets.ts and lib/services/email.ts.

Administrative Observability and Access Control

Admin login, protected metrics pages, and an API reporting surface form the operational subsystem. Entrypoints are app/admin/login/page.tsx, app/admin/metrics/page.tsx, and app/api/admin/metrics/route.ts. Authorization is enforced through lib/auth/require-admin.ts, while metrics aggregation is owned by lib/services/admin-metrics.ts. Middleware-level Supabase session handling is implemented in middleware.ts and lib/supabase/middleware.ts.

Cross-Cutting UI and Localization

Shared navigation, theme, feedback, and locale support are anchored in components/header.tsx, components/theme-provider.tsx, and lib/i18n/context.tsx. Localized copy is bundled under lib/i18n/locales/en.json, lib/i18n/locales/jp.json, and lib/i18n/locales/ko.json. Changelog content is filesystem-backed Markdown, surfaced through app/changelog/page.tsx and parsed by lib/markdown.ts.