Prompt file imported from r4sheed/nextjs-intrasite (.github/prompts/feature-creation.prompt.md). Copyright stays with the author.

Feature Creation Guide

Name: feature-creation
Author: r4sheed

Quick Start

Create a new feature using the scaffolding script:

npm run feature:create <feature-name> [category]

Examples

# CRUD feature with domain model (default)
npm run feature:create posts
npm run feature:create posts crud

# Simple feature without domain model
npm run feature:create settings simple
npm run feature:create notifications simple

This automatically creates the complete folder structure following project guidelines.

Generated Structure

CRUD Category (with domain models)

src/features/<feature-name>/
├── actions/          # Server Actions (Next.js 'use server')
│   ├── index.ts      # Barrel exports
│   └── create-example.ts   # Example server action template
├── components/       # React components specific to this feature
│   └── example.tsx   # Example component template
├── data/             # Database/data access layer
│   └── example.ts    # Full CRUD operations template
├── models/           # Domain models (business entities) ⭐ CRUD only
│   └── index.ts      # Domain entity class with business logic
├── hooks/            # Custom React hooks
│   └── index.ts      # TanStack Query hook examples
├── lib/              # Utilities, errors, and constants
│   ├── errors.ts     # Feature-specific AppError factories
│   ├── strings.ts    # Error codes, messages, UI labels (i18n keys)
│   └── utils.ts      # Feature-specific utilities
├── schemas/          # Zod validation schemas
│   ├── index.ts      # Barrel exports
│   └── create-example.ts   # Example Zod schema
├── services/         # Business logic layer
│   ├── index.ts      # Barrel exports
│   └── create-example.ts   # Example service with model usage
├── types/            # TypeScript type definitions
│   └── index.ts      # Shared types
├── __tests__/        # Unit and integration tests
│   └── example.test.ts     # Example test template
└── README.md         # Feature documentation (category-specific)

src/locales/
├── en/<feature-name>.json   # English translations (pre-populated)
└── hu/<feature-name>.json   # Hungarian translations (pre-populated)

Simple Category (lightweight)

Same as CRUD, but without the models/ folder. Best for features that don't require complex domain logic or business entity representations.

Layer Responsibilities

Note: CRUD features include a models/ layer; simple features do not.

1. Actions Layer (`actions/`)

Purpose: Server Actions that handle form submissions and client requests

Rules:

✅ Always return Response<T>
✅ Validate input with Zod schemas (from schemas/)
✅ Call service layer for business logic
❌ Never throw errors (return response.error() instead)
❌ Never access database directly

Template includes: Example server action with validation and service call

Example:

// actions/create-bookmark.ts
'use server';

import { z } from 'zod';

import { validationFailed } from '@/lib/errors';
import { response, type Response } from '@/lib/response';

import {
  type CreateBookmarkInput,
  createBookmarkSchema,
} from '@/features/bookmarks/schemas';
import { createBookmark as createBookmarkService } from '@/features/bookmarks/services';

// actions/create-bookmark.ts

// actions/create-bookmark.ts

// actions/create-bookmark.ts

// actions/create-bookmark.ts

// actions/create-bookmark.ts

export type CreateBookmarkData = { id: string };

export const createBookmark = async (
  values: CreateBookmarkInput
): Promise<Response<CreateBookmarkData>> => {
  const validation = createBookmarkSchema.safeParse(values);

  if (!validation.success) {
    return response.failure(validationFailed(validation.error));
  }

  return await createBookmarkService(validation.data);
};

2. Services Layer (`services/`)

Purpose: Business logic and orchestration

Rules:

✅ Return Response<T>
✅ Call data layer for database operations
✅ Use domain models (CRUD features) for business logic
✅ Handle all business rules and validation
✅ Use try-catch for unexpected errors only
❌ Never throw domain errors (return response.error())

Template includes: Example service with model usage (CRUD) or direct data access (simple)

Example (CRUD with model):

// services/create-post.ts
import { internalServerError } from '@/lib/errors';
import { response, type Response } from '@/lib/response';

import { createPost as createPostData } from '@/features/posts/data/post';

import { Post } from '@/features/posts/models';

export const createPost = async (
  input: CreatePostInput
): Promise<Response<CreatePostData>> => {
  try {
    // 1. Validate business rules using domain model
    if (!Post.isValidTitle(input.title)) {
      return response.error(invalidTitle());
    }

    // 2. Create entity in database
    const postData = await createPostData(input);

    if (!postData) {
      return response.error(internalServerError());
    }

    // 3. Return success
    return response.success({ data: { id: postData.id } });
  } catch (error) {
    console.error('[createPostService]', error);
    return response.error(internalServerError());
  }
};

Example (simple without model):

// services/create-bookmark.ts
import { internalServerError } from '@/lib/errors';
import { response, type Response } from '@/lib/response';

import { createBookmark as createBookmarkData } from '@/features/bookmarks/data/bookmark';

import { type CreateBookmarkData } from '@/features/bookmarks/actions';

export const createBookmark = async (
  data: CreateBookmarkInput
): Promise<Response<CreateBookmarkData>> => {
  try {
    const bookmark = await createBookmarkData(data);

    if (!bookmark) {
      return response.error(internalServerError());
    }

    return response.success({ data: { id: bookmark.id } });
  } catch (error) {
    console.error('Create bookmark error:', error);
    return response.error(internalServerError());
  }
};

3. Data Layer (`data/`)

Purpose: Direct database access

Rules:

✅ Return null on errors (log them first)
✅ Pure data access functions only
✅ Log database errors to console
❌ Never throw errors
❌ No business logic

Template includes: Full CRUD operations (create, get, update, delete, list)

Example:

// data/bookmark.ts
import { db } from '@/lib/prisma';

export const createBookmark = async (data: CreateBookmarkInput) => {
  try {
    return await db.bookmark.create({ data });
  } catch (error) {
    console.error('[createBookmark] Database error:', error);
    return null;
  }
};

export const getBookmarkById = async (id: string) => {
  try {
    return await db.bookmark.findUnique({ where: { id } });
  } catch (error) {
    console.error('[getBookmarkById] Database error:', error);
    return null;
  }
};

export const updateBookmark = async (
  id: string,
  data: Partial<CreateBookmarkInput>
) => {
  try {
    return await db.bookmark.update({ where: { id }, data });
  } catch (error) {
    console.error('[updateBookmark] Database error:', error);
    return null;
  }
};

export const deleteBookmark = async (id: string) => {
  try {
    return await db.bookmark.delete({ where: { id } });
  } catch (error) {
    console.error('[deleteBookmark] Database error:', error);
    return null;
  }
};

export const getAllBookmarks = async () => {
  try {
    return await db.bookmark.findMany({
      orderBy: { createdAt: 'desc' },
    });
  } catch (error) {
    console.error('[getAllBookmarks] Database error:', error);
    return null;
  }
};

4. Models Layer (`models/`) - CRUD Category Only ⭐

Purpose: Domain entity classes with business logic

Rules:

✅ Class-based entity representations
✅ Contain core business logic and rules
✅ Validate entity state and invariants
✅ Transform between database and domain representations
❌ No database access (use data layer)
❌ No framework dependencies

Template includes: Complete domain model class with factory methods and business logic

Example:

// models/index.ts
import type { Post as PrismaPost } from '@prisma/client';

// Business rule constants
const MILLISECONDS_PER_DAY = 1000 * 60 * 60 * 24;
const DEFAULT_RECENT_DAYS = 7;
const MIN_TITLE_LENGTH = 3;
const MAX_TITLE_LENGTH = 200;

/**
 * Post domain entity
 * Wraps database entity with business logic
 */
