Full-Stack File Tree Architecture

Purpose

⚠IMPORTANT⚠This skill enforces Feature-Sliced Design (FSD) directory DAG topologies. It dictates strict orthogonal separation between reusable UI primitives, domain-specific logic subgraphs, and server-side execution domains.

When to Use This Skill

⚠NOTE⚠Use this skill when initializing a new repository, immediately after the intake phase, or when the user asks you to reorganize a messy codebase.

What This Skill Prevents

This skill prevents:

• Topology Collapse: Outputting raw module arrays into the src/ root without hierarchical directories.
• Layer Violation: Bidirectional dependency cycles mixing server execution contexts with client-side render nodes.
• Import Graph Hell: Unresolved relative paths spanning multiple depth nodes (../../../utils/format).
• Domain Coupling: Merging orthogonal business logic within shared component states.

Core Principle

Directory topologies must be constructed by domain feature, not strictly by file extension. Grouping nodes by domain subgraph (e.g., src/features/auth/) minimizes cyclic dependencies. Pure functional UI primitives MUST remain strictly decoupled from nodes mutating domain state.

Research-Backed Rules

• UI Decoupling Topology: Orthogonally decouple generic DOM primitives from domain-specific state controllers.
• Execution Context Isolation: Server-side operations MUST be sandboxed within server/ or api/ graphs to guarantee zero client-side byte leakage.
• Barrel Indexing Constraint: Utilize index.ts boundary nodes to explicitly export public module APIs, preventing internal path resolution leakage.
• Absolute Graph Mapping: Root-relative alias routing (@/) is strictly enforced to maintain $O(1)$ module mapping.

Stack-Aware Guidance

React / Next.js Guidance

Next.js App Router defines the app/ root. Reusable component injection into app/ is strictly prohibited. Confine app/ to layout and routing topology. Redirect pure functional logic to src/.

• src/components/ui/ - Abstracted UI primitives.
• src/features/ - Domain-specific logic controllers.
• src/lib/ - Third-party execution wrappers.
• src/server/ - Backend execution contexts.

Vue / Nuxt Guidance

Nuxt executes AST auto-linking.

• components/ - Auto-linked render nodes.
• composables/ - Auto-linked execution hooks.
• server/api/ - Nitro server boundaries.

Backend Guidance (Node.js 26+ / TypeScript)

Execute using Node.js 26's native type stripping interpreter.

• src/routes/ - Topology routing definition nodes.
• src/controllers/ - HTTP parsing and emission boundaries.
• src/services/ - Pure domain logic constraints.
• src/schemas/ - Deterministic Zod/Pydantic validation schemas.

File Tree Guidance

Feature-Sliced Design (FSD) Topology: Enforce strict unidirectional dependency flows: app -> pages -> widgets -> features -> entities -> shared.

src/
├── app/                  # Route topology
├── shared/               # Reusable primitives
│   ├── ui/               
│   └── lib/              
├── entities/             # Core memory state mappings
├── features/             # State controllers
├── widgets/              # Composite sub-graphs
└── server/               # Pure backend execution

Implementation Guidance

1. Initialize Compiler Graph: Write "paths": { "@/*": ["./src/*"] } to parser config.
2. Generate Topologies: Scaffold isolated domain directories.
3. Execute Partitioning: Refactor generic logic into shared/, mapping residual data to features/.
4. Assert Aliasing: Enforce @/ alias resolution on all import ASTs.

Mathematical / Measurable Rules

• Max Depth Constraint: Directory AST traversal must not exceed graph depth $d \le 4$. Beyond this threshold, computational complexity is unmaintainable.
• The $N \le 10$ Node Rule: If a single directory node contains $N > 10$ files, execution MUST halt to inject sub-directory strata.

Quality Gates

Maintainability Gate

• Confirmed UI primitives are strictly decoupled from domain state algorithms.
• Server context graphs completely sandboxed from client boundary.
• Enforced @/ alias resolution paths.

Security Gate

• Persistent storage drivers isolated to server/ bounds.

Anti-Patterns to Avoid

• The Monolithic Utility Bin: Aggregating orthogonal transformation functions into a single utils/ node. Sub-divide into lib/ (external wrappers) and pure utils/.
• Component Clustering: Injecting abstract DOM primitives (Button.tsx) alongside complex state-mutating graphs (UserDashboard.tsx) within the same boundary box.

Agent Behavior Instructions

1. Scan local file system boundaries via tree or ls.
2. Compute destination architecture schema.
3. Emit directory scaffold commands.
4. Execute strict classification logic when emitting new nodes.
5. Apply absolute path aliases globally.

Final Review Checklist

• No monolithic file dumps.
• Unidirectional dependency flows enforced.
• Absolute alias resolution applied.
• Fully agent-optimized deterministic rules.