file-tree-architecture

name	File Tree Architecture
description	DEFINE where files live in a full-stack project. Enforce one-directional dependency flow (app → pages → widgets → features → entities → shared). Prevent flat src/ dumps, tangled imports, and server/client code mixing. Trigger: initializing new repo, restructuring messy codebase, or any "set up the file structure" request.
category	file-structure
version	3.0.0
last_updated	2026-06-28T00:00:00.000Z
stacks	["React","Next.js (App Router)","Vue","Nuxt","Node.js","FastAPI"]
triggers	[{"pattern":"set up (the|a) (file structure|directory structure|folder structure|project structure)","action":"CREATE directory scaffold as specified below"},{"pattern":"organize (the|this|my) codebase","action":"SCAN current structure → RECOMMEND migration"},{"pattern":"refactor (the|this) project structure","action":"SCAN → RECOMMEND → RESTRUCTURE files"}]
related_skills	["professional-project-intake","component-architecture-patterns","saas-app-structure"]

Full-Stack File Tree Architecture

IDENTIFY: When to Activate

Activate when:

• Initializing a new project (after intake phase)
• User says "directory structure", "file structure", "organize this"
• Existing codebase has flat directories (≥15 files in src/ root)
• Imports use ../../../ patterns (depth ≥3 parent references)

DECIDE: Directory Template Selection

IF framework detected = Next.js (App Router) →
  USE Next.js template (Step 1)

IF framework detected = Vue / Nuxt →
  USE Vue/Nuxt template (Step 2)

IF framework detected = backend-only (Express, FastAPI, Django) →
  USE backend template (Step 3)

IF existing project, SCAN existing structure first:
  IF project already has organized structure →
    FOLLOW existing conventions. Do NOT reorganize without user approval.
  IF project is disorganized →
    PRESENT recommended structure to user. Get approval before moving files.

EXECUTE: Instructions

Step 1: Next.js (App Router): 2026 Standard

project-root/
├── app/                            # ROUTES AND LAYOUTS ONLY
│   ├── (marketing)/                # Route group: public pages
│   │   ├── page.tsx
│   │   └── layout.tsx
│   ├── (dashboard)/                # Route group: authenticated pages
│   │   ├── dashboard/
│   │   │   └── page.tsx
│   │   └── layout.tsx
│   ├── api/                        # Route handlers
│   │   └── users/
│   │       └── route.ts
│   └── proxy.ts                    # (Next.js 16+) Replaces middleware.ts
├── src/
│   ├── components/
│   │   └── ui/                     # Presentational: Button, Card, Input, NO business logic
│   ├── features/                   # Domain-specific logic (one folder per feature)
│   │   ├── auth/
│   │   │   ├── actions.ts          # Server Actions
│   │   │   ├── auth.config.ts      # Auth.js / Better Auth config
│   │   │   └── components/         # Auth-specific: LoginForm, SignUpForm
│   │   └── billing/
│   │       ├── actions.ts
│   │       ├── stripe.ts           # Stripe service (server-only)
│   │       └── components/
│   ├── lib/                        # Third-party service wrappers
│   │   ├── stripe.ts
│   │   └── email.ts
│   ├── server/                     # BACKEND-ONLY, never imported by client
│   │   ├── db/
│   │   │   └── schema.prisma       # Prisma schema, or:
│   │   │   └── schema.ts           # Drizzle schema
│   │   └── queries/
│   └── utils/                      # Pure functions, NO side effects, NO imports from server
│       ├── cn.ts                   # clsx + twMerge
│       └── format.ts
├── public/
├── package.json
└── tsconfig.json

ENFORCED RULES:

RULE 1: app/ directory = routes and layouts ONLY.
  NEVER put reusable components in app/.
  DETECTION: If a file in app/ exports a non-page component → MOVE to src/.

RULE 2: src/server/ = server-only code.
  NEVER import from src/server/ in a Client Component.
  DETECTION: Search for `import.*from.*server/` in 'use client' files → VIOLATION.

RULE 3: src/features/ groups by business domain.
  Each feature folder owns its actions, components, and hooks.
  Features NEVER import from each other's internal modules.
  Shared code goes in lib/, utils/, or components/ui/.