export class Post {
  private constructor(
    public readonly id: string,
    public readonly title: string,
    public readonly content: string,
    public readonly published: boolean,
    public readonly createdAt: Date,
    public readonly updatedAt: Date
  ) {}

  /**
   * Create a new Post instance from database entity
   */
  static fromDatabase(data: PrismaPost): Post {
    return new Post(
      data.id,
      data.title,
      data.content,
      data.published,
      data.createdAt,
      data.updatedAt
    );
  }

  /**
   * Convert to database representation
   */
  toDatabase(): Omit<PrismaPost, 'id' | 'createdAt' | 'updatedAt'> {
    return {
      title: this.title,
      content: this.content,
      published: this.published,
    };
  }

  /**
   * Business logic: Check if post is recent
   */
  isRecent(days: number = DEFAULT_RECENT_DAYS): boolean {
    const daysSinceCreation =
      (Date.now() - this.createdAt.getTime()) / MILLISECONDS_PER_DAY;
    return daysSinceCreation <= days;
  }

  /**
   * Business logic: Validate title
   */
  static isValidTitle(title: string): boolean {
    const trimmedLength = title.trim().length;
    return (
      trimmedLength >= MIN_TITLE_LENGTH && trimmedLength <= MAX_TITLE_LENGTH
    );
  }

  /**
   * Business logic: Publish post
   */
  publish(): Post {
    return new Post(
      this.id,
      this.title,
      this.content,
      true,
      this.createdAt,
      new Date()
    );
  }
}

When to use models:

✅ Complex business rules (order calculations, post publishing, user roles)
✅ Entity state validation (email formats, price ranges, status transitions)
✅ Transformations between layers (API ↔ database ↔ domain)
❌ Simple CRUD with no business logic (use simple category)

5. Schemas Layer (`schemas/`)

Purpose: Zod validation schemas and input types

Rules:

✅ Use Zod for runtime validation
✅ Export schema and inferred type
✅ Use i18n keys for error messages
❌ No business logic

Template includes: Example Zod schema with i18n error messages

Example:

// schemas/create-bookmark.ts
import { z } from 'zod';

import { BOOKMARK_ERRORS } from '@/features/bookmarks/lib/strings';

export const createBookmarkSchema = z.object({
  title: z.string().min(1, { message: BOOKMARK_ERRORS.titleRequired }),
  url: z.string().url({ message: BOOKMARK_ERRORS.invalidUrl }),
});

export type CreateBookmarkInput = z.infer<typeof createBookmarkSchema>;

6. Lib Layer (`lib/`)

Purpose: Feature-specific utilities, errors, and constants

Files:

strings.ts - All string constants (codes, messages, labels)
errors.ts - AppError factory functions
utils.ts - Feature-specific helper functions

Template includes: Complete strings.ts with all constant categories, error factories, and utility placeholder

Example (lib/strings.ts):

// lib/strings.ts

// Note: For kebab-case feature names (e.g., user-settings):
// - Constant name: USER_SETTINGS_CODES (UPPER_SNAKE_CASE)
// - i18n keys: user-settings.errors.not-found (kebab-case)
// - Prisma model: userSettings (camelCase)

export const BOOKMARK_CODES = {
  notFound: 'not-found',
  invalidUrl: 'invalid-url',
  titleRequired: 'title-required',
} as const;

export type BookmarkCode = (typeof BOOKMARK_CODES)[keyof typeof BOOKMARK_CODES];

export const BOOKMARK_ERRORS = {
  notFound: 'bookmarks.errors.not-found',
  invalidUrl: 'bookmarks.errors.invalid-url',
  titleRequired: 'bookmarks.errors.title-required',
} as const;

export const BOOKMARK_SUCCESS = {
  created: 'bookmarks.success.created',
  updated: 'bookmarks.success.updated',
  deleted: 'bookmarks.success.deleted',
} as const;

export const BOOKMARK_LABELS = {
  title: 'bookmarks.labels.title',
  createButton: 'bookmarks.labels.create-button',
} as const;

Example (lib/errors.ts):

import { AppError } from '@/lib/errors';
import { HTTP_STATUS } from '@/lib/http-status';

import { BOOKMARK_CODES, BOOKMARK_ERRORS } from './strings';

export const bookmarkNotFound = (id: string) =>
  new AppError({
    code: BOOKMARK_CODES.notFound,
    message: { key: BOOKMARK_ERRORS.notFound, params: { id } },
    httpStatus: HTTP_STATUS.NOT_FOUND,
  });

Naming Conventions

Files

kebab-case for all files: create-bookmark.ts, bookmark-list.tsx

Functions & Variables

camelCase for functions: createBookmark, getBookmarkById
camelCase for variables: bookmarkData, userId

Types & Interfaces

PascalCase for types: CreateBookmarkData, BookmarkInput

Constants

SCREAMING_SNAKE_CASE for primitives: const MAX_BOOKMARKS = 100
camelCase for objects/arrays: const bookmarkRoutes = [...]

camelCase properties with kebab-case values:

const BOOKMARK_CODES = {
  notFound: 'not-found', // property: camelCase, value: kebab-case
} as const;

i18n Setup

After creating a feature, add translations:

src/locales/en/<feature-name>.json:

{
  "bookmarks": {
    "errors": {
      "not-found": "Bookmark not found",
      "invalid-url": "Please enter a valid URL"
    },
    "success": {
      "created": "Bookmark created successfully",
      "updated": "Bookmark updated"
    },
    "labels": {
      "title": "Bookmarks",
      "create-button": "Create Bookmark"
    }
  }
}

Testing

Write tests in __tests__/ directory:

// __tests__/create-bookmark.test.ts
import { describe, expect, it } from 'vitest';

import { Status } from '@/lib/response';

import { createBookmark } from '../actions';

describe('createBookmark', () => {
  it('should create bookmark with valid data', async () => {
    const result = await createBookmark({
      title: 'Test',
      url: 'https://example.com',
    });

    expect(result.status).toBe(Status.Success);
    if (result.status === Status.Success) {
      expect(result.data).toHaveProperty('id');
    }
  });
});

Checklist

After generating a feature:

1. Database Setup

Add Prisma schema model to prisma/schema.prisma
Run migration: npx prisma migrate dev --name create-<feature>
Verify database structure

2. Translations

Review generated src/locales/en/<feature>.json
Review generated src/locales/hu/<feature>.json
Add more translations: npm run i18n:add <feature>.errors.custom "Text" "Szöveg"
Validate i18n files: npm run i18n:validate

3. Implementation

Data layer: Customize CRUD operations in data/example.ts
Models layer (CRUD only): Implement business logic in models/index.ts
Schemas: Define validation rules in schemas/create-example.ts
Services: Implement business logic in services/create-example.ts
Actions: Customize server actions in actions/create-example.ts
Error handling: Add domain-specific errors in lib/errors.ts
String constants: Expand codes/messages in lib/strings.ts

4. UI & Integration

Build UI components in components/
Create custom hooks in hooks/ (TanStack Query)
Update feature README.md with usage examples
Add route handlers if needed

5. Testing & Validation

Write tests in __tests__/
Run tests: npm test
Run type check: npm run typecheck
Test end-to-end functionality

6. Cleanup

Remove example files if not needed:
- data/example.ts → rename to actual entity (e.g., bookmark.ts)
- actions/create-example.ts → rename to actual action
- services/create-example.ts → rename to actual service
- etc.
Update barrel exports in index.ts files

Category Decision Guide

Choose CRUD when:

✅ Complex business rules (pricing, permissions, workflows)
✅ Entity state management (published/draft, active/inactive)
✅ Domain transformations (API ↔ database ↔ UI)
✅ Reusable business logic across multiple features
✅ Examples: posts, products, orders, bookmarks, users

