Feature Architecture

Layer Overview

┌─────────────────────────────────────────┐
│  Pages (src/app/)                       │  Route handlers, layouts
├─────────────────────────────────────────┤
│  Components (features/*/components/)    │  UI elements
├─────────────────────────────────────────┤
│  Server Actions (features/*/usecases/)  │  API layer
├─────────────────────────────────────────┤
│  Services (features/*/<name>-service)   │  Business logic
├─────────────────────────────────────────┤
│  DAL (features/*/dal/)                  │  Database access
├─────────────────────────────────────────┤
│  Model (features/*/model/)              │  Schemas, types
└─────────────────────────────────────────┘

Implementation Order

Always implement bottom-up:

1. Model - Zod schemas, types, constants
2. DAL - Database operations
3. Service - Business logic
4. Actions - Server actions
5. Components - UI
6. Pages - Routes

Feature Directory Structure

src/features/<feature>/
├── model/
│   ├── <feature>-schemas.ts     # Zod schemas + types
│   └── <feature>-constants.ts   # Constants
├── dal/
│   ├── create_<entity>.ts       # snake_case files
│   ├── find_<entity>_by_id.ts
│   ├── update_<entity>.ts
│   └── delete_<entity>.ts
├── <feature>-service.ts         # Business logic
├── usecases/
│   ├── create/actions/<action>.ts
│   ├── update/actions/<action>.ts
│   └── delete/actions/<action>.ts
├── components/
│   ├── <Component>.tsx
│   ├── <Component>-server.tsx
│   └── <Component>-client.tsx
└── utils/                       # Feature utilities

Layer Responsibilities

Model Layer

• Zod schemas for validation
• TypeScript types (inferred from Zod)
• Constants and enums
• No logic, only definitions

DAL Layer

• Direct database operations
• One file per operation
• snake_case naming
• Returns { success, data?, error? }
• Entity-to-model converters
• No business logic

Service Layer

• Business logic and validation
• Orchestrates DAL calls
• Permission checks
• Called by actions, not directly by UI

Actions Layer

• Server actions for client calls
• Authentication via authedProcedure
• Input validation with Zod
• Calls services, NOT DAL
• Cache revalidation

Components Layer

• Server components (default)
• Client components (interactivity)
• Split pattern for hybrid needs

Pages Layer

• Route definitions
• Layout composition
• Data fetching (server components)

Naming Conventions

Layer	Case	Example
Model files	kebab-case	account-schemas.ts
DAL files	snake_case	create_account.ts
Service files	kebab-case	account-service.ts
Action files	kebab-case	create-account-action.ts
Components	PascalCase	AccountCard.tsx
Directories	kebab-case	user-profile/
Constants	SCREAMING_SNAKE	MAX_NAME_LENGTH

Data Flow

User Action
    ↓
Component (client)
    ↓
Server Action (validates, authenticates)
    ↓
Service (business logic)
    ↓
DAL (database operation)
    ↓
DynamoDB

Quick Reference

Need to...	Go to...
Add validation	model/<feature>-schemas.ts
Add DB operation	dal/ (new snake_case file)
Add business rule	<feature>-service.ts
Add API endpoint	usecases/*/actions/
Add UI element	components/
Add page route	src/app/

Environment Setup

# Install UV for Python tools
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
pnpm install

# Development
pnpm dev

# SST dev mode
npx sst dev --stage dev

Related Skills

• zod-validation - Schema patterns
• dynamodb-onetable - Database patterns
• nextjs-server-actions - Action patterns
• nextjs-web-client - Component patterns
• sst-infra - Deployment patterns