# Alpha — Documento Técnico

> **Alpha = KAPPA Hub**. Aplicación Tauri + Vue 3 para gestión multi-proyecto.
> Semilla de RUMBO. POC en producción como herramienta de Business Analyst.

**Versión**: 0.1.0 | **Fecha**: 2026-05-26 | **Autor**: Ricardo Gonzalez (Teloprax)

---

## 1. Stack tecnológico

| Capa | Tecnología | Versión |
|------|-----------|---------|
| Desktop shell | Tauri v2 | 2.11 |
| Frontend | Vue 3 + TypeScript + Vite | 3.4 / 5.x |
| Runtime JS | Bun | 1.3+ |
| Estado | Pinia | 2.1 |
| Base de datos local | Turso (libSQL) | Embedded |
| Cache navegador | Dexie.js (IndexedDB) | 4.0 |
| UI Components | shadcn-vue (reka-ui) | 2.7 / New York |
| Estilos | Tailwind CSS v4 | 4.3 |
| Tablas | @tanstack/vue-table → AG Grid | 8.21 / planned |
| i18n | vue-i18n | 11.4 |
| Iconos | Lucide + Tabler Icons | — |
| HTTP | fetch() nativo | — |
| Auth | Bearer token KAPPA | — |

## 2. Arquitectura

```
┌──────────────────────────────────────────────┐
│                  Alpha (Tauri)                │
│                                              │
│  ┌──────────┐  ┌───────────┐  ┌───────────┐  │
│  │ Vue 3 FE │  │  Pinia    │  │  Dexie.js │  │
│  │ (Vite)   │  │  Stores   │  │ (offline) │  │
│  └────┬─────┘  └───────────┘  └───────────┘  │
│       │                                       │
│  ┌────┴──────────────────────────────────┐   │
│  │         Rust Backend (Tauri)           │   │
│  │  ┌─────────┐  ┌────────────────────┐  │   │
│  │  │ Commands│  │  Turso/libSQL DB   │  │   │
│  │  │ (invoke)│  │  ~/Library/...     │  │   │
│  │  └─────────┘  │  alpha.db          │  │   │
│  │               └────────────────────┘  │   │
│  └───────────────────────────────────────┘   │
│                                               │
│  ┌───────────────────────────────────────┐   │
│  │         Vite Dev Proxy                 │   │
│  │  /api → kappa.lambdaanalytics.co       │   │
│  └───────────────────────────────────────┘   │
└──────────────────────────────────────────────┘
```

### 2.1 Flujo de datos

1. **Auth**: Login → Bearer token → localStorage → Pinia store
2. **KAPPA sync**: fetch() vía proxy Vite → store Pinia → opcional cache Dexie
3. **Datos locales**: Tauri invoke → Rust commands → Turso/libSQL → retorna JSON al frontend
4. **Offline**: Dexie.js guarda cache del scheduler y datos de sesión

### 2.2 Base de datos local (Turso)

Archivo: `~/Library/Application Support/com.teloprax.alpha/alpha.db`

Tablas actuales:
- `projects` — caché de iniciativas KAPPA
- `work_items` — caché de historias de usuario y tareas

Tablas planeadas (módulo usuarios):
- `users` — cache KAPPA + campos locales (rol, seniority, célula)
- `cells` — células/equipos
- `cell_members` — relación usuario ↔ célula
- `project_members` — relación usuario ↔ proyecto
- `absences` — ausencias (vacaciones, permisos)
- `daily_logs` — registro diario por usuario
- `performance_snapshots` — métricas calculadas

## 3. Estructura del proyecto