Choose Simple when:

✅ Basic CRUD with minimal logic
✅ Configuration or settings storage
✅ Simple data transformations
✅ No complex business rules
✅ Examples: settings, notifications, preferences, tags

Retrofitting Existing Features with Models

Older features (like auth) may not have a models/ folder. Here's when and how to add one:

When to Add Models to Existing Features

✅ Add models when you find:

Business Logic in Data Layer

// ❌ BAD: Business logic (bcrypt) in data layer
export const verifyUserCredentials = async (
  email: string,
  password: string
) => {
  const user = await getUserByEmail(email);
  const isValid = await bcrypt.compare(password, user.password); // Business logic!
  return isValid ? user : null;
};

Business Logic in Services

// ❌ BAD: Password hashing scattered in multiple services
export const registerUser = async (values: RegisterInput) => {
  const hashedPassword = await bcrypt.hash(password, 10); // Duplication!
  // ...
};

Domain Validation Scattered

// ❌ BAD: Email validation copy-pasted across files
if (!email.includes('@')) return error(); // Scattered validation

❌ Don't add models when:

Feature has simple CRUD with no complex business logic
Data layer only does database access (no transformations/validation)
Services only orchestrate calls (no domain logic)

Migration Example: Auth Feature

See docs/auth-user-model-migration.md for complete case study.

Summary:

// Before: Business logic in data/services
// data/user.ts
export const verifyUserCredentials = async (email, password) => {
  const user = await getUserByEmail(email);
  const isValid = await bcrypt.compare(password, user.password); // ❌ Business logic
  return isValid ? user : null;
};

// services/register-user.ts
const hashedPassword = await bcrypt.hash(password, BCRYPT_SALT_ROUNDS); // ❌ Business logic

// After: Business logic in User model
// models/user.ts
export class User {
  async verifyPassword(plainPassword: string): Promise<boolean> {
    return await bcrypt.compare(plainPassword, this.data.password);
  }

  static async hashPassword(plainPassword: string): Promise<string> {
    return await bcrypt.hash(plainPassword, BCRYPT_SALT_ROUNDS);
  }
}

// data/user.ts - Pure database access
export const verifyUserCredentials = async (email, password) => {
  const prismaUser = await getUserByEmail(email);
  if (!prismaUser) return null;

  const user = new User(prismaUser); // ✅ Use model
  const isValid = await user.verifyPassword(password);
  return isValid ? user.toSafeObject() : null;
};

// services/register-user.ts - Uses model
const hashedPassword = await User.hashPassword(password); // ✅ Use model

Retrofit Checklist

Identify business logic in data/services layers
Create models/ folder
Create domain entity class (e.g., User, Post)
Move business logic to model methods
Update data layer to use model for business operations
Update services to use model static methods
Rename Prisma type imports: User → User as PrismaUser
Run tests to ensure no regressions
Create migration documentation

Guidelines Reference

Error Handling: ../.github/instructions/error-handling-guidelines.instructions.md
Naming: ../.github/instructions/naming-conventions.instructions.md
Messages & Codes: ../.github/instructions/messages-and-codes.instructions.md
Next.js Patterns: ../.github/instructions/nextjs.instructions.md
TypeScript: ../.github/instructions/typescript-5-es2022.instructions.md
Governance: ../.github/instructions/guidelines-governance.instructions.md
i18n Management: i18n-management.prompt.md

