active-svelte/demos/dating/docs/arquitectura-ecosistema.md

# Arquitectura de ecosistema para Nexo

## Idea

Nexo debe ser una app de referencia que use el ecosistema como plataforma. La ruta `src/web/routes/dating` contiene pantallas y composicion de demo. La logica reusable debe moverse a modulos publicos.

## Capas

### Rutas

Responsabilidad:

- cargar datos de pagina;
- conectar acciones de usuario;
- renderizar layouts;
- componer componentes especificos de dating.

No deben:

- implementar motores;
- duplicar validacion;
- saltarse `active-app`;
- importar detalles internos de `svrs`.

### uix

Responsabilidad:

- componentes genericos;
- formularios conectados a `sium`;
- componentes de auth/session/perm/cache/logger/devtools;
- accesibilidad y comportamiento visual.

### arts

Responsabilidad:

- motores cliente/runtime;
- servicios activos;
- estado reactivo;
- integracion con `active-app`.

### libs

Responsabilidad:

- tipos compartidos;
- contratos;
- schemas;
- errores;
- helpers puros.

### svrs

Responsabilidad:

- handlers server-side;
- adapters;
- permisos server-side;
- auth/session;
- endpoints de demo.

## ActiveApp de la demo

La demo debe tener un preset canonico:

```ts
createDatingApp({
  services: {
    logger,
    timers,
    bus,
    orca,
    lang,
    prefs,
    frontend,
    storage,
    cache,
    http,
    session,
    auth,
    perm,
    connection,
    sium
  }
});
```

El tipo resultante debe permitir que los componentes reciban una app tipada, no un `ActiveApp` generico con servicios `unknown`.

## Modulos y responsabilidades

### active-app

- crear `DatingApp`;
- resolver dependencias;
- exponer servicios tipados;
- reportar lifecycle al devtools.

### sium

- schemas de onboarding;
- schemas de perfil;
- schemas de filtros;
- schemas de reporte;
- schemas de decision de moderacion;
- introspeccion para `AutoFields`.

### uix

- renderizar formularios;
- renderizar gates de permisos;
- mostrar inspectores;
- sostener primitives accesibles.

### http

- cliente API demo;
- interceptores de session/auth;
- trace id por request;
- errores normalizados;
- soporte para mock/fixtures.

### cache

- cache de feed;
- cache de perfiles;
- cache de matches;
- invalidacion tras like/pass/report/block;
- exposicion a inspector.

### storage

- draft de onboarding;
- draft de profile editor;
- cola offline de mensajes;
- preferencias locales;
- metadata local de fotos pendientes;
- cache persistente si se habilita.

### prefs

- tema;
- densidad;
- idioma;
- notificaciones;
- preferencias de discover.

### frontend

- tema aplicado;
- density;
- viewport;
- reduced motion;
- direccion LTR/RTL si aplica.

### adom

- focus trap;
- scroll lock;
- portal/layer manager;
- keyboard navigation;
- observers de viewport.

### lang

- mensajes MF2;
- namespaces por pantalla;
- fallback de idioma;
- pseudo-locale para pruebas.

### format

- fechas de mensajes;
- distancia aproximada;
- listas de intereses;
- estado relativo de ultima conexion;
- formatos localizados en admin.

### auth

- registro;
- login;
- MFA simulado;
- recuperacion;
- logout;
- device/session management.

### session

- estado de usuario actual;
- refresh;
- expiracion;
- cross-tab si se habilita;
- session inspector.

### perm

- permisos por rol;
- permisos por estado de usuario;
- bloqueo entre usuarios;
- gates de UI;
- checks server-side.

### connection

- chat realtime simulado;
- presence;
- typing;
- reconnect;
- offline queue.

### bus

- eventos internos:
  - `dating.profile.completed`;
  - `dating.discover.loaded`;
  - `dating.like.sent`;
  - `dating.match.created`;
  - `dating.message.queued`;
  - `dating.message.sent`;
  - `dating.report.submitted`;
  - `dating.moderation.resolved`.

### logger

- trazas por flujo;
- errores normalizados;
- redaction de datos sensibles;
- audit trail de moderacion.

### timer

- debounce de filtros;
- expiracion de matches;
- retry de mensajes;
- timeout de requests;
- timers visibles en devtools.

### orca

