Skip to content

03-stack-reference.md

Latest commit

 

History

History
130 lines (99 loc) · 3.35 KB

03-stack-reference.md

File metadata and controls

130 lines (99 loc) · 3.35 KB
Raw

Stack Reference

Architecture Overview

This template uses a modern, type-safe stack optimized for designer-led development with ACA assistance.

Frontend Stack

Next.js (App Router)

  • Version: 14+
  • Why: Server components, excellent TypeScript support, built-in optimizations
  • Key Files: app/ directory

TypeScript

  • Mode: Strict
  • Why: Type safety helps ACAs understand code better
  • Config: tsconfig.json

Tailwind CSS

  • Version: 3.x
  • Why: Utility-first CSS, excellent ACA support
  • Config: tailwind.config.ts

shadcn/ui

  • Why: Accessible, customizable components
  • Location: components/ui/
  • Installation: Included in repo (not via npm)

React Hook Form + Zod

  • Why: Type-safe form handling with validation
  • Usage: See components/examples/form-with-validation.tsx

Backend Stack

Convex

  • Why: Real-time database with built-in backend functions
  • Schema: convex/schema.ts
  • Queries/Mutations: convex/*.ts files
  • Client: Used via hooks in features/*/hooks/

Architecture Pattern

UI Components → Domain Hooks → Convex Queries/Mutations → Database

Important: UI components should NEVER call Convex directly. Always use domain hooks.

Authentication

NextAuth.js (Auth.js)

  • Version: v5
  • Why: Industry-standard authentication
  • Route: app/api/auth/[...nextauth]/route.ts
  • Helper: core/auth/getCurrentUser.ts

File Structure Patterns

Features

features/<domain>/
  ├─ components/     # React components
  ├─ hooks/          # Domain hooks (wrap Convex)
  ├─ index.ts        # Barrel exports
  └─ README.md       # Domain documentation

Convex

convex/
  ├─ schema.ts       # Database schema
  ├─ <domain>.ts     # Domain queries/mutations
  └─ system.ts       # System functions (protected)

Components

components/
  ├─ ui/             # shadcn/ui components
  ├─ layout/         # Layout components
  ├─ charts/         # Chart components
  └─ examples/       # Pattern examples

Domain Boundaries

Projects Domain

  • Convex: convex/projects.ts
  • Hooks: features/projects/hooks/
  • Components: features/projects/components/
  • Types: lib/types.ts (Project type)

Settings Domain

  • Convex: convex/users.ts (user profile)
  • Hooks: features/settings/hooks/
  • Components: features/settings/components/

AI Assistant Domain

  • Convex: convex/ai-assistant.ts
  • Hooks: features/ai-assistant/hooks/
  • Components: features/ai-assistant/components/

Data Flow

  1. User Action → Component event handler
  2. Component → Calls domain hook
  3. Hook → Calls Convex query/mutation
  4. Convex → Updates database
  5. Convex → Pushes update to client
  6. Hook → Returns updated data
  7. Component → Re-renders with new data

Type Safety

  • All Convex functions are fully typed
  • Use Id<"table"> for Convex IDs
  • Import types from @/convex/_generated/dataModel
  • Use Zod schemas for validation

Environment Variables

  • Managed via Vercel dashboard
  • Validated in core/config/env.ts (protected)
  • See .env.example for required variables

Deployment

  • Platform: Vercel
  • Database: Convex (hosted)
  • CI/CD: GitHub Actions (.github/workflows/ci.yml)