Project Structure Enforcer

Enforce 2026 folder structure best practices with BLOCKING validation.

When to Use

• Creating new files
• Reviewing project architecture
• Refactoring folder structure
• Validating import patterns

Validation Rules

BLOCKING Rules (exit 1)

Rule	Check	Example Violation
Max Nesting	Max 4 levels from src/ or app/	src/a/b/c/d/e/file.ts
No Barrel Files	No index.ts re-exports	src/components/index.ts
Component Location	React components in components/ or features/	src/utils/Button.tsx
Hook Location	Custom hooks in hooks/ directory	src/components/useAuth.ts
Import Direction	Unidirectional: shared → features → app	features/ importing from app/

Expected Folder Structures

React/Next.js (Frontend)

src/
├── app/              # Next.js App Router (pages)
│   ├── (auth)/       # Route groups
│   ├── api/          # API routes
│   └── layout.tsx
├── components/       # Reusable UI components
│   ├── ui/           # Primitive components
│   └── forms/        # Form components
├── features/         # Feature modules (self-contained)
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types.ts
│   └── dashboard/
├── hooks/            # Global custom hooks
├── lib/              # Third-party integrations
├── services/         # API clients
├── types/            # Global TypeScript types
└── utils/            # Pure utility functions

FastAPI (Backend)

app/
├── routers/          # API route handlers
│   ├── router_users.py
│   ├── router_auth.py
│   └── deps.py       # Shared dependencies
├── services/         # Business logic layer
│   ├── user_service.py
│   └── auth_service.py
├── repositories/     # Data access layer
│   ├── user_repository.py
│   └── base_repository.py
├── schemas/          # Pydantic models
│   ├── user_schema.py
│   └── auth_schema.py
├── models/           # SQLAlchemy models
│   ├── user_model.py
│   └── base.py
├── core/             # Config, security, deps
│   ├── config.py
│   ├── security.py
│   └── database.py
└── utils/            # Utility functions

Nesting Depth Rules

Maximum 4 levels from src/ or app/:

ALLOWED (4 levels):
  src/features/auth/components/LoginForm.tsx
  app/routers/v1/users/router_users.py

BLOCKED (5+ levels):
  src/features/dashboard/widgets/charts/line/LineChart.tsx
  ↳ Flatten to: src/features/dashboard/charts/LineChart.tsx

No Barrel Files

Barrel files (index.ts that only re-export) cause tree-shaking issues with Vite/webpack:

// BLOCKED: src/components/index.ts
export { Button } from './Button';
export { Input } from './Input';
export { Modal } from './Modal';

// GOOD: Import directly
import { Button } from '@/components/Button';
import { Input } from '@/components/Input';

Why? Barrel files:

• Break tree-shaking (entire barrel is imported)
• Cause circular dependency issues
• Slow down build times
• Make debugging harder

Import Direction (Unidirectional Architecture)

Code must flow in ONE direction:

┌─────────────────────────────────────────────────────────┐
│                                                         │
│   shared/lib  →  components  →  features  →  app       │
│                                                         │
│   (lowest)                                 (highest)    │
│                                                         │
└─────────────────────────────────────────────────────────┘

Allowed Imports

Layer	Can Import From
shared/, lib/	Nothing (base layer)
components/	shared/, lib/, utils/
features/	shared/, lib/, components/, utils/
app/	Everything above

Blocked Imports

// BLOCKED: shared/ importing from features/
// File: src/shared/utils.ts
import { authConfig } from '@/features/auth/config';  // ❌

// BLOCKED: features/ importing from app/
// File: src/features/auth/useAuth.ts
import { RootLayout } from '@/app/layout';  // ❌

// BLOCKED: Cross-feature imports
// File: src/features/auth/useAuth.ts
import { DashboardContext } from '@/features/dashboard/context';  // ❌
// Fix: Extract to shared/ if needed by multiple features

Type-Only Imports (Exception)

Type-only imports across features are allowed:

// ALLOWED: Type-only import from another feature
import type { User } from '@/features/users/types';

Component Location Rules

