majiayu000 Codebase Guide
Master reference for this TanStack Start e-commerce application.
Quick Reference
| Need | Skill |
|---|---|
| Create API endpoint | api-routes |
| Build admin page | admin-crud |
| Add form | forms |
| Modify database | database |
| Add translations | i18n |
| Write tests | testing |
| Fix checkout issues | checkout |
| Security review | security |
| Debug issues | 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
| Layer | Technology | Purpose |
|---|---|---|
| Framework | TanStack Start | SSR/SSG with Vite + Nitro |
| Router | TanStack Router | File-based routing |
| Database | Drizzle + PostgreSQL | Type-safe ORM |
| State | Zustand | Client state with persistence |
| Server State | React Query | Caching, mutations |
| Forms | TanStack Form + FNForm | Validation, field management |
| UI | Radix + shadcn + Tailwind v4 | Accessible components |
| i18n | i18next | Multi-language (en, fr, id) |
| Payments | Stripe + PayPal | Checkout processing |
| Media | Cloudinary | Image upload/optimization |
| SendGrid | Transactional emails |
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) or requireAdmin(request).
3. Localized Content
Database stores JSONB: { en: "English", fr?: "French", id?: "Indonesian" }
4. Forms
Use FNForm component for all forms. Supports grid layouts, validation, custom fields.
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
| Task | Files to Modify |
|---|---|
| Add API endpoint | src/routes/api/ |
| Add admin page | src/routes/admin/, src/components/admin/ |
| Add customer page | src/routes/$lang/ |
| Modify schema | src/db/schema.ts, run yarn db:generate |
| Add translation | src/i18n/locales/*.json |
| Add utility | src/lib/ |
| Add hook | 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