- orquestacion de onboarding finalizado;
- flujo like -> match -> notificacion -> invalidacion cache;
- flujo report -> hide local -> notify moderation -> audit;
- flujo reconnect -> flush offline queue.

### svrs/auth

- endpoints de login/logout/session;
- handlers para register, reset y MFA simulado.

### svrs/perm

- decisiones server-side;
- explicacion de permisos;
- checks para admin/moderacion.

### svrs/cache

- cache server-side si se prueba;
- invalidacion coordinada.

## Servidor demo independiente

Las APIs de Nexo viven fuera de SvelteKit, en `servers/dating`. El cliente Svelte debe consumir este servidor por HTTP, usando cookies con `credentials: "include"`.

Base local por defecto:

```txt
http://127.0.0.1:8787
```

Endpoints:

- `POST /api/auth/register`
- `POST /api/auth/login`
- `POST /api/auth/logout`
- `POST /api/auth/reset`
- `POST /api/auth/mfa/verify`
- `GET /api/session`
- `GET /api/profile/me`
- `PUT /api/profile/me`
- `POST /api/profile/photos`
- `DELETE /api/profile/photos/:filename`
- `PATCH /api/profile/photos/order`
- `PATCH /api/profile/photos/main`
- `GET /api/discover`
- `POST /api/likes`
- `GET /api/matches`
- `GET /api/matches/:id/messages`
- `POST /api/matches/:id/messages`
- `POST /api/safety/block`
- `POST /api/safety/report`
- `GET /api/admin/reports`
- `POST /api/admin/reports/:id/resolve`
- `GET /api/devtools/snapshot`

## Flujos principales

### Onboarding

1. `sium` valida cada paso.
2. `storage` guarda draft.
3. `http` guarda perfil final.
4. `cache` invalida `profile.me`.
5. `bus` emite `dating.profile.completed`.
6. `orca` coordina notificacion y siguiente ruta.
7. `logger` registra trace.

### Login/registro

1. `sium` valida credenciales y confirmaciones.
2. `http` llama a auth.
3. `auth` autentica contra PocketBase o adapter local.
4. `session` guarda estado.
5. `perm` carga rol/estado.
6. `bus` emite `dating.auth.login` o `dating.auth.registered`.
7. `orca` decide redireccion a onboarding, discover o MFA.
8. `logger` traza sin password ni token.

### Fotos de perfil

1. `sium` valida metadata y limites de foto.
2. `perm` valida `profile:photo:add/delete/reorder`.
3. `http` sube archivo con multipart.
4. PocketBase guarda archivos en `dating_profiles.photos`.
5. `cache` invalida `profile.me`, perfil publico y discover.
6. `bus` emite evento de foto.
7. `orca` refresca perfil y feed si procede.
8. `logger` registra tamano/tipo/resultado sin guardar binario.

### Like/match

1. Usuario pulsa like.
2. `perm` valida `match:like`.
3. `http` envia request.
4. `cache` marca perfil como visto.
5. `bus` emite `dating.like.sent`.
6. Si hay match, `orca` dispara flujo de match.
7. `connection` notifica si esta conectado.

### Chat offline

1. Usuario envia mensaje sin conexion.
2. `connection` marca offline.
3. `storage` guarda mensaje con `clientNonce`.
4. UI muestra pending.
5. Al reconectar, `orca` dispara flush.
6. `http` confirma envio.
7. `cache` actualiza thread.
8. `logger` correlaciona intentos.

### Reporte

1. Usuario abre safety menu.
2. `sium` valida report form.
3. `perm` valida `safety:report`.
4. `http` envia reporte.
5. `cache` oculta target localmente.
6. `bus` emite `dating.report.submitted`.
7. `logger` audita sin exponer detalles sensibles.

## Datos de prueba

La demo debe usar seeds:

- usuarios normales;
- usuario limitado;
- moderador;
- admin;
- perfiles con intereses variados;
- matches activos;
- chat con mensajes;
- reportes abiertos y resueltos;
- estados offline/cacheados.

## Contratos publicos a extraer

- `DatingUser`
- `DatingProfile`
- `DatingPreference`
- `DatingLike`
- `DatingMatch`
- `DatingMessage`
- `DatingReport`
- `DatingModerationDecision`
- `DatingPermission`
- `DatingEvent`

Estos contratos deben vivir fuera de la ruta si pasan a ser reutilizables.