React Components (PascalCase .tsx)

ALLOWED:
  src/components/Button.tsx
  src/components/ui/Card.tsx
  src/features/auth/components/LoginForm.tsx
  src/app/dashboard/page.tsx

BLOCKED:
  src/utils/Button.tsx       # Components not in utils/
  src/services/Modal.tsx     # Components not in services/
  src/hooks/Dropdown.tsx     # Components not in hooks/

Custom Hooks (useX pattern)

ALLOWED:
  src/hooks/useAuth.ts
  src/hooks/useLocalStorage.ts
  src/features/auth/hooks/useLogin.ts

BLOCKED:
  src/components/useAuth.ts   # Hooks not in components/
  src/utils/useDebounce.ts    # Hooks not in utils/
  src/services/useFetch.ts    # Hooks not in services/

Python File Location Rules

Routers

ALLOWED:
  app/routers/router_users.py
  app/routers/routes_auth.py
  app/routers/api_v1.py

BLOCKED:
  app/users_router.py          # Not in routers/
  app/services/router_users.py # Router in services/

Services

ALLOWED:
  app/services/user_service.py
  app/services/auth_service.py

BLOCKED:
  app/user_service.py           # Not in services/
  app/routers/user_service.py   # Service in routers/

Common Violations

1. Too Deep Nesting

BLOCKED: Max nesting depth exceeded: 5 levels (max: 4)
  File: src/features/dashboard/widgets/charts/line/LineChart.tsx
  Consider flattening: src/features/dashboard/charts/LineChart.tsx

2. Barrel File Created

BLOCKED: Barrel files (index.ts) discouraged - causes tree-shaking issues
  File: src/components/index.ts
  Import directly from source files instead

3. Component in Wrong Location

BLOCKED: React components must be in components/, features/, or app/
  File: src/utils/Button.tsx
  Move to: src/components/Button.tsx

4. Invalid Import Direction

BLOCKED: Import direction violation (unidirectional architecture)
  features/ cannot import from app/
  Import direction: features -> shared, lib, components

Allowed flow: shared/lib -> components -> features -> app

5. Cross-Feature Import

BLOCKED: Cannot import from other features (cross-feature dependency)
  File: src/features/auth/useAuth.ts
  Import: from '@/features/dashboard/context'
  Extract shared code to shared/ or lib/

Migration Guide

Flattening Deep Nesting

# Before (5 levels)
src/features/dashboard/widgets/charts/line/LineChart.tsx
src/features/dashboard/widgets/charts/line/LineChartTooltip.tsx

# After (4 levels) - Flatten last two levels
src/features/dashboard/charts/LineChart.tsx
src/features/dashboard/charts/LineChartTooltip.tsx

Removing Barrel Files

# Before
src/components/index.ts  # Re-exports everything
import { Button, Input } from '@/components';

# After - Direct imports
import { Button } from '@/components/Button';
import { Input } from '@/components/Input';

Fixing Cross-Feature Imports

# Before - Cross-feature dependency
src/features/auth/useAuth.ts imports from src/features/users/types

# After - Extract to shared
src/shared/types/user.ts
src/features/auth/useAuth.ts imports from src/shared/types/user
src/features/users/... imports from src/shared/types/user

Related Skills

• backend-architecture-enforcer - FastAPI layer separation
• clean-architecture - DDD patterns
• type-safety-validation - TypeScript strictness

Capability Details

folder-structure

Keywords: folder structure, directory structure, project layout, organization Solves:

• Enforce feature-based organization
• Validate proper file placement
• Maintain consistent project structure

nesting-depth

Keywords: nesting, depth, levels, max depth, deep nesting Solves:

• Limit directory nesting to 4 levels
• Prevent overly complex structures
• Improve navigability

import-direction

Keywords: import, unidirectional, circular, dependency direction Solves:

• Enforce unidirectional imports
• Prevent circular dependencies
• Maintain clean architecture

component-location

Keywords: component location, file placement, where to put Solves:

• Validate React component placement
• Enforce hook location rules
• Block barrel files