05. System Sequence Diagrams

Fase: 04 — Modelado del Sistema
Entregable: 05 de 15
Proyecto: NoteVault (PC Windows, macOS, Linux, Android, iOS / iPhone)
Estado: Formalizado y Certificado

---

1. Diagramas de Secuencia de Flujos Críticos del Sistema

Los diagramas de secuencia UML formalizan la coreografía temporal de mensajes, despacho de IPC y persistencia atómica en los flujos más sensibles del ecosistema:

1.1 Flujo 1: Edición y Guardado Atómico de Nota con Detección de Conflictos (MOD-NOTES)

sequenceDiagram
    autonumber
    actor Usuario
    participant UI as Editor CodeMirror 6
    participant Store as useApp Store (Zustand)
    participant Bridge as lib/bridge.ts
    participant Preload as Preload IPC (window.nv)
    participant PythonCore as notevault_app API
    participant FS as Sistema de Archivos Local

    Usuario->>UI: Modifica texto y presiona Ctrl + S (o espera 1500ms)
    UI->>Store: saveCurrentNote()
    Store->>Bridge: api.writeNote(path, content, frontmatter, lastMtime)
    Bridge->>Preload: ipcRenderer.invoke("note_write", payload)
    Preload->>PythonCore: handler_write_note(payload)

    PythonCore->>FS: os.stat(note_path) -> Obtener mtime en disco
    alt mtime_disco > lastMtime (Conflicto Externo)
        PythonCore-->>Preload: { ok: false, conflict: true, disk_mtime }
        Preload-->>Bridge: Retorna WriteResult(conflict=True)
        Bridge-->>Store: Notifica conflicto de concurrencia
        Store-->>UI: Despliega Diálogo Modal: "Recargar de disco o Guardar Copia"
    else mtime_disco == lastMtime (Consistente)
        PythonCore->>FS: Escribir archivo temporal "note.tmp"
        PythonCore->>FS: os.replace("note.tmp", "note.md") -> Atómico
        FS-->>PythonCore: Confirmación de I/O exitoso
        PythonCore-->>Preload: { ok: true, conflict: false, new_mtime }
        Preload-->>Bridge: Retorna WriteResult(ok=True)
        Bridge-->>Store: Actualiza note.modified = new_mtime
        Store-->>UI: Muestra confirmación silenciosa de guardado en Status Bar
    end

---

1.2 Flujo 2: Ciclo de Repetición Espaciada Activa (MOD-STUDY)

sequenceDiagram
    autonumber
    actor Estudiante
    participant UI as ReviewCalendar / StudyView
    participant SRS as studySrsManager.ts
    participant Bridge as lib/bridge.ts
    participant Storage as srs.json en Disco

    Estudiante->>UI: Inicia Repaso del Día
    UI->>SRS: getDueCards(today)
    SRS->>Storage: Carga srs.json
    Storage-->>SRS: Lista de tarjetas programadas
    SRS-->>UI: Presenta primera tarjeta (Demostración oculta)

    Estudiante->>UI: Piensa demostración y pulsa "Revelar"
    UI->>UI: Renderiza demostración completa con KaTeX
    Estudiante->>UI: Pulsa tecla de autoevaluación "4" (Bien)

    UI->>SRS: evaluateCard(cardId, grade=4)
    SRS->>SRS: Recalcula Intervalo = I_{n-1} * EF
    SRS->>SRS: Ajusta EF = EF + 0.1 - (5-4)*(0.08 + (5-4)*0.02)
    SRS->>SRS: Programa next_due = today + Intervalo
    SRS->>Bridge: api.saveSrs(updatedCards)
    Bridge->>Storage: Reemplazo atómico de srs.json
    Storage-->>Bridge: OK
    Bridge-->>UI: Avanza instantáneamente a la siguiente tarjeta (< 20 ms)

---

1.3 Flujo 3: Sesión Pomodoro y Evaluación Post-Sesión (MOD-MENTOR)

