SOLID Next.js - Modular Architecture

Current Date (CRITICAL)

Today: January 2026 - ALWAYS use the current year for your searches. Search with "2025" or "2026", NEVER with past years.

MANDATORY: Research Before Coding

CRITICAL: Check today's date first, then search documentation and web BEFORE writing any code.

• Use Context7 to query Next.js/React official documentation

• Use Exa web search with current year for latest trends

• Check Vercel Blog of current year for new features

• Verify package versions for Next.js 16 compatibility

Search queries (replace YYYY with current year):

• Next.js [feature] YYYY best practices

• React 19 [component] YYYY

• TypeScript [pattern] YYYY

• Prisma 7 [feature] YYYY

Codebase Analysis (MANDATORY)

Before ANY implementation:

• Explore project structure to understand architecture

• Read existing related files to follow established patterns

• Identify naming conventions, coding style, and patterns used

• Understand data flow and dependencies

DRY - Reuse or Create Shared (MANDATORY)

Before writing ANY new code:

• Grep the codebase for similar function names, patterns, or logic

• Check shared locations: modules/cores/lib/ , modules/cores/components/ , modules/cores/hooks/

• If similar code exists → extend/reuse instead of duplicate

• If code will be used by 2+ features → create it in modules/cores/ directly

• Extract repeated logic (3+ occurrences) into shared helpers

• Run npx jscpd ./src --threshold 3 after creating new files

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

• fuse-ai-pilot:explore-codebase - Analyze project structure and existing patterns

• fuse-ai-pilot:research-expert - Verify latest docs for all stack technologies

• mcp__context7__query-docs - Check integration compatibility

After implementation, run fuse-ai-pilot:sniper for validation.

Absolute Rules (MANDATORY)

1. Files < 100 lines

• Split at 90 lines - Never exceed 100

• Page components < 50 lines (use composition)

• Server Components < 80 lines

• Client Components < 60 lines

• Server Actions < 30 lines each

2. Modular Architecture

See references/architecture-patterns.md for complete structure with feature modules and cores directory.

3. JSDoc Mandatory

/**

• Fetch user by ID from database.
• @param id - User unique identifier
• @returns User object or null if not found
• @throws DatabaseError on connection failure */ export async function getUserById(id: string): Promise<User | null>

4. Interfaces Separated

modules/auth/src/ ├── interfaces/ # Types ONLY │ ├── user.interface.ts │ └── session.interface.ts ├── services/ # NO types here └── components/ # NO types here

SOLID Principles (Detailed Guides)

Each SOLID principle has a dedicated reference guide:

references/single-responsibility.md

• One class/function = one reason to change

• File splitting at 90 lines (pages < 50, components < 60, services < 80)

• Component composition patterns

• Next.js page & server action examples

references/open-closed.md

• Extend via composition, not modification

• Plugin architecture patterns

• Provider patterns for multiple implementations

• Adapter and strategy patterns

• Adding features without changing existing code

references/liskov-substitution.md

• Contract compliance & behavioral subtyping

• Subtypes must be substitutable for base types

• Exception and return type contracts

• Testing LSP compliance

references/interface-segregation.md

• Many focused interfaces beat one fat interface

• Role-based interfaces

• Avoiding bloated contracts

• Client-specific interfaces

references/dependency-inversion.md

• Depend on abstractions, not implementations

• Constructor injection patterns

• Factory patterns for creation

• IoC containers

• Easy mocking for tests

See references/solid-principles.md for overview and quick reference.

Code Templates

Ready-to-copy code in references/templates/ :

Template Usage

server-component.md

Server Component with data fetching

client-component.md

Client Component with hooks

service.md

Service with dependency injection

hook.md

React hook with state

interface.md

TypeScript interfaces

store.md

Zustand store with persistence

action.md

Server Action with validation

api-route.md

API Route Handler

validator.md

Zod validation schemas

factory.md

Factory pattern

adapter.md

Adapter pattern

error.md

Custom error classes

test.md

Test templates

middleware.md

Auth middleware

prisma.md

Prisma singleton

i18n.md

Feature/global translations

query.md

Database queries (Prisma 7)

Response Guidelines

• Research first - MANDATORY: Search Context7 + Exa before ANY code

• Show complete code - Working examples, not snippets

• Explain decisions - Why this pattern over alternatives

• Include tests - Always suggest test cases

• Handle errors - Never ignore, use error boundaries

• Type everything - Full TypeScript, no any

• Document code - JSDoc for complex functions

Forbidden

• ❌ Coding without researching docs first (ALWAYS research)

• ❌ Using outdated APIs without checking current year docs

• ❌ Files > 100 lines

• ❌ Interfaces in component files

• ❌ Business logic in app/ pages

• ❌ Direct DB calls in components

• ❌ Module importing another module (except cores)

• ❌ 'use client' by default

• ❌ useEffect for data fetching

• ❌ Missing JSDoc on exports

• ❌ any type

• ❌ Barrel exports

• ❌ Duplicating existing utility/helper without Grep search first

• ❌ Copy-pasting logic blocks instead of extracting shared function