```
kappa-hub/
├── src/                          # Frontend Vue 3
│   ├── components/
│   │   ├── ui/                   # shadcn-vue (30+ componentes)
│   │   ├── dashboard/            # Cards, tabla, sidebar, charts
│   │   ├── AppSidebar.vue        # Navegación principal
│   │   ├── NavProjects.vue       # Selector de proyectos
│   │   └── NavUser.vue           # Perfil de usuario
│   ├── views/
│   │   ├── LoginView.vue         # Auth
│   │   ├── NewDashboardView.vue  # Dashboard multi-sección
│   │   ├── ProjectListView.vue   # Lista de proyectos
│   │   ├── CalendarView.vue      # Calendario colombiano
│   │   └── SchedulerView.vue     # Recetas automáticas
│   ├── stores/                   # Pinia
│   │   ├── auth.ts               # Autenticación
│   │   ├── projects.ts           # Proyectos KAPPA
│   │   ├── workitems.ts          # Work items
│   │   └── scheduler.ts          # Reglas + logs
│   ├── services/
│   │   ├── kappa-api.ts          # Cliente HTTP KAPPA
│   │   ├── calendar.ts           # Feriados Colombia + días hábiles
│   │   └── scheduler.ts          # Motor de recetas
│   ├── types/kappa.ts            # Tipos TypeScript KAPPA
│   ├── i18n/                     # es.json, en.json
│   └── composables/              # useSearch, useTheme
├── src-tauri/                    # Backend Rust
│   ├── src/
│   │   ├── main.rs               # Entry point, comandos Tauri
│   │   └── db.rs                 # Operaciones Turso/libSQL
│   ├── tauri.conf.json           # Config Tauri
│   └── icons/                    # Iconos app (macOS, Windows, iOS, Android)
└── public/                       # Assets estáticos
    └── Alpha.svg                 # Logo vectorial
```

## 4. APIs KAPPA integradas

| Endpoint | Método | Uso |
|----------|--------|-----|
| `/users/login/` | POST | Auth |
| `/users/all/` | GET | Listar usuarios |
| `/initiatives-all/` | GET | Listar proyectos |
| `/userstorys/` | GET | HUs por proyecto |
| `/userstorys/create/` | POST | Crear HU |
| `/logbooks/` | GET | Bitácoras |
| `/logbooks_master/create/` | POST | Crear bitácora |
| `/logbooks/create/` | POST | Entrada bitácora |
| `/plannings/` | GET | Planeaciones |
| `/plannings_master/create/` | POST | Crear planeación |
| `/plannings/create/` | POST | Entrada planeación |
| `/business-rules/` | GET | Reglas de negocio |
| `/business-rules/create/` | POST | Crear regla |
| `/functionalrequirements/` | GET | Requisitos |
| `/functionalrequirements/create/` | POST | Crear requisito |
| `/employees/` | GET (paginado) | Usuarios ↔ proyectos |

## 5. Autenticación

- **Método**: Bearer token (JWT de Django REST)
- **Almacenamiento**: localStorage (`kappa_token`)
- **Flujo**: Login → POST `/users/login/` → token → header `Authorization: Bearer <token>`
- **Persistencia**: Recordar email en `alpha_remember_email`
- **Proxy dev**: Vite redirige `/api/*` → `https://kappa.lambdaanalytics.co`

## 6. Sincronización entre máquinas

- **Código**: iCloud Drive (`com~apple~CloudDocs/AI/Teloprax/`)
- **Datos KAPPA**: Servidor remoto (el Hub es solo cliente)
- **Token**: localStorage del navegador (logueo por máquina)
- **Turso DB**: Local por máquina (`~/Library/Application Support/`)

## 7. Decisiones técnicas

| Decisión | Razón |
|----------|-------|
| Tauri v2 en vez de Electron | Binario <10MB, RAM <50MB, Rust nativo |
| Turso/libSQL en vez de SQLite puro | Compatible SQLite, embedded, MCP server built-in |
| Dexie.js para offline | IndexedDB wrapper, API simple, ya integrado |
| shadcn-vue New York | Estilo moderno, copiable, Tailwind v4 nativo |
| Bun runtime | Más rápido que npm/yarn, compatible con Node |
| fetch() nativo | Sin dependencia axios, suficiente para REST |
| AG Grid (planeado) | Reemplaza @tanstack/vue-table para tablas complejas |

## 8. Roadmap técnico

| Fase | Alcance | Estado |
|------|---------|--------|
| Auth + Proyectos | Login, listado, dashboard individual | ✅ |
| Layout + Navegación | Sidebar, tabs, shadcn-vue | ✅ |
| Calendario | Feriados Colombia, Ley Emiliani | ✅ |
| Scheduler | Recetas automáticas, Dexie, notificaciones | ✅ |
| i18n | Español/Inglés | ✅ |
| Tauri | Migración web → desktop app | ✅ |
| Módulo Usuarios | AG Grid, Turso, roles, células | 🔜 F1 |
| Métricas PMI | SPI, CPI, Velocity, Burndown | 🔜 F4 |
| Daily | Registro diario + recálculo | 🔜 F5 |
| Calendarios externos | Google/Outlook OAuth2 | ⬜ K-21 |
| Alertas post-reunión | Detección fin reunión → captura | ⬜ K-22 |