# Architect Nextjs

> Establish the architecture for Next.js 15+ applications using the Scope Rule and Screaming Architecture. Use this skill when (1) Setting up a new project, (2) Deciding component placement (local vs shared), (3) Refactoring codebases, or (4) implementing Server Actions, layouts, and route groups.

- Skill: `ivantsxx/architect-nextjs` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ivantsxx/architect-nextjs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivantsxx/architect-nextjs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ivantsxx (https://skillmd.com/u/ivantsxx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ivantsxx/architect-nextjs

---


# Scope Rule Architect (Next.js 15+)

This skill establishes the architectural foundation for scalable Next.js applications by enforcing strict **Scope Rules** and **Screaming Architecture**.

## Core Principles

### 1. The Scope Rule (Absolute Law)

**"Scope determines structure."**

- **Local Scope**: Code used by **1 feature** → MUST stay local (e.g., `(user)/profile/_components`).
- **Shared Scope**: Code used by **2+ features** → MUST go to `src/shared/`.
- **No Exceptions**: Do not pollute `shared` with single-use components.

### 2. Screaming Architecture

Directory structures must immediately declare *what* the application does.

- Use **Route Groups** `(feature)` for top-level modules.
- Avoid generic folders like `containers` or `views` at the top level.

### 3. Next.js 15 Standards

- **App Router Only**: No `pages/` directory.
- **Server-First**: Components are Server Components by default.
- **Data Access**: Fetch directly in Server Components or via Server Actions.

## Decision Framework

When placing files, follow this decision tree:

1. **Count Usage**:
    - **Used by 1 Feature**: Place in `app/(feature)/_components/`.
    - **Used by 2+ Features**: Place in `src/shared/components/`.

2. **Determine Type**:
    - **Server Component**: Default. Used for static content and initial data fetching.
    - **Client Component**: Use ONLY for `useState`, `useEffect`, or event listeners.
    - **Server Action**: Use for mutations and form handling. Place in `_actions/name.ts`.

## Implementation Guides

### Project Structure

For the standard directory layout, reference the [Project Structure Template](references/project_structure.md).  
Use this reference when setting up new folders or verifying where a specific file should reside.

### Component Templates

For code patterns ensuring best practices, reference the [Component Templates](references/component_templates.md).  
This includes:

- **Server Components** with `Suspense` and data fetching.
- **Client Components** isolated for interactivity.
- **Server Actions** properly typed and validated.

## Quality Checklist

Before finalizing a structure or file creation:

1. [ ] **Scope**: Is this used in >1 feature? If no, move to `_components`.
2. [ ] **Server**: Is "use client" absolutely necessary? Can it be pushed down the tree?
3. [ ] **Screaming**: Does the folder name describe *what* it does (e.g., `(invoices)` vs `pages`)?
4. [ ] **Colocation**: Are specific hooks/types/styles next to the consuming component?