Frontend Architecture

The frontend is a Next.js 16 App Router application with a mix of server and client components.

Main directories

• app/: route segments, layouts, pages, metadata, and API routes
• components/: reusable UI and feature-specific components
• providers/: app-level providers such as Convex auth
• lib/: cross-cutting utilities

Route organization

The route tree contains several major product zones:

• public marketing and policy pages
• event discovery and checkout
• DP creation and management
• organizer operations
• admin operations
• API routes under app/api/*

UI composition

The component model is split into:

• components/ui/* for shadcn/ui-style primitives
• components/organizer/*, components/admin/*, components/events/*, and similar feature folders
• page-level logic often kept directly in route files for large dashboard screens

State and data access

• Convex client access is provided by providers/ConvexClientProvider.tsx.
• Client routes use convex/react hooks for data and actions.
• Some server-rendered metadata routes use ConvexHttpClient directly.

API routes owned by the frontend

The Next.js app owns several HTTP surfaces:

• app/api/health
• app/api/mobile/backend
• app/api/payments/checkout
• app/api/webhooks/*
• app/api/ai/*
• app/api/email/*
• wallet, QR, badges, and notification helper endpoints

Practical guidance

• Use client components only where interactivity is needed.
• Keep new low-level UI primitives in components/ui/.
• Keep feature-specific logic close to the owning route or feature folder.
• Reuse lib/money.ts for currency formatting and lib/utils.ts helpers rather than inlining equivalents.