Codebase Guide

Master reference for this TanStack Start e-commerce application.

Quick Reference

api-routes

admin-crud

forms

database

i18n

testing

checkout

security

debugging

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend                                 │
├──────────────────┬──────────────────┬──────────────────────────┤
│   Customer UI    │    Admin UI      │      Shared UI           │
│   /$lang/*       │    /admin/*      │   /components/ui/*       │
│                  │                  │                          │
│  • Product pages │  • Dashboard     │  • Button, Input, Card   │
│  • Cart/Checkout │  • Orders table  │  • Dialog, Badge, Tabs   │
│  • Account       │  • Product CRUD  │  • FNForm (forms)        │
└────────┬─────────┴────────┬─────────┴────────────┬─────────────┘
         │                  │                      │
         ▼                  ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                      State Management                            │
├──────────────────┬──────────────────┬──────────────────────────┤
│     Zustand      │   React Query    │    TanStack Form         │
│                  │                  │                          │
│  • useCartStore  │  • Server state  │  • Form validation       │
│  • useAuthStore  │  • Caching       │  • Field management      │
│  • localStorage  │  • Mutations     │  • Submit handling       │
└────────┬─────────┴────────┬─────────┴────────────┬─────────────┘
         │                  │                      │
         ▼                  ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                       API Layer                                  │
│                    /routes/api/*                                 │
├──────────────────┬──────────────────┬──────────────────────────┤
│   Auth APIs      │   CRUD APIs      │    Webhooks              │
│                  │                  │                          │
│  • /auth/login   │  • /products     │  • /webhooks/stripe      │
│  • /auth/logout  │  • /orders       │  • /webhooks/paypal      │
│  • /auth/me      │  • /customers    │                          │
└────────┬─────────┴────────┬─────────┴────────────┬─────────────┘
         │                  │                      │
         ▼                  ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Server Layer                                 │
│                      /src/server/*                               │
├──────────────────┬──────────────────┬──────────────────────────┤
│   Business Logic │   Utilities      │    Integrations          │
│                  │                  │                          │
│  • orders.ts     │  • auth.ts       │  • stripe.ts             │
│  • products.ts   │  • api.ts        │  • paypal.ts             │
│  • checkout.ts   │  • rate-limit.ts │  • cloudinary.ts         │
└────────┬─────────┴────────┬─────────┴────────────┬─────────────┘
         │                  │                      │
         ▼                  ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Database Layer                              │
│                  Drizzle ORM + PostgreSQL                        │
├──────────────────┬──────────────────┬──────────────────────────┤
│   Auth Tables    │   Store Tables   │    Order Tables          │
│                  │                  │                          │
│  • users         │  • products      │  • orders                │
│  • sessions      │  • variants      │  • orderItems            │
│  • customers     │  • collections   │  • checkouts             │
└──────────────────┴──────────────────┴──────────────────────────┘

Tech Stack

Directory Structure

src/
├── routes/                    # File-based routing
│   ├── $lang/                 # Localized customer pages
│   │   ├── index.tsx          # Homepage
│   │   ├── products/          # Product catalog
│   │   ├── cart.tsx           # Shopping cart
│   │   ├── checkout/          # Checkout flow
│   │   └── account/           # Customer account
│   ├── admin/                 # Admin dashboard
│   │   ├── index.tsx          # Dashboard home
│   │   ├── products/          # Product management
│   │   ├── orders/            # Order management
│   │   └── login.tsx          # Admin login
│   └── api/                   # REST API endpoints
│       ├── auth/              # Authentication
│       ├── products/          # Product CRUD
│       ├── orders/            # Order management
│       ├── checkout/          # Checkout flow
│       └── webhooks/          # Payment webhooks
├── components/
│   ├── ui/                    # Reusable UI (shadcn pattern)
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── fn-form.tsx        # Centralized form component
│   │   └── ...
│   ├── admin/                 # Admin-specific components
│   │   ├── products/          # Product management UI
│   │   ├── orders/            # Order management UI
│   │   └── media/             # Media library
│   └── checkout/              # Checkout components
├── hooks/
│   ├── useAuth.ts             # Authentication state
│   ├── useCart.ts             # Cart state (Zustand)
│   ├── useCheckout.ts         # Checkout state
│   └── useDataTable.ts        # Admin table state
├── lib/
│   ├── auth.ts                # Auth utilities
│   ├── api.ts                 # Response helpers
│   ├── stripe.ts              # Stripe client
│   ├── paypal.ts              # PayPal client
│   ├── rate-limit.ts          # Rate limiting
│   ├── csrf.ts                # CSRF protection
│   ├── i18n.ts                # i18n setup
│   └── utils.ts               # General utilities
├── db/
│   ├── index.ts               # Database client
│   └── schema.ts              # Drizzle schema
├── server/
│   ├── orders.ts              # Order business logic
│   └── products.ts            # Product business logic
└── i18n/
    └── locales/               # Translation files
        ├── en.json
        ├── fr.json
        └── id.json

Key Patterns

1. API Routes

All API routes use TanStack Router server handlers:

export const Route = createFileRoute('/api/resource')({
  server: { handlers: { GET, POST, PATCH, DELETE } },
})

2. Authentication

Session-based with HTTP-only cookies. Check with

requireAuth(request)

requireAdmin(request)

3. Localized Content

Database stores JSONB:

{ en: "English", fr?: "French", id?: "Indonesian" }

4. Forms

Use

FNForm

5. State

• Zustand: Cart, auth (persistent)
• React Query: Server data (cached)
• TanStack Form: Form state

6. Security

• Rate limiting on all endpoints
• CSRF tokens for mutations
• Input validation
• Timing-safe comparisons

Common Tasks

src/routes/api/

src/routes/admin/

src/components/admin/

src/routes/$lang/

src/db/schema.ts

yarn db:generate

src/i18n/locales/*.json

src/lib/

src/hooks/

Development Commands

yarn dev          # Start dev server (port 3000)
yarn build        # Production build
yarn test         # Run tests
yarn typecheck    # Type checking
yarn db:generate  # Generate migrations
yarn db:migrate   # Apply migrations
yarn db:studio    # Database GUI
yarn locales:scan # Scan for translation keys