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:

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:

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.