| 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/.
