file-tree-architecture

name	File Tree Architecture
description	DEFINIR dónde viven los archivos en un proyecto full-stack. Hacer cumplir el flujo de dependencia unidireccional (app → pages → widgets → features → entities → shared). Prevenir volcados planos en src/, importaciones enredadas y mezcla de código de servidor y cliente. Activadores: inicializar nuevo repositorio, reestructurar base de código desordenada o cualquier solicitud de "set up the file structure".
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":"CREAR andamiaje de directorios como se especifica abajo"},{"pattern":"organize (the|this|my) codebase","action":"ESCANEAR estructura actual → RECOMENDAR migración"},{"pattern":"refactor (the|this) project structure","action":"ESCANEAR → RECOMENDAR → REESTRUCTURAR archivos"}]
related_skills	["professional-project-intake","component-architecture-patterns","saas-app-structure"]
lang	es
direction	ltr
source_version	3.0.0
translated_at	2026-06-29T00:00:00.000Z

Arquitectura de Árbol de Archivos Full-Stack

IDENTIFICAR: Cuándo activarse

Activar cuando:

• Se inicializa un nuevo proyecto (después de la fase de ingesta)
• El usuario dice "directory structure", "file structure", "organize this"
• La base de código existente tiene directorios planos (≥15 archivos en la raíz de src/)
• Las importaciones usan patrones ../../../ (profundidad ≥3 referencias al padre)

DECIDIR: Selección de Plantilla de Directorios

SI se detecta framework = Next.js (App Router) →
  USAR plantilla Next.js (Paso 1)

SI se detecta framework = Vue / Nuxt →
  USAR plantilla Vue/Nuxt (Paso 2)

SI se detecta framework = solo backend (Express, FastAPI, Django) →
  USAR plantilla backend (Paso 3)

SI es proyecto existente, ESCANEAR estructura existente primero:
  SI el proyecto ya tiene estructura organizada →
    SEGUIR convenciones existentes. NO reorganizar sin aprobación del usuario.
  SI el proyecto está desorganizado →
    PRESENTAR estructura recomendada al usuario. Obtener aprobación antes de mover archivos.

EJECUTAR: Instrucciones

Paso 1: Next.js (App Router): Estándar 2026

raíz-del-proyecto/
├── app/                            # SOLO RUTAS Y DISEÑOS
│   ├── (marketing)/                # Grupo de rutas: páginas públicas
│   │   ├── page.tsx
│   │   └── layout.tsx
│   ├── (dashboard)/                # Grupo de rutas: páginas autenticadas
│   │   ├── dashboard/
│   │   │   └── page.tsx
│   │   └── layout.tsx
│   ├── api/                        # Manejadores de ruta
│   │   └── users/
│   │       └── route.ts
│   └── proxy.ts                    # (Next.js 16+) Reemplaza middleware.ts
├── src/
│   ├── components/
│   │   └── ui/                     # Presentacional: Button, Card, Input, SIN lógica de negocio
│   ├── features/                   # Lógica específica de dominio (una carpeta por funcionalidad)
│   │   ├── auth/
│   │   │   ├── actions.ts          # Server Actions
│   │   │   ├── auth.config.ts      # Configuración Auth.js / Better Auth
│   │   │   └── components/         # Específico de auth: LoginForm, SignUpForm
│   │   └── billing/
│   │       ├── actions.ts
│   │       ├── stripe.ts           # Servicio Stripe (solo servidor)
│   │       └── components/
│   ├── lib/                        # Wrappers de servicios de terceros
│   │   ├── stripe.ts
│   │   └── email.ts
│   ├── server/                     # SOLO BACKEND, nunca importado por el cliente
│   │   ├── db/
│   │   │   └── schema.prisma       # Esquema Prisma, o:
│   │   │   └── schema.ts           # Esquema Drizzle
│   │   └── queries/
│   └── utils/                      # Funciones puras, SIN efectos secundarios, SIN importaciones de server
│       ├── cn.ts                   # clsx + twMerge
│       └── format.ts
├── public/
├── package.json
└── tsconfig.json

REGLAS APLICADAS: