# Arquitectura — El Bajo Manager

## Principios

1. **Admin-only**: una sola persona opera el panel; no hay portal de huéspedes.
2. **Notion como base de datos**: no hay Postgres/SQLite propio.
3. **Modular por dominio**: cada módulo encapsula tipos, mappers, repository y UI.
4. **Fase 2 sin reescritura**: nuevos módulos se registran en `config/modules.ts` y viven en `src/modules/<id>/`.
5. **API boundary**: el cliente React Query solo habla con `/api/*`; Notion vive en el servidor.

## Diagrama de capas

```
┌─────────────────────────────────────────────────────────┐
│  UI (App Router pages + componentes de módulo)          │
│  React Query hooks → fetch /api/*                       │
├─────────────────────────────────────────────────────────┤
│  API Routes (Next.js Route Handlers)                    │
│  Validación ligera + orquestación                       │
├─────────────────────────────────────────────────────────┤
│  Domain modules                                         │
│  rooms | guests | finance | cleaning | dashboard        │
│  (+ stubs Fase 2: maintenance, incidents, …)            │
├─────────────────────────────────────────────────────────┤
│  Notion adapter                                         │
│  client · config · helpers · mappers                    │
│  mock fallback (USE_MOCK_DATA)                          │
└─────────────────────────────────────────────────────────┘
```

## Estructura de carpetas

```
src/
  app/                          # Rutas Next.js (UI + API)
    api/
      dashboard|rooms|guests|finance|cleaning/
    habitaciones|huespedes|finanzas|limpieza/
  components/
    layout/                     # Sidebar, mobile header
    shared/                     # PageHeader, StatusBadge, StatCard…
    dashboard|rooms|guests|finance|cleaning/
    ui/                         # Shadcn
  config/
    modules.ts                  # Registro de módulos (Fase 1 + 2)
  hooks/
    use-modules.ts              # React Query
  lib/
    notion/                     # Cliente y helpers Notion SDK v5
    mock/                       # Datos demo
    query/                      # QueryProvider
    constants.ts | format.ts | utils.ts
  modules/                      # Dominio (sin UI)
    rooms|guests|finance|cleaning|dashboard/
      mappers.ts
      repository.ts | service.ts
  types/
    domain.ts                   # Contratos de dominio
docs/                           # Arquitectura, schema, wireframes
```

## Flujo de datos (lectura)

1. Página cliente monta un hook (`useRooms`, `useDashboard`…).
2. El hook llama a `/api/<recurso>`.
3. El route handler invoca el repository del módulo.
4. Si `useMock` → datos demo; si no → `dataSources.query` (Notion).
5. El mapper convierte propiedades Notion → tipos de dominio.
6. La UI renderiza con componentes compartidos.

## Extensión (nuevo módulo)

1. Añadir entrada en `APP_MODULES` (`status: "active"`).
2. Crear `src/modules/<id>/{mappers,repository}.ts`.
3. Crear `src/app/api/<id>/route.ts`.
4. Crear `src/app/<ruta>/page.tsx` + componente en `components/<id>/`.
5. Añadir hook en `use-modules.ts`.
6. Si necesita DB Notion: documentar en `NOTION_SCHEMA.md` y env var.

No tocar `lib/notion/client.ts` ni el layout salvo que el módulo requiera navegación nueva (ya cubierta por `ACTIVE_NAV`).

## Decisiones clave

| Decisión | Motivo |
|----------|--------|
| React Query en cliente | Caché, refetch y UX rápida en móvil |
| Repositories server-side | Token Notion seguro |
| Mappers explícitos | Aíslan cambios de schema Notion |
| Mock data | Desarrollar UI sin credenciales |
| `modules.ts` registry | Activar Fase 2 sin refactor de nav |
| Un solo inmueble | Scope simple; multi-propiedad = Fase 3+ |

## Seguridad (mínimo viable)

- Token solo en variables de servidor.
- Sin auth de huéspedes (Fase 1).
- Recomendado antes de producción: proteger el panel con Vercel Auth / middleware básico / Basic Auth.