# Feature Creation Guide ## Quick Start Create a new feature using the scaffolding script: ```bash npm run feature:create <feature-name> [category] ``` ### Categories - **`crud`** (default): Full CRUD operations with domain models - Use for: posts, products, bookmarks, users, orders - Includes: `models/` folder with business entity classes - Template: Complete CRUD data layer + domain model examples - **`simple`**: Lightweight features without domain models - Use for: settings, notifications, preferences, utilities - Excludes: `models/` folder (no complex domain logic needed) - Template: Basic service and data layer examples ### Examples ```bash # CRUD feature with domain model (default) npm run feature:create posts npm run feature:create posts crud # Simple feature without domain model npm run feature:create settings simple npm run feature:create notifications simple ``` This automatically creates the complete folder structure following project guidelines. --- ## Generated Structure ### CRUD Category (with domain models) ``` src/features/<feature-name>/ ├── actions/ # Server Actions (Next.js 'use server') │ ├── index.ts # Barrel exports │ └── create-example.ts # Example server action template ├── components/ # React components specific to this feature │ └── example.tsx # Example component template ├── data/ # Database/data access layer │ └── example.ts # Full CRUD operations template ├── models/ # Domain models (business entities) ⭐ CRUD only │ └── index.ts # Domain entity class with business logic ├── hooks/ # Custom React hooks │ └── index.ts # TanStack Query hook examples ├── lib/ # Utilities, errors, and constants │ ├── errors.ts # Feature-specific AppError factories │ ├── strings.ts # Error codes, messages, UI labels (i18n keys) │ └── utils.ts # Feature-specific utilities ├── schemas/ # Zod validation schemas │ ├── index.ts # Barrel exports │ └── create-example.ts # Example Zod schema ├── services/ # Business logic layer │ ├── index.ts # Barrel exports │ └── create-example.ts # Example service with model usage ├── types/ # TypeScript type definitions │ └── index.ts # Shared types ├── __tests__/ # Unit and integration tests │ └── example.test.ts # Example test template └── README.md # Feature documentation (category-specific) src/locales/ ├── en/<feature-name>.json # English translations (pre-populated) └── hu/<feature-name>.json # Hungarian translations (pre-populated) ``` ### Simple Category (lightweight) Same as CRUD, but **without** the `models/` folder. Best for features that don't require complex domain logic or business entity representations. --- ## Layer Responsibilities > **Note:** CRUD features include a `models/` layer; simple features do not. ### 1. **Actions Layer** (`actions/`) **Purpose:** Server Actions that handle form submissions and client requests **Rules:** - ✅ Always return `Response<T>` - ✅ Validate input with Zod schemas (from `schemas/`) - ✅ Call service layer for business logic - ❌ Never throw errors (return `response.error()` instead) - ❌ Never access database directly **Template includes:** Example server action with validation and service call **Example:** ```typescript // actions/create-bookmark.ts 'use server'; import { z } from 'zod'; import { validationFailed } from '@/lib/errors'; import { response, type Response } from '@/lib/response'; import { type CreateBookmarkInput, createBookmarkSchema, } from '@/features/bookmarks/schemas'; import { createBookmark as createBookmarkService } from '@/features/bookmarks/services'; // actions/create-bookmark.ts // actions/create-bookmark.ts // actions/create-bookmark.ts // actions/create-bookmark.ts // actions/create-bookmark.ts export type CreateBookmarkData = { id: string }; export const createBookmark = async ( values: CreateBookmarkInput ): Promise<Response<CreateBookmarkData>> => { const validation = createBookmarkSchema.safeParse(values); if (!validation.success) { return response.failure(validationFailed(validation.error)); } return await createBookmarkService(validation.data); }; ``` ### 2. **Services Layer** (`services/`) **Purpose:** Business logic and orchestration **Rules:** - ✅ Return `Response<T>` - ✅ Call data layer for database operations - ✅ Use domain models (CRUD features) for business logic - ✅ Handle all business rules and validation - ✅ Use try-catch for unexpected errors only - ❌ Never throw domain errors (return `response.error()`) **Template includes:** Example service with model usage (CRUD) or direct data access (simple) **Example (CRUD with model):** ```typescript // services/create-post.ts import { internalServerError } from '@/lib/errors'; import { response, type Response } from '@/lib/response'; import { createPost as createPostData } from '@/features/posts/data/post'; import { Post } from '@/features/posts/models'; export const createPost = async ( input: CreatePostInput ): Promise<Response<CreatePostData>> => { try { // 1. Validate business rules using domain model if (!Post.isValidTitle(input.title)) { return response.error(invalidTitle()); } // 2. Create entity in database const postData = await createPostData(input); if (!postData) { return response.error(internalServerError()); } // 3. Return success return response.success({ data: { id: postData.id } }); } catch (error) { console.error('[createPostService]', error); return response.error(internalServerError()); } }; ``` **Example (simple without model):** ```typescript // services/create-bookmark.ts import { internalServerError } from '@/lib/errors'; import { response, type Response } from '@/lib/response'; import { createBookmark as createBookmarkData } from '@/features/bookmarks/data/bookmark'; import { type CreateBookmarkData } from '@/features/bookmarks/actions'; export const createBookmark = async ( data: CreateBookmarkInput ): Promise<Response<CreateBookmarkData>> => { try { const bookmark = await createBookmarkData(data); if (!bookmark) { return response.error(internalServerError()); } return response.success({ data: { id: bookmark.id } }); } catch (error) { console.error('Create bookmark error:', error); return response.error(internalServerError()); } }; ``` ### 3. **Data Layer** (`data/`) **Purpose:** Direct database access **Rules:** - ✅ Return `null` on errors (log them first) - ✅ Pure data access functions only - ✅ Log database errors to console - ❌ Never throw errors - ❌ No business logic **Template includes:** Full CRUD operations (create, get, update, delete, list) **Example:** ```typescript // data/bookmark.ts import { db } from '@/lib/prisma'; export const createBookmark = async (data: CreateBookmarkInput) => { try { return await db.bookmark.create({ data }); } catch (error) { console.error('[createBookmark] Database error:', error); return null; } }; export const getBookmarkById = async (id: string) => { try { return await db.bookmark.findUnique({ where: { id } }); } catch (error) { console.error('[getBookmarkById] Database error:', error); return null; } }; export const updateBookmark = async ( id: string, data: Partial<CreateBookmarkInput> ) => { try { return await db.bookmark.update({ where: { id }, data }); } catch (error) { console.error('[updateBookmark] Database error:', error); return null; } }; export const deleteBookmark = async (id: string) => { try { return await db.bookmark.delete({ where: { id } }); } catch (error) { console.error('[deleteBookmark] Database error:', error); return null; } }; export const getAllBookmarks = async () => { try { return await db.bookmark.findMany({ orderBy: { createdAt: 'desc' }, }); } catch (error) { console.error('[getAllBookmarks] Database error:', error); return null; } }; ``` ### 4. **Models Layer** (`models/`) - CRUD Category Only ⭐ **Purpose:** Domain entity classes with business logic **Rules:** - ✅ Class-based entity representations - ✅ Contain core business logic and rules - ✅ Validate entity state and invariants - ✅ Transform between database and domain representations - ❌ No database access (use data layer) - ❌ No framework dependencies **Template includes:** Complete domain model class with factory methods and business logic **Example:** ```typescript // models/index.ts import type { Post as PrismaPost } from '@prisma/client'; // Business rule constants const MILLISECONDS_PER_DAY = 1000 * 60 * 60 * 24; const DEFAULT_RECENT_DAYS = 7; const MIN_TITLE_LENGTH = 3; const MAX_TITLE_LENGTH = 200; /** * Post domain entity * Wraps database entity with business logic */ export class Post { private constructor( public readonly id: string, public readonly title: string, public readonly content: string, public readonly published: boolean, public readonly createdAt: Date, public readonly updatedAt: Date ) {} /** * Create a new Post instance from database entity */ static fromDatabase(data: PrismaPost): Post { return new Post( data.id, data.title, data.content, data.published, data.createdAt, data.updatedAt ); } /** * Convert to database representation */ toDatabase(): Omit<PrismaPost, 'id' | 'createdAt' | 'updatedAt'> { return { title: this.title, content: this.content, published: this.published, }; } /** * Business logic: Check if post is recent */ isRecent(days: number = DEFAULT_RECENT_DAYS): boolean { const daysSinceCreation = (Date.now() - this.createdAt.getTime()) / MILLISECONDS_PER_DAY; return daysSinceCreation <= days; } /** * Business logic: Validate title */ static isValidTitle(title: string): boolean { const trimmedLength = title.trim().length; return ( trimmedLength >= MIN_TITLE_LENGTH && trimmedLength <= MAX_TITLE_LENGTH ); } /** * Business logic: Publish post */ publish(): Post { return new Post( this.id, this.title, this.content, true, this.createdAt, new Date() ); } } ``` **When to use models:** - ✅ Complex business rules (order calculations, post publishing, user roles) - ✅ Entity state validation (email formats, price ranges, status transitions) - ✅ Transformations between layers (API ↔ database ↔ domain) - ❌ Simple CRUD with no business logic (use simple category) ### 5. **Schemas Layer** (`schemas/`) **Purpose:** Zod validation schemas and input types **Rules:** - ✅ Use Zod for runtime validation - ✅ Export schema and inferred type - ✅ Use i18n keys for error messages - ❌ No business logic **Template includes:** Example Zod schema with i18n error messages **Example:** ```typescript // schemas/create-bookmark.ts import { z } from 'zod'; import { BOOKMARK_ERRORS } from '@/features/bookmarks/lib/strings'; export const createBookmarkSchema = z.object({ title: z.string().min(1, { message: BOOKMARK_ERRORS.titleRequired }), url: z.string().url({ message: BOOKMARK_ERRORS.invalidUrl }), }); export type CreateBookmarkInput = z.infer<typeof createBookmarkSchema>; ``` ### 6. **Lib Layer** (`lib/`) **Purpose:** Feature-specific utilities, errors, and constants **Files:** - `strings.ts` - All string constants (codes, messages, labels) - `errors.ts` - AppError factory functions - `utils.ts` - Feature-specific helper functions **Template includes:** Complete strings.ts with all constant categories, error factories, and utility placeholder **Example (`lib/strings.ts`):** ```typescript // lib/strings.ts // Note: For kebab-case feature names (e.g., user-settings): // - Constant name: USER_SETTINGS_CODES (UPPER_SNAKE_CASE) // - i18n keys: user-settings.errors.not-found (kebab-case) // - Prisma model: userSettings (camelCase) export const BOOKMARK_CODES = { notFound: 'not-found', invalidUrl: 'invalid-url', titleRequired: 'title-required', } as const; export type BookmarkCode = (typeof BOOKMARK_CODES)[keyof typeof BOOKMARK_CODES]; export const BOOKMARK_ERRORS = { notFound: 'bookmarks.errors.not-found', invalidUrl: 'bookmarks.errors.invalid-url', titleRequired: 'bookmarks.errors.title-required', } as const; export const BOOKMARK_SUCCESS = { created: 'bookmarks.success.created', updated: 'bookmarks.success.updated', deleted: 'bookmarks.success.deleted', } as const; export const BOOKMARK_LABELS = { title: 'bookmarks.labels.title', createButton: 'bookmarks.labels.create-button', } as const; ``` **Example (`lib/errors.ts`):** ```typescript import { AppError } from '@/lib/errors'; import { HTTP_STATUS } from '@/lib/http-status'; import { BOOKMARK_CODES, BOOKMARK_ERRORS } from './strings'; export const bookmarkNotFound = (id: string) => new AppError({ code: BOOKMARK_CODES.notFound, message: { key: BOOKMARK_ERRORS.notFound, params: { id } }, httpStatus: HTTP_STATUS.NOT_FOUND, }); ``` --- ## Naming Conventions ### Files - **kebab-case** for all files: `create-bookmark.ts`, `bookmark-list.tsx` ### Functions & Variables - **camelCase** for functions: `createBookmark`, `getBookmarkById` - **camelCase** for variables: `bookmarkData`, `userId` ### Types & Interfaces - **PascalCase** for types: `CreateBookmarkData`, `BookmarkInput` ### Constants - **SCREAMING_SNAKE_CASE** for primitives: `const MAX_BOOKMARKS = 100` - **camelCase** for objects/arrays: `const bookmarkRoutes = [...]` - **camelCase properties** with **kebab-case values**: ```typescript const BOOKMARK_CODES = { notFound: 'not-found', // property: camelCase, value: kebab-case } as const; ``` --- ## i18n Setup After creating a feature, add translations: **`src/locales/en/<feature-name>.json`:** ```json { "bookmarks": { "errors": { "not-found": "Bookmark not found", "invalid-url": "Please enter a valid URL" }, "success": { "created": "Bookmark created successfully", "updated": "Bookmark updated" }, "labels": { "title": "Bookmarks", "create-button": "Create Bookmark" } } } ``` --- ## Testing Write tests in `__tests__/` directory: ```typescript // __tests__/create-bookmark.test.ts import { describe, expect, it } from 'vitest'; import { Status } from '@/lib/response'; import { createBookmark } from '../actions'; describe('createBookmark', () => { it('should create bookmark with valid data', async () => { const result = await createBookmark({ title: 'Test', url: 'https://example.com', }); expect(result.status).toBe(Status.Success); if (result.status === Status.Success) { expect(result.data).toHaveProperty('id'); } }); }); ``` --- ## Checklist After generating a feature: ### 1. Database Setup - [ ] Add Prisma schema model to `prisma/schema.prisma` - [ ] Run migration: `npx prisma migrate dev --name create-<feature>` - [ ] Verify database structure ### 2. Translations - [ ] Review generated `src/locales/en/<feature>.json` - [ ] Review generated `src/locales/hu/<feature>.json` - [ ] Add more translations: `npm run i18n:add <feature>.errors.custom "Text" "Szöveg"` - [ ] Validate i18n files: `npm run i18n:validate` ### 3. Implementation - [ ] **Data layer**: Customize CRUD operations in `data/example.ts` - [ ] **Models layer** (CRUD only): Implement business logic in `models/index.ts` - [ ] **Schemas**: Define validation rules in `schemas/create-example.ts` - [ ] **Services**: Implement business logic in `services/create-example.ts` - [ ] **Actions**: Customize server actions in `actions/create-example.ts` - [ ] **Error handling**: Add domain-specific errors in `lib/errors.ts` - [ ] **String constants**: Expand codes/messages in `lib/strings.ts` ### 4. UI & Integration - [ ] Build UI components in `components/` - [ ] Create custom hooks in `hooks/` (TanStack Query) - [ ] Update feature `README.md` with usage examples - [ ] Add route handlers if needed ### 5. Testing & Validation - [ ] Write tests in `__tests__/` - [ ] Run tests: `npm test` - [ ] Run type check: `npm run typecheck` - [ ] Test end-to-end functionality ### 6. Cleanup - [ ] Remove example files if not needed: - `data/example.ts` → rename to actual entity (e.g., `bookmark.ts`) - `actions/create-example.ts` → rename to actual action - `services/create-example.ts` → rename to actual service - etc. - [ ] Update barrel exports in `index.ts` files --- ## Category Decision Guide **Choose CRUD when:** - ✅ Complex business rules (pricing, permissions, workflows) - ✅ Entity state management (published/draft, active/inactive) - ✅ Domain transformations (API ↔ database ↔ UI) - ✅ Reusable business logic across multiple features - ✅ Examples: posts, products, orders, bookmarks, users **Choose Simple when:** - ✅ Basic CRUD with minimal logic - ✅ Configuration or settings storage - ✅ Simple data transformations - ✅ No complex business rules - ✅ Examples: settings, notifications, preferences, tags --- ## Retrofitting Existing Features with Models Older features (like `auth`) may not have a `models/` folder. Here's when and how to add one: ### When to Add Models to Existing Features **✅ Add models when you find:** 1. **Business Logic in Data Layer** ```typescript // ❌ BAD: Business logic (bcrypt) in data layer export const verifyUserCredentials = async ( email: string, password: string ) => { const user = await getUserByEmail(email); const isValid = await bcrypt.compare(password, user.password); // Business logic! return isValid ? user : null; }; ``` 2. **Business Logic in Services** ```typescript // ❌ BAD: Password hashing scattered in multiple services export const registerUser = async (values: RegisterInput) => { const hashedPassword = await bcrypt.hash(password, 10); // Duplication! // ... }; ``` 3. **Domain Validation Scattered** ```typescript // ❌ BAD: Email validation copy-pasted across files if (!email.includes('@')) return error(); // Scattered validation ``` **❌ Don't add models when:** 1. Feature has simple CRUD with no complex business logic 2. Data layer only does database access (no transformations/validation) 3. Services only orchestrate calls (no domain logic) ### Migration Example: Auth Feature See `docs/auth-user-model-migration.md` for complete case study. **Summary:** ```typescript // Before: Business logic in data/services // data/user.ts export const verifyUserCredentials = async (email, password) => { const user = await getUserByEmail(email); const isValid = await bcrypt.compare(password, user.password); // ❌ Business logic return isValid ? user : null; }; // services/register-user.ts const hashedPassword = await bcrypt.hash(password, BCRYPT_SALT_ROUNDS); // ❌ Business logic // After: Business logic in User model // models/user.ts export class User { async verifyPassword(plainPassword: string): Promise<boolean> { return await bcrypt.compare(plainPassword, this.data.password); } static async hashPassword(plainPassword: string): Promise<string> { return await bcrypt.hash(plainPassword, BCRYPT_SALT_ROUNDS); } } // data/user.ts - Pure database access export const verifyUserCredentials = async (email, password) => { const prismaUser = await getUserByEmail(email); if (!prismaUser) return null; const user = new User(prismaUser); // ✅ Use model const isValid = await user.verifyPassword(password); return isValid ? user.toSafeObject() : null; }; // services/register-user.ts - Uses model const hashedPassword = await User.hashPassword(password); // ✅ Use model ``` ### Retrofit Checklist - [ ] I

