Visión de Arquitectura¶
Proyecto: {{PROJECT_NAME}} · Clase SaMD: {{SAMD_CLASS}} · Versión: v0.1 · Fecha: 2026-01-01
Plantilla del SaMD Starter Kit. Reemplazá los marcadores
{{...}}y ajustá el diagrama a tu topología real.
1. Principios de arquitectura¶
- Offline-first: toda mutación de datos pasa primero por un almacén local (cola/outbox) → sincronización. Nunca eludir el motor de sincronización.
- Identidad desde el token: la identidad del sujeto se deriva exclusivamente del token verificado, nunca de un
idrecibido en body o query. - Fail-safe explícito (ISO 14971): el fallo degrada de forma segura y visible.
- Asincronía: I/O no bloqueante en el backend.
- Tipado estricto y errores empáticos: sin tracebacks ni metadatos internos hacia el cliente.
2. Diagrama de alto nivel¶
flowchart TD
subgraph CLIENT["Cliente — offline-first"]
UI["UI accesible"] --> CACHE["Cache / Query"]
CACHE --> STORE[("Almacén local<br/>IndexedDB / SQLite")]
STORE --> OUTBOX["Outbox"]
OUTBOX --> SYNC["Sync engine"]
SYNC -. render .-> UI
end
CLIENT -->|"HTTPS + token verificado"| API
subgraph API["Backend — API + lógica"]
AUTH["Auth"] --> ROUTERS["Routers"]
ROUTERS --> SERVICES["Services"]
SERVICES --> AUDIT["Audit middleware"]
SERVICES --> FAILSAFE["Fail-safe<br/>503 + Retry-After"]
end
API --> IDP["Proveedor de identidad"]
API --> DB[("Base de datos<br/>cifrado en reposo")]
API --> EXT["Servicios externos<br/>IA · email · pagos"]
subgraph CLOUD["Plataforma cloud"]
OPS["Cómputo · Migraciones · Scheduler<br/>Secret Manager · Logs · Monitoring"]
end
DB --- CLOUD
3. Decisiones clave de arquitectura¶
4. Ítems de software y clase de seguridad (IEC 62304 §5.3)¶
Clasificá cada ítem: A (no contribuye a daño), B (daño no serio posible), C (daño serio o muerte posible). El producto hereda la clase del ítem más alto salvo segregación demostrada.
5. Puntos de fail-safe (ISO 14971)¶
| Punto | Modo de fallo | Comportamiento seguro esperado |
|---|---|---|
| Pérdida de red en cliente | Sin backend | Operar offline; encolar mutaciones; avisar estado, no bloquear |
| Backend saturado (pool BD agotado) | 503 | Degradar con 503 + Retry-After; mensaje empático; sin traceback |
| Fallo de algoritmo clínico | Excepción | No mostrar resultado dudoso; estado "no disponible"; registrar incidente |
| Fallo de servicio de IA | Timeout/error | Degradar a flujo sin IA; nunca inventar dato clínico |
| Fallo de migración | Schema inconsistente | Abortar deploy; mantener versión previa |
6. Versionado de este documento¶
| Versión | Fecha | Autor | Cambio |
|---|---|---|---|
| v0.1 | 2026-01-01 | {{OWNER}} | Plantilla inicial |
Navegación: Índice del DHF · Master Map