¿Alguna vez has entrado a un proyecto y te has sentido perdido en un mar de carpetas genéricas como components, hooks y utils?

Es un síntoma común de deuda técnica. A medida que una aplicación escala, la ubicación del código se vuelve tan crítica como la calidad del mismo. Cuando todo es "global", nada tiene un dominio claro.

La solución no es crear más carpetas. La solución es arquitectura intencional aplicada a través de La Regla del Scope.

La Regla del Scope: Contexto es Rey

Este principio arquitectónico redefine cómo organizamos el código basándonos en su alcance de uso, no en su tipo técnico:

"La ubicación de un archivo está determinada por quién lo consume."

En lugar de agrupar archivos por su extensión o "tipo" (todos los botones juntos, todos los hooks juntos), agrupamos por funcionalidad de negocio (Feature Slicing).

1. Scope Local (1 Feature): Si un componente es exclusivo del Dashboard, vive DENTRO del directorio dashboard.
2. Scope Compartido (2+ Features): Solo si un componente se utiliza en múltiples dominios (ej: Dashboard y Perfil), se promueve a shared.

Screaming Architecture en la Era de Next.js

Tu estructura de carpetas debe "gritar" la intención del negocio, no el framework que utilizas. Esto facilita drásticamente el onboarding de nuevos desarrolladores.

❌ Estructura Silenciosa (Legacy Pattern):

src/
  components/    # ¿Botones? ¿Modales? ¿Cards de producto?
  hooks/         # ¿Lógica de bóveda? ¿Auth?
  pages/         # Rutas desconectadas de su lógica

✅ Estructura que Grita (Scope Rule):

src/
  app/
    (auth)/           # Dominio: Autenticación
      login/
      _components/    # UI exclusiva de login (LoginForm)
    (dashboard)/      # Dominio: Panel de Control
      analytics/
      _components/    # Gráficos de ventas (KPIChart)
  shared/             # UI Kit base, primitivos reutilizables

Impacto para el equipo: Un desarrollador nuevo puede abrir el repo y entender qué hace la aplicación en segundos, sin navegar grafo de dependencias complejos.

Optimización y Server Components

En Next.js 15, esta arquitectura potencia el rendimiento y la separación de responsabilidades.

• Server First Mentalily: Al mantener componentes cerca de sus rutas (app/dashboard/_components), es natural escribirlos como Server Components, reduciendo el JS bundle enviado al cliente.
• Colocación de Actions: Tus _actions.ts viven junto al formulario que los invoca. Alta cohesión, bajo acoplamiento.

Caso de Estudio: Widget de Precios

Imagina un PriceWidget complejo que solo existe en el Checkout.

• Enfoque Tradicional: Lo pones en src/components/PriceWidget.tsx. Contaminas el scope global con lógica de negocio específica.
• Enfoque Scope Rule: Vive en src/app/(shop)/checkout/_components/price-widget.tsx.

Resultado: Código modular. Si mañana eliminas la feature de checkout, eliminas su carpeta y el código muerto desaparece automáticamente. Mantenibilidad garantizada.

Checklist para una Arquitectura Robusta

Antes de crear un archivo, aplica este filtro de decisión:

1. 🛑 ¿Alcance?

   • 1 Feature → Local (_components, _hooks).
   • 2+ Features → Shared (shared/ui).

2. ⚡ ¿Entorno?

   • Prioriza Server Components por defecto.
   • Usa 'use client' solo en las hojas del árbol de componentes (interactividad específica).

3. 📢 ¿Semántica?

   • Usa Route Groups (auth), (shop) para organizar dominios sin afectar la URL.

La arquitectura no son reglas rígidas; es comunicación. Al adoptar la Regla del Scope, escribes código que explica su propio propósito, facilitando la vida a tu equipo actual y a los desarrolladores del futuro.