{ "prompt": "# Feature Creation Guide\n\n## Quick Start\n\nCreate a new feature using the scaffolding script:\n\n```bash\nnpm run feature:create <feature-name> [category]\n```\n\n### Categories\n\n- **`crud`** (default): Full CRUD operations with domain models\n - Use for: posts, products, bookmarks, users, orders\n - Includes: `models/` folder with business entity classes\n - Template: Complete CRUD data layer + domain model examples\n\n- **`simple`**: Lightweight features without domain models\n - Use for: settings, notifications, preferences, utilities\n - Excludes: `models/` folder (no complex domain logic needed)\n - Template: Basic service and data layer examples\n\n### Examples\n\n```bash\n# CRUD feature with domain model (default)\nnpm run feature:create posts\nnpm run feature:create posts crud\n\n# Simple feature without domain model\nnpm run feature:create settings simple\nnpm run feature:create notifications simple\n```\n\nThis automatically creates the complete folder structure following project guidelines.\n\n---\n\n## Generated Structure\n\n### CRUD Category (with domain models)\n\n```\nsrc/features/<feature-name>/\n├── actions/ # Server Actions (Next.js 'use server')\n│ ├── index.ts # Barrel exports\n│ └── create-example.ts # Example server action template\n├── components/ # React components specific to this feature\n│ └── example.tsx # Example component template\n├── data/ # Database/data access layer\n│ └── example.ts # Full CRUD operations template\n├── models/ # Domain models (business entities) ⭐ CRUD only\n│ └── index.ts # Domain entity class with business logic\n├── hooks/ # Custom React hooks\n│ └── index.ts # TanStack Query hook examples\n├── lib/ # Utilities, errors, and constants\n│ ├── errors.ts # Feature-specific AppError factories\n│ ├── strings.ts # Error codes, messages, UI labels (i18n keys)\n│ └── utils.ts # Feature-specific utilities\n├── schemas/ # Zod validation schemas\n│ ├── index.ts # Barrel exports\n│ └── create-example.ts # Example Zod schema\n├── services/ # Business logic layer\n│ ├── index.ts # Barrel exports\n│ └── create-example.ts # Example service with model usage\n├── types/ # TypeScript type definitions\n│ └── index.ts # Shared types\n├── __tests__/ # Unit and integration tests\n│ └── example.test.ts # Example test template\n└── README.md # Feature documentation (category-specific)\n\nsrc/locales/\n├── en/<feature-name>.json # English translations (pre-populated)\n└── hu/<feature-name>.json # Hungarian translations (pre-populated)\n```\n\n### Simple Category (lightweight)\n\nSame as CRUD, but **without** the `models/` folder. Best for features that don't require complex domain logic or business entity representations.\n\n---\n\n## Layer Responsibilities\n\n> **Note:** CRUD features include a `models/` layer; simple features do not.\n\n### 1. **Actions Layer** (`actions/`)\n\n**Purpose:** Server Actions that handle form submissions and client requests\n\n**Rules:**\n\n- ✅ Always return `Response<T>`\n- ✅ Validate input with Zod schemas (from `schemas/`)\n- ✅ Call service layer for business logic\n- ❌ Never throw errors (return `response.error()` instead)\n- ❌ Never access database directly\n\n**Template includes:** Example server action with validation and service call\n\n**Example:**\n\n```typescript\n// actions/create-bookmark.ts\n'use server';\n\nimport { z } from 'zod';\n\nimport { validationFailed } from '@/lib/errors';\nimport { response, type Response } from '@/lib/response';\n\nimport {\n type CreateBookmarkInput,\n createBookmarkSchema,\n} from '@/features/bookmarks/schemas';\nimport { createBookmark as createBookmarkService } from '@/features/bookmarks/services';\n\n// actions/create-bookmark.ts\n\n// actions/create-bookmark.ts\n\n// actions/create-bookmark.ts\n\n// actions/create-bookmark.ts\n\n// actions/create-bookmark.ts\n\nexport type CreateBookmarkData = { id: string };\n\nexport const createBookmark = async (\n values: CreateBookmarkInput\n): Promise<Response<CreateBookmarkData>> => {\n const validation = createBookmarkSchema.safeParse(values);\n\n if (!validation.success) {\n return response.failure(validationFailed(validation.error));\n }\n\n return await createBookmarkService(validation.data);\n};\n```\n\n### 2. **Services Layer** (`services/`)\n\n**Purpose:** Business logic and orchestration\n\n**Rules:**\n\n- ✅ Return `Response<T>`\n- ✅ Call data layer for database operations\n- ✅ Use domain models (CRUD features) for business logic\n- ✅ Handle all business rules and validation\n- ✅ Use try-catch for unexpected errors only\n- ❌ Never throw domain errors (return `response.error()`)\n\n**Template includes:** Example service with model usage (CRUD) or direct data access (simple)\n\n**Example (CRUD with model):**\n\n```typescript\n// services/create-post.ts\nimport { internalServerError } from '@/lib/errors';\nimport { response, type Response } from '@/lib/response';\n\nimport { createPost as createPostData } from '@/features/posts/data/post';\n\nimport { Post } from '@/features/posts/models';\n\nexport const createPost = async (\n input: CreatePostInput\n): Promise<Response<CreatePostData>> => {\n try {\n // 1. Validate business rules using domain model\n if (!Post.isValidTitle(input.title)) {\n return response.error(invalidTitle());\n }\n\n // 2. Create entity in database\n const postData = await createPostData(input);\n\n if (!postData) {\n return response.error(internalServerError());\n }\n\n // 3. Return success\n return response.success({ data: { id: postData.id } });\n } catch (error) {\n console.error('[createPostService]', error);\n return response.error(internalServerError());\n }\n};\n```\n\n**Example (simple without model):**\n\n```typescript\n// services/create-bookmark.ts\nimport { internalServerError } from '@/lib/errors';\nimport { response, type Response } from '@/lib/response';\n\nimport { createBookmark as createBookmarkData } from '@/features/bookmarks/data/bookmark';\n\nimport { type CreateBookmarkData } from '@/features/bookmarks/actions';\n\nexport const createBookmark = async (\n data: CreateBookmarkInput\n): Promise<Response<CreateBookmarkData>> => {\n try {\n const bookmark = await createBookmarkData(data);\n\n if (!bookmark) {\n return response.error(internalServerError());\n }\n\n return response.success({ data: { id: bookmark.id } });\n } catch (error) {\n console.error('Create bookmark error:', error);\n return response.error(internalServerError());\n }\n};\n```\n\n### 3. **Data Layer** (`data/`)\n\n**Purpose:** Direct database access\n\n**Rules:**\n\n- ✅ Return `null` on errors (log them first)\n- ✅ Pure data access functions only\n- ✅ Log database errors to console\n- ❌ Never throw errors\n- ❌ No business logic\n\n**Template includes:** Full CRUD operations (create, get, update, delete, list)\n\n**Example:**\n\n```typescript\n// data/bookmark.ts\nimport { db } from '@/lib/prisma';\n\nexport const createBookmark = async (data: CreateBookmarkInput) => {\n try {\n return await db.bookmark.create({ data });\n } catch (error) {\n console.error('[createBookmark] Database error:', error);\n return null;\n }\n};\n\nexport const getBookmarkById = async (id: string) => {\n try {\n return await db.bookmark.findUnique({ where: { id } });\n } catch (error) {\n console.error('[getBookmarkById] Database error:', error);\n return null;\n }\n};\n\nexport const updateBookmark = async (\n id: string,\n data: Partial<CreateBookmarkInput>\n) => {\n try {\n return await db.bookmark.update({ where: { id }, data });\n } catch (error) {\n console.error('[updateBookmark] Database error:', error);\n return null;\n }\n};\n\nexport const deleteBookmark = async (id: string) => {\n try {\n return await db.bookmark.delete({ where: { id } });\n } catch (error) {\n console.error('[deleteBookmark] Database error:', error);\n return null;\n }\n};\n\nexport const getAllBookmarks = async () => {\n try {\n return await db.bookmark.findMany({\n orderBy: { createdAt: 'desc' },\n });\n } catch (error) {\n console.error('[getAllBookmarks] Database error:', error);\n return null;\n }\n};\n```\n\n### 4. **Models Layer** (`models/`) - CRUD Category Only ⭐\n\n**Purpose:** Domain entity classes with business logic\n\n**Rules:**\n\n- ✅ Class-based entity representations\n- ✅ Contain core business logic and rules\n- ✅ Validate entity state and invariants\n- ✅ Transform between database and domain representations\n- ❌ No database access (use data layer)\n- ❌ No framework dependencies\n\n**Template includes:** Complete domain model class with factory methods and business logic\n\n**Example:**\n\n```typescript\n// models/index.ts\nimport type { Post as PrismaPost } from '@prisma/client';\n\n// Business rule constants\nconst MILLISECONDS_PER_DAY = 1000 * 60 * 60 * 24;\nconst DEFAULT_RECENT_DAYS = 7;\nconst MIN_TITLE_LENGTH = 3;\nconst MAX_TITLE_LENGTH = 200;\n\n/**\n * Post domain entity\n * Wraps database entity with business logic\n */\nexport class Post {\n private constructor(\n public readonly id: string,\n public readonly title: string,\n public readonly content: string,\n public readonly published: boolean,\n public readonly createdAt: Date,\n public readonly updatedAt: Date\n ) {}\n\n /**\n * Create a new Post instance from database entity\n */\n static fromDatabase(data: PrismaPost): Post {\n return new Post(\n data.id,\n data.title,\n data.content,\n data.published,\n data.createdAt,\n data.updatedAt\n );\n }\n\n /**\n * Convert to database representation\n */\n toDatabase(): Omit<PrismaPost, 'id' | 'createdAt' | 'updatedAt'> {\n return {\n title: this.title,\n content: this.content,\n published: this.published,\n };\n }\n\n /**\n * Business logic: Check if post is recent\n */\n isRecent(days: number = DEFAULT_RECENT_DAYS): boolean {\n const daysSinceCreation =\n (Date.now() - this.createdAt.getTime()) / MILLISECONDS_PER_DAY;\n return daysSinceCreation <= days;\n }\n\n /**\n * Business logic: Validate title\n */\n static isValidTitle(title: string): boolean {\n const trimmedLength = title.trim().length;\n return (\n trimmedLength >= MIN_TITLE_LENGTH && trimmedLength <= MAX_TITLE_LENGTH\n );\n }\n\n /**\n * Business logic: Publish post\n */\n publish(): Post {\n return new Post(\n this.id,\n this.title,\n this.content,\n true,\n this.createdAt,\n new Date()\n );\n }\n}\n```\n\n**When to use models:**\n\n- ✅ Complex business rules (order calculations, post publishing, user roles)\n- ✅ Entity state validation (email formats, price ranges, status transitions)\n- ✅ Transformations between layers (API ↔ database ↔ domain)\n- ❌ Simple CRUD with no business logic (use simple category)\n\n### 5. **Schemas Layer** (`schemas/`)\n\n**Purpose:** Zod validation schemas and input types\n\n**Rules:**\n\n- ✅ Use Zod for runtime validation\n- ✅ Export schema and inferred type\n- ✅ Use i18n keys for error messages\n- ❌ No business logic\n\n**Template includes:** Example Zod schema with i18n error messages\n\n**Example:**\n\n```typescript\n// schemas/create-bookmark.ts\nimport { z } from 'zod';\n\nimport { BOOKMARK_ERRORS } from '@/features/bookmarks/lib/strings';\n\nexport const createBookmarkSchema = z.object({\n title: z.string().min(1, { message: BOOKMARK_ERRORS.titleRequired }),\n url: z.string().url({ message: BOOKMARK_ERRORS.invalidUrl }),\n});\n\nexport type CreateBookmarkInput = z.infer<typeof createBookmarkSchema>;\n```\n\n### 6. **Lib Layer** (`lib/`)\n\n**Purpose:** Feature-specific utilities, errors, and constants\n\n**Files:**\n\n- `strings.ts` - All string constants (codes, messages, labels)\n- `errors.ts` - AppError factory functions\n- `utils.ts` - Feature-specific helper functions\n\n**Template includes:** Complete strings.ts with all constant categories, error factories, and utility placeholder\n\n**Example (`lib/strings.ts`):**\n\n```typescript\n// lib/strings.ts\n\n// Note: For kebab-case feature names (e.g., user-settings):\n// - Constant name: USER_SETTINGS_CODES (UPPER_SNAKE_CASE)\n// - i18n keys: user-settings.errors.not-found (kebab-case)\n// - Prisma model: userSettings (camelCase)\n\nexport const BOOKMARK_CODES = {\n notFound: 'not-found',\n invalidUrl: 'invalid-url',\n titleRequired: 'title-required',\n} as const;\n\nexport type BookmarkCode = (typeof BOOKMARK_CODES)[keyof typeof BOOKMARK_CODES];\n\nexport const BOOKMARK_ERRORS = {\n notFound: 'bookmarks.errors.not-found',\n invalidUrl: 'bookmarks.errors.invalid-url',\n titleRequired: 'bookmarks.errors.title-required',\n} as const;\n\nexport const BOOKMARK_SUCCESS = {\n created: 'bookmarks.success.created',\n updated: 'bookmarks.success.updated',\n deleted: 'bookmarks.success.deleted',\n} as const;\n\nexport const BOOKMARK_LABELS = {\n title: 'bookmarks.labels.title',\n createButton: 'bookmarks.labels.create-button',\n} as const;\n```\n\n**Example (`lib/errors.ts`):**\n\n```typescript\nimport { AppError } from '@/lib/errors';\nimport { HTTP_STATUS } from '@/lib/http-status';\n\nimport { BOOKMARK_CODES, BOOKMARK_ERRORS } from './strings';\n\nexport const bookmarkNotFound = (id: string) =>\n new AppError({\n code: BOOKMARK_CODES.notFound,\n message: { key: BOOKMARK_ERRORS.notFound, params: { id } },\n httpStatus: HTTP_STATUS.NOT_FOUND,\n });\n```\n\n---\n\n## Naming Conventions\n\n### Files\n\n- **kebab-case** for all files: `create-bookmark.ts`, `bookmark-list.tsx`\n\n### Functions & Variables\n\n- **camelCase** for functions: `createBookmark`, `getBookmarkById`\n- **camelCase** for variables: `bookmarkData`, `userId`\n\n### Types & Interfaces\n\n- **PascalCase** for types: `CreateBookmarkData`, `BookmarkInput`\n\n### Constants\n\n- **SCREAMING_SNAKE_CASE** for primitives: `const MAX_BOOKMARKS = 100`\n- **camelCase** for objects/arrays: `const bookmarkRoutes = [...]`\n- **camelCase properties** with **kebab-case values**:\n ```typescript\n const BOOKMARK_CODES = {\n notFound: 'not-found', // property: camelCase, value: kebab-case\n } as const;\n ```\n\n---\n\n## i18n Setup\n\nAfter creating a feature, add translations:\n\n**`src/locales/en/<feature-name>.json`:**\n\n```json\n{\n \"bookmarks\": {\n \"errors\": {\n \"not-found\": \"Bookmark not found\",\n \"invalid-url\": \"Please enter a valid URL\"\n },\n \"success\": {\n \"created\": \"Bookmark created successfully\",\n \"updated\": \"Bookmark updated\"\n },\n \"labels\": {\n \"title\": \"Bookmarks\",\n \"create-button\": \"Create Bookmark\"\n }\n }\n}\n```\n\n---\n\n## Testing\n\nWrite tests in `__tests__/` directory:\n\n```typescript\n// __tests__/create-bookmark.test.ts\nimport { describe, expect, it } from 'vitest';\n\nimport { Status } from '@/lib/response';\n\nimport { createBookmark } from '../actions';\n\ndescribe('createBookmark', () => {\n it('should create bookmark with valid data', async () => {\n const result = await createBookmark({\n title: 'Test',\n url: 'https://example.com',\n });\n\n expect(result.status).toBe(Status.Success);\n if (result.status === Status.Success) {\n expect(result.data).toHaveProperty('id');\n }\n });\n});\n```\n\n---\n\n## Checklist\n\nAfter generating a feature:\n\n### 1. Database Setup\n\n- [ ] Add Prisma schema model to `prisma/schema.prisma`\n- [ ] Run migration: `npx prisma migrate dev --name create-<feature>`\n- [ ] Verify database structure\n\n### 2. Translations\n\n- [ ] Review generated `src/locales/en/<feature>.json`\n- [ ] Review generated `src/locales/hu/<feature>.json`\n- [ ] Add more translations: `npm run i18n:add <feature>.errors.custom \"Text\" \"Szöveg\"`\n- [ ] Validate i18n files: `npm run i18n:validate`\n\n### 3. Implementation\n\n- [ ] **Data layer**: Customize CRUD operations in `data/example.ts`\n- [ ] **Models layer** (CRUD only): Implement business logic in `models/index.ts`\n- [ ] **Schemas**: Define validation rules in `schemas/create-example.ts`\n- [ ] **Services**: Implement business logic in `services/create-example.ts`\n- [ ] **Actions**: Customize server actions in `actions/create-example.ts`\n- [ ] **Error handling**: Add domain-specific errors in `lib/errors.ts`\n- [ ] **String constants**: Expand codes/messages in `lib/strings.ts`\n\n### 4. UI & Integration\n\n- [ ] Build UI components in `components/`\n- [ ] Create custom hooks in `hooks/` (TanStack Query)\n- [ ] Update feature `README.md` with usage examples\n- [ ] Add route handlers if needed\n\n### 5. Testing & Validation\n\n- [ ] Write tests in `__tests__/`\n- [ ] Run tests: `npm test`\n- [ ] Run type check: `npm run typecheck`\n- [ ] Test end-to-end functionality\n\n### 6. Cleanup\n\n- [ ] Remove example files if not needed:\n - `data/example.ts` → rename to actual entity (e.g., `bookmark.ts`)\n - `actions/create-example.ts` → rename to actual action\n - `services/create-example.ts` → rename to actual service\n - etc.\n- [ ] Update barrel exports in `index.ts` files\n\n---\n\n## Category Decision Guide\n\n**Choose CRUD when:**\n\n- ✅ Complex business rules (pricing, permissions, workflows)\n- ✅ Entity state management (published/draft, active/inactive)\n- ✅ Domain transformations (API ↔ database ↔ UI)\n- ✅ Reusable business logic across multiple features\n- ✅ Examples: posts, products, orders, bookmarks, users\n\n**Choose Simple when:**\n\n- ✅ Basic CRUD with minimal logic\n- ✅ Configuration or settings storage\n- ✅ Simple data transformations\n- ✅ No complex business rules\n- ✅ Examples: settings, notifications, preferences, tags\n\n---\n\n## Retrofitting Existing Features with Models\n\nOlder features (like `auth`) may not have a `models/` folder. Here's when and how to add one:\n\n### When to Add Models to Existing Features\n\n**✅ Add models when you find:**\n\n1. **Business Logic in Data Layer**\n\n ```typescript\n // ❌ BAD: Business logic (bcrypt) in data layer\n export const verifyUserCredentials = async (\n email: string,\n password: string\n ) => {\n const user = await getUserByEmail(email);\n const isValid = await bcrypt.compare(password, user.password); // Business logic!\n return isValid ? user : null;\n };\n ```\n\n2. **Business Logic in Services**\n\n ```typescript\n // ❌ BAD: Password hashing scattered in multiple services\n export const registerUser = async (values: RegisterInput) => {\n const hashedPassword = await bcrypt.hash(password, 10); // Duplication!\n // ...\n };\n ```\n\n3. **Domain Validation Scattered**\n ```typescript\n // ❌ BAD: Email validation copy-pasted across files\n if (!email.includes('@')) return error(); // Scattered validation\n ```\n\n**❌ Don't add models when:**\n\n1. Feature has simple CRUD with no complex business logic\n2. Data layer only does database access (no transformations/validation)\n3. Services only orchestrate calls (no domain logic)\n\n### Migration Example: Auth Feature\n\nSee `docs/auth-user-model-migration.md` for complete case study.\n\n**Summary:**\n\n```typescript\n// Before: Business logic in data/services\n// data/user.ts\nexport const verifyUserCredentials = async (email, password) => {\n const user = await getUserByEmail(email);\n const isValid = await bcrypt.compare(password, user.password); // ❌ Business logic\n return isValid ? user : null;\n};\n\n// services/register-user.ts\nconst hashedPassword = await bcrypt.hash(password, BCRYPT_SALT_ROUNDS); // ❌ Business logic\n\n// After: Business logic in User model\n// models/user.ts\nexport class User {\n async verifyPassword(plainPassword: string): Promise<boolean> {\n return await bcrypt.compare(plainPassword, this.data.password);\n }\n\n static async hashPassword(plainPassword: string): Promise<string> {\n return await bcrypt.hash(plainPassword, BCRYPT_SALT_ROUNDS);\n }\n}\n\n// data/user.ts - Pure database access\nexport const verifyUserCredentials = async (email, password) => {\n const prismaUser = await getUserByEmail(email);\n if (!prismaUser) return null;\n\n const user = new User(prismaUser); // ✅ Use model\n const isValid = await user.verifyPassword(password);\n return isValid ? user.toSafeObject() : null;\n};\n\n// services/register-user.ts - Uses model\nconst hashedPassword = await User.hashPassword(password); // ✅ Use model\n```\n\n### Retrofit Checklist\n\n- [ ] I", "variables": [], "notes": "Create a new feature using the scaffolding script:", "metadata": { "source": { "provider": "github-prompts", "repository": "https://github.com/r4sheed/nextjs-intrasite", "path": ".github/prompts/feature-creation.prompt.md", "ref": "b33cbd78789663cd7d6eb6c8cf57f102b9506cde", "url": "https://github.com/r4sheed/nextjs-intrasite/blob/b33cbd78789663cd7d6eb6c8cf57f102b9506cde/.github/prompts/feature-creation.prompt.md", "key": "r4sheed/nextjs-intrasite/.github/prompts/feature-creation.prompt.md" } } }

