Project Structure

You are a project structure expert.

Read individual rule files in rules/ for detailed explanations and examples.

Rules Overview

Workflow

Step 1: Detect Project Type

Scan for project indicators to determine the appropriate organisation approach:

• Frontend SPA / Next.js / React → feature-based
• Backend API / Express / Fastify / Hono → layer-based
• Monorepo (apps/ + packages/) → hybrid
• Existing structure → respect and extend current patterns

Step 2: Audit

Check the existing structure against all rules. Report violations grouped by severity with directory paths.

Step 3: Recommend

Based on project type and existing patterns, recommend where new code should live. Always prioritise colocation.

Rule: Avoid common structural anti-patterns that make codebases hard to navigate and maintain.

Catch-All Files

Avoid generic utils.ts, helpers.ts, common.ts. Split by domain instead.

# Bad
src/utils.ts          # 500 lines of unrelated helpers

# Good
src/lib/date.ts       # Date formatting utilities
src/lib/currency.ts   # Currency formatting utilities

Deep Nesting

Keep directory depth under 4 levels. Use descriptive names instead of deeper nesting.

# Bad
src/features/auth/components/forms/fields/inputs/text-input.tsx

# Good
src/features/auth/components/auth-text-field.tsx

Barrel Files

Avoid index.ts re-export files. They hurt tree-shaking, slow down TypeScript and bundlers, and create circular dependency risks. Import directly from source files instead.

# Bad — barrel file
src/components/index.ts       # re-exports from 15 files
import { Button } from './components'

# Good — direct imports
import { Button } from './components/button'

Only acceptable use: package entry points (packages/ui/index.ts) where a public API boundary is intentional.

Circular Dependencies

Watch for modules that import each other directly or through a chain. Common signs:

• Runtime errors about undefined imports
• Barrel files that re-export from modules that import back from the barrel
• Feature A importing from Feature B and vice versa

Fix by extracting shared code into a separate module that both features import from.

Separated Tests

Don't put all tests in a separate __tests__/ directory. Colocate unit tests next to the code they test.

Language Grouping in Monorepos

Group packages by domain, not by language.

# Bad
packages/typescript/
packages/go/

# Good
packages/auth/
packages/payments/

Rule: Place code as close to where it's relevant as possible. Things that change together should be located together.

Incorrect

src/
├── components/
│   └── user-profile.tsx
├── hooks/
│   └── use-user.ts
├── types/
│   └── user.ts
└── tests/
    └── user-profile.test.tsx

Correct

src/features/users/
├── user-profile.tsx
├── user-profile.test.tsx
├── use-user.ts
└── user.types.ts

Next.js App Router

Colocate components with the route that uses them:

app/dashboard/
├── page.tsx
├── dashboard-chart.tsx
├── dashboard-stats.tsx
└── use-dashboard-data.ts

Where to Put Things

Rule: Group by domain — all related code (components, hooks, services, tests) in one directory. Recommended for frontend projects.

Structure

src/features/
├── auth/
│   ├── components/
│   ├── hooks/
│   ├── auth.service.ts
│   └── auth.test.ts
├── users/
│   ├── components/
│   ├── hooks/
│   └── users.service.ts
└── products/
    ├── components/
    └── products.service.ts

Next.js App Router

Use route groups to organise by feature without affecting the URL:

app/
├── (auth)/
│   ├── login/page.tsx
│   ├── register/page.tsx
│   └── layout.tsx
├── (dashboard)/
│   ├── overview/page.tsx
│   ├── settings/page.tsx
│   └── layout.tsx
└── layout.tsx

Monorepo Variant

apps/           # Applications
├── web/
├── api/
packages/       # Shared libraries (by domain, not language)
├── types/
├── utils/
└── ui/

Rule: Follow framework-specific directory conventions. File-based routing frameworks require specific directory structures to function correctly.

Next.js App Router

app/
├── layout.tsx              # Root layout (required)
├── page.tsx                # Home route
├── loading.tsx             # Loading UI
├── error.tsx               # Error boundary
├── not-found.tsx           # 404 page
├── (marketing)/            # Route group (no URL segment)
│   ├── about/page.tsx
│   └── pricing/page.tsx
├── dashboard/
│   ├── layout.tsx          # Nested layout
│   ├── page.tsx
│   └── @modal/             # Parallel route (named slot)
│       └── default.tsx
└── api/
    └── users/route.ts      # API route handler

Key conventions:

• app/ is the root for all routes
• Route groups (name)/ organise without affecting URLs
• Parallel routes @name/ render multiple pages in the same layout
• middleware.ts lives at the project root, not inside app/

Expo Router

app/
├── (tabs)/
│   ├── index.tsx           # First tab
│   └── settings.tsx        # Second tab
└── [id].tsx                # Dynamic route

Key conventions:

• (name)/ for layout groups (tabs, drawers)
• [param].tsx for dynamic segments

Note: Expo Router requires specific prefixes for certain files (e.g., layout files, not-found screens). These are framework-mandated — do not use _ or + prefixes for your own files outside of what the framework requires.

Rule: Group by technical layer. Common for backend/API projects where cross-cutting concerns span domains.

Structure

src/
├── controllers/    # Request handling
├── services/       # Business logic
├── models/         # Data models
├── routes/         # Route definitions
├── middleware/      # Express/Fastify middleware
└── utils/          # Shared utilities

Use layer-based when the project is a focused API with clear horizontal layers. Switch to feature-based when the backend grows to span multiple distinct domains.