Skip to content

architecture.md

Latest commit

 

History

History
66 lines (50 loc) · 2.14 KB

architecture.md

File metadata and controls

66 lines (50 loc) · 2.14 KB

Architecture

Overview

Next.js App Router with Convex backend. Feature-based design pattern.

Tech Stack

  • Frontend: Next.js, React, TypeScript, TailwindCSS, shadcn/ui
  • Backend: Convex (real-time database, functions, auth)
  • State: Jotai (feature state), Convex queries (server state)

Directory Structure

src/
├── app/                    # Next.js App Router (routes)
├── features/               # Feature modules (business domains)
├── components/ui/          # Shared UI primitives
├── lib/                    # Utilities, error handling
└── hooks/                  # Shared hooks

convex/
├── schema.ts               # Database schema
├── http.ts                 # HTTP routes (webhooks)
├── crons.ts                # Scheduled jobs
├── _helpers/               # Shared utilities
└── [entity].ts             # Backend functions by entity

Feature Module Structure

Each feature is a self-contained module:

features/[name]/
├── api/            # Data fetching hooks (use-get-*, use-create-*)
├── components/     # Feature-specific UI
├── hooks/          # Business logic hooks
├── store/          # State atoms (Jotai)
├── types.ts        # TypeScript types
└── index.ts        # Public exports

State Management

Layer Tool Use
Component useState Local UI state
Feature Jotai atoms Feature-wide UI state
Server Convex queries Database data (real-time)
URL Search params Filters, pagination

Error System

  1. Backend: Typed error codes thrown via helper functions
  2. Frontend: Mutation hooks parse and surface typed errors
  3. UI: Toast notifications display user-friendly messages

Conventions

  • Files: kebab-case
  • Components: PascalCase exports
  • Hooks: use-[name].ts → useHookName
  • Imports: Path aliases (@/*), no deep relative imports
  • Components: Server Components by default, Client Components only when needed