home / skills / gilbertopsantosjr / fullstacknextjs / feature-architecture

feature-architecture skill

safe

/skills/feature-architecture

This skill guides feature planning and organization across models, DAL, services, actions, components, and pages in a layered Next.js architecture.

npx playbooks add skill gilbertopsantosjr/fullstacknextjs --skill feature-architecture

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

4.8 KB

---
name: feature-architecture
description: Guide for implementing features in a layered Next.js full-stack architecture. Use when planning new features, understanding the layer structure (Model, DAL, Service, Actions, Components, Pages), or deciding where code should live.
---

# 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

```bash
# 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

Overview

This skill guides implementing features in a layered Next.js full-stack architecture. It defines a clear folder layout (Model, DAL, Service, Actions, Components, Pages) and prescribes a bottom-up implementation order to keep responsibilities separated. The aim is predictable data flow, consistent naming, and easy maintenance across features.

How this skill works

Start by defining types and validation in the Model layer, then add one-file-per-operation DAL functions for database access. Build business rules and orchestration in the Service layer, expose functionality through Server Actions, and implement UI with split server/client Components before wiring Pages and routes. Each layer has strict responsibilities and naming conventions to avoid leakage of concerns.

When to use it

Planning a new feature to ensure consistent structure and responsibilities
Deciding where to place validation, database access, or business rules
Onboarding engineers to the project architecture and coding standards
Refactoring an existing feature to separate concerns and improve testability
Designing API endpoints and server action flows that require auth and validation

Best practices

Implement bottom-up: Model → DAL → Service → Actions → Components → Pages
Keep Model files pure definitions: schemas, types, constants; no logic
DAL files should be single-operation, snake_case, and return { success, data?, error? }
Services orchestrate DAL and enforce permissions; Actions call services, not DAL
Use split server/client components for hybrid needs and default to server components
Follow the naming conventions per layer to improve discoverability

Example use cases

Adding a new entity: create Zod schemas, DAL create/find/update/delete files, service logic, server actions, UI components, and page routes
Implementing an authenticated mutation: validate input in action, call service with permission checks, then revalidate cache
Refactoring validation: move inline checks into the Model layer using Zod and update services to rely on validated types
Creating a read-heavy endpoint: optimize DAL operations and keep services lightweight to minimize business-layer overhead
Building a reusable UI feature: place shared components under features/<feature>/components and keep feature utils isolated

FAQ

Why implement bottom-up?

Bottom-up ensures data shapes and DB operations are defined before business rules and UI, reducing iteration and preventing downstream changes.

Should services ever access the database directly?

No. Services should call DAL functions to keep database access centralized and maintain single-responsibility boundaries.