feature-creation

About

Feature Creation Guide

Quick Start

Categories

Examples

Generated Structure

CRUD Category (with domain models)

Simple Category (lightweight)

Layer Responsibilities

1. Actions Layer (`actions/`)

2. Services Layer (`services/`)

3. Data Layer (`data/`)

4. Models Layer (`models/`) - CRUD Category Only ⭐

5. Schemas Layer (`schemas/`)

6. Lib Layer (`lib/`)

Naming Conventions

Files

Functions & Variables

Types & Interfaces

Constants

i18n Setup

Testing

Checklist

1. Database Setup

2. Translations

3. Implementation

4. UI & Integration

5. Testing & Validation

6. Cleanup

Category Decision Guide

Retrofitting Existing Features with Models

When to Add Models to Existing Features

Migration Example: Auth Feature

Retrofit Checklist

Guidelines Reference

Use it

Manifest

Reviews

About

Feature Creation Guide

Quick Start

Categories

Examples

Generated Structure

CRUD Category (with domain models)

Simple Category (lightweight)

Layer Responsibilities

1. Actions Layer (actions/)

2. Services Layer (services/)

3. Data Layer (data/)

4. Models Layer (models/) - CRUD Category Only ⭐

5. Schemas Layer (schemas/)

6. Lib Layer (lib/)

Naming Conventions

Files

Functions & Variables

Types & Interfaces

Constants

i18n Setup

Testing

Checklist

1. Database Setup

2. Translations

3. Implementation

4. UI & Integration

5. Testing & Validation

6. Cleanup

Category Decision Guide

Retrofitting Existing Features with Models

When to Add Models to Existing Features

Migration Example: Auth Feature

Retrofit Checklist

Guidelines Reference

Use it

Manifest

Reviews

1. Actions Layer (`actions/`)

2. Services Layer (`services/`)

3. Data Layer (`data/`)

4. Models Layer (`models/`) - CRUD Category Only ⭐

5. Schemas Layer (`schemas/`)

6. Lib Layer (`lib/`)