System

apps/system/README.md

apps/system

Aplicación principal de administración de Nidus. Es una aplicación Next.js 16 con App Router que gestiona autenticación, comunidades, usuarios, propiedades, obras, infracciones, accesos y configuración.

Este README es el punto de entrada para entender la app. Para reglas transversales leer primero AGENTS.md, packages/README.md y .opencode/rules/packages.md.

Qué pertenece a system

system contiene pantallas, composición visual y flujos específicos del producto administrativo. La app consume packages compartidos, pero no debe duplicar sus adapters, schemas, constantes globales ni componentes UI.

ÁreaDocumentación
Arquitectura y límitesdocs/architecture.md
Rutas, layouts y permisosdocs/routes-and-permissions.md
Autenticación y sesiónmodules/auth/README.md
Componentes y utilidades transversalesmodules/shared/README.md
Módulos de negociomodules/README.md

Stack y configuración

  • Next.js 16.1.7, React 19.2.3, TypeScript y App Router.
  • Tailwind CSS v4 con tokens de @repo/ui.
  • Firebase Client mediante @repo/firebase-client-adapter.
  • Casos de uso mediante @repo/app-services.
  • Errores tipados mediante @repo/app-errors; @repo/client-operations ejecuta queries y mutations.
  • Schemas y tipos compartidos mediante @repo/schemas.
  • Zustand mediante @repo/zustand.
  • PWA mediante Serwist.
  • Tests con Vitest en entorno configurado por la app.

app/layout.tsx es Client Component porque inicializa el contexto raíz mediante useRootLayout. Mientras el contexto no está listo muestra el loader global. El layout de (dashboard) inicializa auth, navegación, sidebar y toaster; el layout de (auth) solo agrega el toaster del flujo de autenticación.

Estructura real

text
apps/system/
├── app/                         # Rutas, layouts, metadata, PWA y estilos de la app
├── modules/
│   ├── access/                  # Registro y consulta de accesos
│   ├── auth/                    # Sesión, registro, login, invitaciones y onboarding
│   ├── configuration/           # Configuración de la comunidad/organización
│   ├── estates/                 # Propiedades/estates
│   ├── information/             # Contactos, normas y FAQ con errores tipados
│   ├── infractions/             # Infracciones y resolución
│   ├── shared/                  # UI y utilidades transversales de system
│   ├── users/                   # Gestión de usuarios e invitaciones
│   └── works/                   # Obras, documentación y personal
├── constants/                   # Constantes exclusivas de system
├── public/                      # Assets públicos, si aplica
├── apphosting.test.yaml         # Configuración App Hosting de test
├── next.config.ts
├── package.json
├── tsconfig.json
└── vitest.config.ts

ClientOperationsProvider se monta una sola vez en app/root-layout-client.tsx. Para Information, los servicios entregan AppError con códigos estables y modules/information/utils/information-error.ts los convierte en copy seguro para toasts y estado de página. No mostrar error.message directamente. El flujo y su catálogo están descritos en la guía de Information.

Regla para crear código

  1. Buscar primero la API existente en packages/README.md y el README del package candidato.
  2. Si es visual y reutilizable entre apps, usar @repo/ui; si es específico de system, usar el módulo correspondiente.
  3. Si es un schema, entidad o payload compartido, usar @repo/schemas.
  4. Si es una operación cliente reutilizable, usar @repo/app-services.
  5. Mantener en modules/<domain> los componentes, hooks, mocks y tipos que solo conoce system.
  6. No llamar Firebase SDK directamente desde componentes; usar adapter o service.
  7. No duplicar roles, permisos, rutas globales ni schemas existentes.

Desarrollo

Desde la raíz del monorepo:

bash
pnpm --filter system dev
pnpm --filter system lint
pnpm --filter system test
pnpm --filter system build

La app usa next dev --webpack. El puerto por defecto es 3000, salvo que esté ocupado.

Variables y deploy

La configuración de App Hosting está en apphosting.test.yaml. Actualmente define el ambiente y las variables públicas de Firebase disponibles en build y runtime. Las variables NEXT_PUBLIC_* pueden llegar al navegador; nunca colocar secretos server-side allí.

El deploy de esta app se realiza mediante Firebase App Hosting. Antes de desplegar validar lint, tests y build. Revisar también que el proyecto Firebase seleccionado y el archivo de App Hosting correspondan al ambiente deseado.

Testing

Los tests de lógica y hooks viven junto al módulo probado con sufijo .test.ts o .test.tsx. La configuración Vitest usa happy-dom y cubre componentes, hooks, utilidades y errores. Para Information, la cobertura se reparte por frontera:

  • Schemas: estructura persistida, campos requeridos/opcionales, auditoría y updates parciales.
  • Servicio: permisos, transacciones, CRUD, suscripciones, normalización de errores y cleanup de Storage.
  • Hooks/UI: contexto de comunidad/rol/usuario, payloads, caché realtime, retry, formularios y borrado.
  • Utilidades: límites de tamaño, extensión/MIME de documentos y mensajes de error seguros.

Mockear adapters, servicios externos y estado cuando corresponda. Tests con adapters mockeados no demuestran autorización de Firestore/Storage; eso requiere tests de Security Rules en el emulador.

bash
pnpm --filter system test
pnpm --filter system lint
pnpm --filter system exec tsc --noEmit
pnpm --filter system build

El detalle del módulo y sus comandos por package está en la guía de Information.