Project Structure

The kit follows Next.js App Router conventions with a clean separation between frontend components, backend logic, and database infrastructure.

Top-Level Structure

ecommerce-supabase/
├── app/                    # Next.js routes and API endpoints
├── components/             # React components (3-tier hierarchy)
├── context/                # React context providers
├── data/                   # Static data (navigation, blog, testimonials)
├── hooks/                  # Custom React hooks
├── lib/                    # Utilities, Supabase clients, Server Actions
├── supabase/               # Database migrations and seed data
├── types/                  # TypeScript type definitions
├── public/                 # Static assets
├── middleware.ts           # Auth middleware for route protection
└── .env.example            # Environment variable template

Route Groups

The app/ directory uses Next.js route groups for layout separation:

app/
├── (storefront)/           # Public shopping pages
│   ├── page.tsx            # Homepage
│   ├── products/           # Product listing and detail
│   ├── categories/         # Category pages
│   ├── collections/        # Collection pages
│   ├── search/             # Search results
│   ├── cart/               # Shopping cart
│   ├── checkout/           # Multi-step checkout
│   ├── order-confirmation/ # Post-payment confirmation
│   ├── wishlist/           # Saved items
│   └── ...                 # About, contact, FAQs, etc.
├── (auth)/                 # Authentication pages
│   ├── login/
│   ├── register/
│   ├── forgot-password/
│   └── auth/               # OAuth callback and email confirm routes
├── (account)/              # Customer account (protected)
│   └── account/
│       ├── page.tsx        # Account dashboard
│       ├── orders/         # Order history and detail
│       ├── addresses/      # Address book
│       ├── reviews/        # Customer reviews
│       ├── returns/        # Return requests
│       └── settings/       # Account settings
├── (admin)/                # Admin panel (admin role required)
│   └── admin/
│       ├── page.tsx        # Admin dashboard
│       ├── products/       # Product management
│       ├── orders/         # Order management
│       ├── customers/      # Customer directory
│       ├── analytics/      # Analytics and reports
│       ├── discounts/      # Discount codes
│       ├── reviews/        # Review moderation
│       └── settings/       # Store settings
└── api/
    ├── checkout/           # Stripe Checkout Session creation
    └── webhooks/stripe/    # Stripe webhook handler

Component Hierarchy

Components follow a 3-tier system:

components/
├── ui/                     # Tier 1: shadcn/ui primitives (never modified)
│   ├── button.tsx
│   ├── card.tsx
│   ├── dialog.tsx
│   └── ...
├── storefront/             # Tier 2: Storefront composites
│   ├── product-card.tsx
│   ├── product-gallery.tsx
│   ├── filter-sheet.tsx
│   ├── order-summary.tsx
│   └── ...
├── admin/                  # Tier 2: Admin composites
│   ├── image-uploader.tsx
│   └── ...
└── layout/                 # Tier 2: Layout components
    ├── store-header.tsx
    ├── store-footer.tsx
    ├── admin-sidebar.tsx
    └── ...

Backend Infrastructure

lib/
├── supabase/
│   ├── client.ts           # Browser Supabase client
│   ├── server.ts           # Server Supabase client (reads cookies)
│   ├── admin.ts            # Service-role client (bypasses RLS)
│   └── middleware.ts       # Middleware Supabase client
├── stripe.ts               # Server-side Stripe instance
├── actions/                # Next.js Server Actions
│   ├── products.ts         # Product CRUD
│   ├── orders.ts           # Order management
│   ├── reviews.ts          # Review moderation
│   ├── addresses.ts        # Address CRUD
│   ├── returns.ts          # Return requests
│   ├── discounts.ts        # Discount codes
│   └── customers.ts        # Customer queries
└── queries.ts              # Shared Supabase query functions

Database Files

supabase/
├── migrations/
│   ├── 001_schema.sql      # 18 tables: products, orders, users, etc.
│   ├── 002_rls.sql         # Row-level security policies
│   ├── 003_triggers.sql    # Auto profile creation, review aggregation
│   └── 004_storage.sql     # Product images bucket
└── seed.sql                # 40 products, categories, reviews, orders

Context Providers

context/
├── cart-context.tsx         # Hybrid cart (guest localStorage + Supabase)
├── wishlist-context.tsx     # Wishlist with guest/auth support
└── recently-viewed-context.tsx  # Client-side recently viewed

Key Files

File	Purpose
middleware.ts	Protects /account/* and /admin/* routes
hooks/use-user.ts	Client hook for current user session
types/database.ts	Generated Supabase database types
types/index.ts	Application-level TypeScript interfaces
data/static.ts	Navigation, blog posts, testimonials (non-DB data)