sequenceDiagram
    autonumber
    actor Usuario
    participant Ticker as TopBarPomodoro.tsx
    participant Store as usePomodoro Store
    participant Modal as PomodoroAssessmentModal.tsx
    participant FS as .notevault/mentor/sessions/

    Usuario->>Ticker: Click en "Iniciar Sesión (50 min)"
    Ticker->>Store: startPomodoro(area="Matematicas", duration=50*60)
    Store->>Ticker: Inicia cuenta regresiva en segundos (50:00 -> 00:00)

    Note over Ticker, Store: El usuario estudia con foco. El reloj llega a 00:00.

    Store->>Ticker: Emite señal sonora suave de campana
    Store->>Modal: Abre modal de evaluación con foco automático
    Usuario->>Modal: Califica concentración (5/5) y añade notas de aprendizaje
    Usuario->>Modal: Presiona "Guardar y Descansar"

    Modal->>FS: Escribe session_YYYYMMDD_HHMM.json (atómico)
    FS-->>Modal: Confirmación OK
    Modal->>Store: Inicia automáticamente descanso de 10 minutos (10:00)
    Store->>Ticker: Actualiza ticker a color menta (Modo Descanso)

---

1.4 Flujo 4: Registro de Serie de Entrenamiento y Rest Timer (MOD-EXERCISE)

sequenceDiagram
    autonumber
    actor Atleta
    participant UI as ExerciseModule.tsx
    participant Coach as exerciseCoach.ts
    participant Timer as useRestTimer Store
    participant History as history.json

    Atleta->>UI: Ingresa Peso: 90 kg, Reps: 8, RPE: 8.5
    Atleta->>UI: Click en "Completar Serie"
    UI->>Coach: calculate1RM(90, 8) -> 114 kg
    UI->>Coach: updateTotalTonnage(series) -> +720 kg
    UI->>Timer: startRestTimer(seconds=120)

    Timer-->>UI: Inicia cuenta regresiva en cabecera (02:00 -> 00:00)
    UI->>History: Guarda serie en caché local temporal

    Note over Timer: El reloj de descanso alcanza 00:00
    Timer->>UI: Emite beep sonoro + vibración háptica
    UI-->>Atleta: Notifica visualmente: "¡Descanso terminado! Inicia la siguiente serie"

---

1.5 Flujo 5: Navegación Protegida y Web Clipper a Markdown (MOD-WEB)

sequenceDiagram
    autonumber
    actor Usuario
    participant Webview as Electron Webview (persist:nvweb)
    participant NetFilter as Interceptor de Red Electron
    participant Rules as rules.json
    participant Clipper as lib/webClipper.ts
    participant Vault as Bóveda Markdown

    Usuario->>Webview: Navega a URL externa
    Webview->>NetFilter: Solicitud HTTP de navegación
    NetFilter->>Rules: Verifica dominio contra lista negra

    alt Dominio Bloqueado (en Modo Pomodoro)
        NetFilter-->>Webview: Redirige a vista local "Focus Guard: Sitio Bloqueado"
    else Dominio Permitido
        NetFilter-->>Webview: Permite conexión HTTP y renderiza página
        Usuario->>Clipper: Click en botón "Recortar a Nota"
        Clipper->>Webview: Inyecta script Mozilla Readability
        Webview-->>Clipper: Retorna DOM limpio (título, autor, HTML)
        Clipper->>Clipper: Convierte HTML a Markdown GFM y frontmatter YAML
        Clipper->>Vault: Guarda atómicamente "Recortes/Articulo.md"
        Vault-->>Clipper: OK
        Clipper-->>Usuario: Muestra toast "Nota creada" y la abre en el editor
    end

---

2. Marco Conceptual: Interacción Temporal de Secuencia

1. **Entidad principal e independiente.** 2. **Es la entidad líder del conjunto de datos:** posee un identificador global único que fija el protocolo de intercambio temporal (`sequence_interaction_id`: `SEQ-IPC-ATOMIC-SAVE`), consultado en las suites de pruebas de integración y simulación de carga. 3. **Existe por sí misma en el diseño de comunicación sin depender de los componentes gráficos**, y es la única responsable de gobernar el orden cronológico y los mecanismos de rollback ante fallos intermedios. 4. **Punto de entrada y límite de consistencia:** Si cualquier paso de la cadena falla (ej. error de I/O en disco), se garantiza el retorno ordenado de un error controlado sin mutar el estado en memoria.