Arquitectura Lógica

El diseño arquitectónico de Lynx Next.js se basa firmemente en el patrón del App Router de Next.js 16, logrando una estricta separación entre Componentes de Servidor (Server Components) y Componentes de Cliente (Client Components).

Flujo de Datos y Componentes

El siguiente diagrama detalla cómo las distintas capas interactúan dentro del ciclo de vida de una solicitud:

graph TD
    A[Next.js App Router] --> B(Server Components)
    A --> C(Client Components)

    B --> D[Paquetes Compartidos]
    C --> D

    D --> E(@lynx/ui)
    D --> F(next-intl i18n)
    D --> G(@lynx/core)
    D --> H(@lynx/models)

    style A fill:#000000,stroke:#333,stroke-width:2px,color:#fff

Estructura de Directorios

Nuestra estructura promueve la modularidad y el aislamiento de responsabilidades:

• proxy.ts: Único punto de entrada del middleware. Todas las reescrituras (rewrites), encabezados HTTP y validaciones de sesión pasan por aquí, en lugar del tradicional middleware.ts.
• src/app/[locale]/: Directorio principal del enrutador. Todas las rutas se anidan bajo un parámetro de idioma para garantizar un i18n predecible.
  • (app)/(public)/: Páginas legales y públicas.
  • (app)/(private)/: Zonas seguras que utilizan el cliente de @lynx/auth.
  • docs/: Contenido servido usando metadatos dinámicos, acoplado con content/**.
• src/components/: Componentes React específicos de la aplicación que no tienen cabida en @lynx/ui.
• src/modules/: Lógica de negocio delimitada por dominio (ej. database, auth, mail, i18n).
• src/lib/: Helpers y envolturas para servicios de terceros (Stripe, Lemon Squeezy, etc.).

Estándares de Enrutamiento y i18n

[!CAUTION] Adición de Nuevas Rutas Cuando crees una nueva ruta en la aplicación, debes actualizar estrictamente tres lugares para mantener el soporte multilenguaje y las migas de pan (breadcrumbs):

1. src/modules/i18n/routing.ts: Añadir la ruta al objeto pathnames.
2. src/modules/i18n/breadcrumbs.ts: Registrar el segmento en BREADCRUMB_REGISTRY.
3. messages/*.json: Agregar la traducción correspondiente bajo la clave "breadcrumbs" en todos los diccionarios soportados (ej. en.json, es.json).

Capa de Interfaz de Usuario (UI)

Nuestra aplicación requiere que utilicemos siempre Componentes de @lynx/ui en lugar de etiquetas HTML en crudo.

Correcto

import { Title, Columns, Button } from '@lynx/ui';
import { Link } from '@/components/(ui)/link';

export function MiComponente() {
  return (
    <Columns>
      <Columns.Column>
        <Title size="3">Hola Mundo</Title>
        <Link href="/dashboard">
          <Button>Ir al Panel</Button>
        </Link>
      </Columns.Column>
    </Columns>
  );
}

Incorrecto

// ❌ Evitar HTML crudo y etiquetas de anclaje estándar
export function MiComponente() {
  return (
    <div className="columns">
      <div className="column">
        <h3>Hola Mundo</h3>
        <a href="/dashboard">
          <button>Ir al Panel</button>
        </a>
      </div>
    </div>
  );
}

[!NOTE] Al configurar la clase Section para diseños que abarcan todo el ancho (como landing pages o hero sections), recuerda pasar explícitamente el parámetro fullwidth, ya que el componente por defecto está acotado a un max-width de 800px.