Diagramas del sistema¶

Diagramas Mermaid de los flujos principales del sistema. Renderizados nativamente por el plugin mkdocs-mermaid2-plugin.

Topología de despliegue (modo producción)¶

Flujo OAuth2 + PKCE (móvil)¶

sequenceDiagram
    participant U as Usuario
    participant App as Flutter App
(Android/iOS)
    participant KC as Keycloak
    participant API as custodiam-api

    U->>App: Toca "Iniciar sesión"
    App->>App: Genera code_verifier + code_challenge
(_pendingGrant en memoria)
    App->>KC: Abre Custom Tab con
authorize?code_challenge=...
    KC-->>U: Pantalla de login
    U->>KC: Credenciales (usuario + password)
    KC-->>App: Redirige a
es.custodiam://callback?code=...
    Note over App: Deep link captura el code
    App->>KC: POST /token
code + code_verifier
    KC-->>App: access_token + refresh_token
    App->>App: Guarda en flutter_secure_storage
    App->>API: GET /me
Authorization: Bearer 
    API->>API: Valida JWT localmente con PyJWT
(usa JWKS cacheado)
    API-->>App: 200 OK + datos del voluntario

Flujo OAuth2 + PKCE (web)¶

sequenceDiagram
    participant U as Usuario
    participant Web as PWA Web
(Flutter Web)
    participant SS as sessionStorage
    participant KC as Keycloak
    participant API as custodiam-api

    U->>Web: Click "Iniciar sesión"
    Web->>Web: Genera code_verifier + code_challenge
    Web->>SS: Persiste code_verifier
(clave: custodiam.oauth.code_verifier)
    Web->>KC: window.location = authorize?code_challenge=...
(webOnlyWindowName: '_self')
    Note over Web: ⚠️ Recarga completa del navegador
    KC-->>U: Pantalla de login
    U->>KC: Credenciales
    KC-->>Web: Redirige a
https://app.custodiam.es/callback?code=...
    Note over Web: GoRouter (PathUrlStrategy) matcha /callback
    Web->>SS: Lee code_verifier
    Web->>KC: POST /token
code + code_verifier
    KC-->>Web: access_token + refresh_token
    Web->>SS: Limpia code_verifier
Guarda tokens en sessionStorage
    Web->>API: GET /me
Authorization: Bearer 
    API-->>Web: 200 OK + datos del voluntario

Flujo de notificación de emergencia¶

sequenceDiagram
    participant Coord as Coordinador
(usuario)
    participant App as App Coord
    participant API as custodiam-api
    participant FCM as Firebase FCM
    participant NTFY as ntfy
    participant Volunt as App Voluntario
(N dispositivos)

    Coord->>App: Crea convocatoria de emergencia
    App->>API: POST /servicios
tipo=emergencia, voluntarios_filtrados
    API->>API: Filtra voluntarios disponibles + permisos
    API->>FCM: Envía push a tokens FCM
(canal principal)

    alt FCM responde 200
        FCM-->>Volunt: Push notification
(notificación + datos del servicio)
        Note over Volunt: Voluntario toca → abre app en pantalla del servicio
    else FCM falla o timeout > 5s
        API->>NTFY: Publica al canal /custodiam-emergencia
(canal de respaldo)
        NTFY-->>Volunt: Push via ntfy
(canal secundario)
        Note over API: Log de fallo de FCM
+ telemetría para análisis
    end

    Volunt->>API: PATCH /servicios/{id}/voluntarios/{me}
{respuesta: "acepto" | "rechazo"}
    API-->>App: Notifica al coordinador
(via FCM tambien)

Despliegue del book de documentación¶

Referencias¶

• Stack técnico — tecnologías concretas con versiones.
• ADRs — decisiones arquitectónicas que sostienen estos diagramas.