Comando	Descripción
`npm run dev`	Servidor de desarrollo
`npm run build`	Build de producción (standalone)
`npm run start`	Sirve el build de producción
`npm run typecheck`	Comprueba tipos sin emitir

Arquitectura

src/
├── app/                  # Rutas (App Router)
│   ├── inbox/            # Issues asignados al usuario
│   ├── issues/           # Lista de issues
│   │   └── [id]/         # Detalle de un issue
│   ├── board/            # Tablero Kanban
│   ├── cycles/           # Ciclos / sprints
│   └── projects/         # Proyectos
│       └── [id]/         # Detalle de proyecto
├── components/
│   ├── layout/           # Sidebar, Topbar, AppShell, palette
│   ├── issues/           # IssueList, IssueRow
│   ├── board/            # Tablero Kanban
│   └── ui/               # Avatar, iconos, etiquetas, progreso
├── hooks/
│   └── useIssues.ts      # Carga de issues con filtros y refresco
└── lib/
    ├── types.ts          # Modelo de dominio (contrato con SAM)
    ├── meta.ts           # Definiciones de estado/prioridad/tipo
    ├── format.ts         # Helpers de formato de fechas
    ├── seed.ts           # Datos de ejemplo (mock)
    ├── store.tsx         # Contexto de datos de referencia
    └── api/
        ├── client.ts     # Interfaz ProyectosApi
        ├── mock.ts       # Implementación en memoria
        └── index.ts      # Selección de implementación

Capa de datos

Toda la app habla contra la interfaz ProyectosApi (src/lib/api/client.ts), nunca contra una implementación concreta. Hay dos implementaciones:

httpApi (src/lib/api/http.ts): la real, contra SAM.API. Es la que se usa por defecto.
mockApi (src/lib/api/mock.ts): datos en memoria sobre src/lib/seed.ts, para desarrollar la UI sin backend. Se activa con NEXT_PUBLIC_USE_MOCK=true.

La selección está en src/lib/api/index.ts. Para cambiar de implementación no hay que tocar componentes, hooks ni páginas: el contrato no cambia.

Autenticación

La API key global de SAM (X-Api-Key) nunca llega al navegador.

El navegador llama a /api/proyectos/* en el mismo origen. Ese route handler (src/app/api/proyectos/[...path]/route.ts) reenvía la petición a SAM.API añadiendo la cabecera en el servidor.

La clave vive en SAM_API_KEY, sin prefijo NEXT_PUBLIC_. Next.js solo inyecta en el bundle JS las variables NEXT_PUBLIC_*, así que esta queda restringida al proceso del servidor.

Sesión de usuario

AuthProvider (src/lib/auth.tsx) guarda en localStorage el miembro devuelto por POST /api/proyectos/auth/login, que valida contra sige_sam_v3.usuario. Ese idUsuario es quien firma los comentarios y filtra la bandeja.

Nota: los tipos de src/lib/types.ts son el contrato esperado del backend. Los endpoints de SAM.API devuelven esta misma forma.

Despliegue en SAM

Sigue el patrón de módulo de SAM: frontend independiente conectado a la API compartida a través de la red sam-net.

Dockerfile: build standalone de Next.js.
docker-compose.module.yml: servicio proyectos-frontend con healthcheck.

Dentro de la red sam-net el frontend alcanza el backend por nombre de contenedor: SAM_API_URL=http://sam-api:5000.

SAM_API_KEY se inyecta desde el entorno del host (${SAM_API_KEY} en el compose); no se escribe en el archivo.

Variables de entorno

Variable	Quién la lee	Descripción
`SAM_API_URL`	servidor	URL base de `SAM.API`. Por defecto `http://127.0.0.1:5000`.
`SAM_API_KEY`	servidor	API key global de SAM (`X-Api-Key`). Sin ella el proxy responde 503.
`NEXT_PUBLIC_MODULE`	cliente	Identificador del módulo (informativo).
`NEXT_PUBLIC_USE_MOCK`	cliente	`true` para usar datos mock en memoria sin backend.

SAM_API_URL y SAM_API_KEY no llevan prefijo NEXT_PUBLIC_ a propósito: solo las ve el proceso del servidor, así que la clave no se empaqueta en el JavaScript que descarga el navegador.