Project Structure

This page documents the complete structure of the kulhad-chai-booking application and what each area is responsible for.

Top-level overview

kulhad-chai-booking/
  app/                # Next.js App Router routes (pages, layouts, API)
  components/         # Reusable UI and feature components (shadcn + Radix)
  contexts/           # React Context providers (auth, theme)
  lib/                # Core business logic, data access (Supabase), types
  public/             # Static assets (logos, images, manifest)
  scripts/            # One-off node scripts (e.g., seed, create admin)
  styles/             # Global CSS (Tailwind)
  supabase/           # Local Supabase config & SQL migrations
  utils/              # Supabase client factories and middleware glue
  docs/               # Project docs (setup, architecture, troubleshooting)
  middleware.ts       # Auth/session protection for routes
  next.config.mjs     # Next.js config (security headers, images)
  package.json        # Dependencies and scripts
  README.md           # Project readme

Routes (App Router)

• app/page.tsx: Customer landing and menu experience with add-to-cart and sticky cart footer.
• app/layout.tsx: Root layout, fonts, analytics, global providers (AuthProvider, ToastProvider).
• app/checkout/page.tsx: Checkout flow (table param, cart summary, continue to order).
• app/billing/page.tsx: Billing UI and printing.
• app/qr-codes/page.tsx: Generate and manage table QR codes.
• app/shop-portal/*: Staff portal (login + shell) protected by middleware.
• app/admin/*: Admin login and settings.
• app/admin-dashboard/*: Full business suite: customers, products, invoices, payments, reports, etc.
• app/analytics/* and app/analytics-dashboard/page.tsx: KPIs and charts.
• app/api/orders/*: Server endpoints for order creation and retrieval.

Key components

• components/navbar.tsx: Responsive navbar with cart counter and admin link.
• components/loading-skeleton.tsx: Placeholder skeletons for perceived performance.
• components/bill-printer.tsx: Print-ready bill component with template options.
• components/order-notification.tsx: Real-time toast when new orders arrive.
• components/admin-sidebar.tsx: Sidebar navigation for the dashboard.
• components/ui/*: Shadcn/Radix primitives (button, card, dialog, table, charts, etc.).

Core business logic (lib)

• lib/supabase.ts: Typed Supabase client and database table typings.
• lib/database.ts: Data-access services for menu items, tables, orders + realtime subscriptions.
• lib/supabase-service.ts: Business suite services (customers, products, invoices, payments, users, settings).
• lib/menu-data.ts: Curated menu catalog used for client display.
• lib/menu-sync.ts: Maps frontend menu IDs to DB UUIDs; optional syncing helpers.
• lib/print-bill.ts, lib/print-utils.tsx: Printing helpers and UI utilities.
• lib/types.ts + lib/business-types.ts: Shared domain models for ordering and billing.

Auth & route protection

• utils/supabase/client.ts and server.ts: SSR/browser Supabase clients (session persistence, cookies).
• utils/supabase/middleware.ts: Session refresh + guarded routes; redirects to login for protected paths.
• middleware.ts: Global matcher excluding assets; applies updateSession to every request.

Supabase integration

• Tables: menu_items, tables, orders, order_items, plus business: customers, products, invoices, invoice_items, payments, users, user_activities, business_settings.
• Realtime: channels for orders, order_items, tables to push UI updates.
• Auth: supabase-auth with role-based checks in middleware (admin gate for /admin-dashboard).

Styling and UX

• TailwindCSS v4 with optimized, mobile-first styles.
• Glassmorphism and subtle gradients; animated background blobs on customer menu.
• Accessibility: focus rings, larger tap targets, ARIA roles, reduced motion defaults.

Build and performance settings

• next.config.mjs: Security headers, compression, SWC minify, unoptimized images (for portability), strict mode.
• Code-splitting: lazy-loaded charts and heavy components in admin dashboard.

Scripts

• scripts/create-admin*.js: Utilities to create an initial admin user.

Docs within repo

• docs/architecture/*: system overview, codebase map, auth details.
• docs/setup/*: installation, supabase setup, admin creation.
• docs/troubleshooting/*: common issues.

For a visual overview of this structure, see the System Architecture page.