# Sistema de Transcripciones — Arquitectura

> Documentación oficial del pipeline transcripciones en Alpha.
> Este patrón se hereda a RUMBO.

---

## Filosofía

```
BD (Dexie/SQLite) = Fuente de verdad
Markdown           = Output generado (nunca se edita manualmente)
```

El markdown es un **artefacto derivado**. Siempre se regenera desde la BD.
Si necesitás modificar algo, se actualiza la BD y se regenera el `.md`.

---

## Estructura de Datos

```
┌─────────────────────────────────────────────────────────────┐
│                      DATABASE (Dexie/IndexedDB)              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  sessions                                                    │
│  ├── id: number                 ← PK autoincrement          │
│  ├── projectId: number          ← FK a proyectos            │
│  ├── date: string               ← Fecha de la sesión        │
│  ├── title: string              ← Título (ej: "Kickoff")    │
│  ├── fileName: string           ← Archivo original subido   │
│  ├── fileType: string           ← docx|vtt|txt|md           │
│  ├── fileSize: number           ← bytes                     │
│  ├── rawText: string            ← Texto completo parseado   │
│  └── processedAt: string        ← ISO timestamp             │
│                                                             │
│  session_summaries                                           │
│  ├── sessionId: number          ← PK = FK → sessions.id     │
│  ├── summary: string            ← Resumen ejecutivo         │
│  ├── objectives: string         ← JSON array                │
│  ├── tasks: string              ← JSON array                │
│  ├── commitments: string        ← JSON array                │
│  ├── decisions: string          ← JSON array                │
│  ├── keyPoints: string          ← JSON array                │
│  └── modelUsed: string          ← Modelo IA usado           │
│                                                             │
│  project_state                                               │
│  ├── projectId: number          ← PK                        │
│  ├── summary: string            ← Resumen consolidado       │
│  ├── objectives: string         ← JSON array (unificado)    │
│  ├── tasks: string              ← JSON array (consolidado)  │
│  ├── commitments: string        ← JSON array (consolidado)  │
│  └── updatedAt: string          ← ISO timestamp             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                      OUTPUT (Markdown)                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  📄 master-[proyecto].md                                    │
│                                                             │
│  ├── BLOQUE 1 — Consolidado Global                          │
│  │   ├── Resumen ejecutivo (desde project_state)            │
│  │   ├── Objetivos                                          │
│  │   ├── Tareas pendientes (con checkbox)                   │
│  │   └── Compromisos (con estados)                          │
│  │                                                          │
│  └── BLOQUE 2 — Detalle por Sesión                          │
│      ├── 📍 Sesión YYYY-MM-DD — Título                      │
│      │   ├── Resumen                                        │
│      │   ├── Objetivos                                      │
│      │   ├── Tareas                                         │
│      │   ├── Compromisos                                    │
│      │   └── Transcripción completa                          │
│      └── ...                                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Flujo Completo

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  SUBIR   │ →  │  PARSEAR │ →  │ GUARDAR  │ →  │ EXTRAER  │
│  .docx   │    │  .vtt    │    │  EN BD   │    │  CON IA  │
│  .vtt    │    │  .txt    │    │ sessions │    │          │
│  .txt    │    │  .md     │    │          │    │          │
│  .md     │    │          │    │          │    │          │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
                                                      │
                                                      ▼
                                              ┌──────────┐
                                              │ GUARDAR  │
                                              │  RESULT  │
                                              │   EN BD  │
                                              │summaries │
                                              └──────────┘
                                                      │
                                                      ▼
                                              ┌──────────┐
                                              │ ACTUALIZ │
                                              │  project │
                                              │  _state  │
                                              └──────────┘
                                                      │
                                                      ▼
                                              ┌──────────┐
                                              │ GENERAR  │
                                              │  .md     │
                                              └──────────┘
```

### Paso a paso

| Paso | Acción | Tabla afectada |
|------|--------|----------------|
| 1 | Usuario sube archivo(s) | — |
| 2 | Parsear a texto plano (mammoth para .docx, regex para .vtt) | — |
| 3 | Guardar transcripción cruda en BD | `sessions` (INSERT) |
| 4 | Enviar a IA para extracción estructurada | — |
| 5 | Guardar resultado de IA en BD | `session_summaries` (INSERT) |
| 6 | Recalcular estado consolidado del proyecto | `project_state` (UPSERT) |
| 7 | Regenerar documento markdown | — (derivado de BD) |

---

## Por qué dual storage (BD + Markdown)

| Problema | Solución con BD |
|----------|----------------|
| Buscar dentro de transcripciones viejas | `SELECT * FROM sessions WHERE rawText LIKE '%keyword%'` |
| Marcar tarea como completada | `UPDATE project_state SET tasks = ...` sin re-procesar nada |
| Regenerar Bloque 1 al agregar sesión nueva | Read de BD, no re-procesar sesiones anteriores |
| Versiones históricas | Cada sesión es un registro independiente |
| Compartir con alguien que no tiene la app | Exportar `.md` — es legible en cualquier editor |
| Backup | La BD se puede respaldar; el `.md` es un snapshot legible |

### Por qué el markdown NO es fuente de verdad

- **No se edita manualmente.** Si alguien modifica el `.md`, esos cambios se pierden al regenerar.
- **Es un snapshot.** Siempre se puede regenerar desde la BD.
- **Es portable.** Se puede compartir, subir a GitHub, etc.

---

## Comparación con la implementación anterior

| Aspecto | Antes (v1) | Ahora (v2) |
|---------|------------|------------|
| Storage | Solo markdown en `project_docs` | BD estructurada + markdown generado |
| Transcripciones | Solo en memoria | Persistidas en `sessions` |
| Búsqueda | Imposible | Query SQL por texto |
| Estado consolidado | Recalculado cada vez desde las sesiones | Cacheado en `project_state` |
| Editar tarea | Había que re-procesar la sesión | UPDATE directo a `project_state` |
| Sesiones individuales | Incrustadas en markdown | Registros independientes |

---

## Consideraciones para RUMBO

En RUMBO (Tauri + Turso/libSQL), el schema es idéntico pero cambia el engine:

```
Alpha (browser):   Dexie + IndexedDB   →   Markdown descargable
RUMBO (desktop):   Turso + libSQL      →   Markdown exportable + auto-sync
```

Las tablas, tipos y flujo son los mismos. Solo cambia:
- `db.sessions.put()` → `INSERT OR REPLACE INTO sessions`
- El markdown se escribe a archivo en `~/RUMBO/projects/[id]/master.md`

---

*Documentado: 2026-05-28*
*Validado en: Alpha*
*Destino: RUMBO*