# 🗺️ AiWorker - Roadmap y Próximos Pasos

**Última actualización**: 2026-01-19
**Estado actual**: Infraestructura completa, Backend iniciado

---

## ✅ COMPLETADO (Sesión 1 - 2026-01-19)

### 1. Infraestructura Kubernetes HA
- [x] Cluster K3s desplegado en CubePath (Houston)
- [x] 3 Control Planes + 3 Workers + 2 Load Balancers
- [x] Red privada 10.100.0.0/24
- [x] Longhorn storage HA (3 réplicas)
- [x] Nginx Ingress + Cert-Manager (TLS automático)
- [x] DNS configurado (*.fuq.tv)

**Docs**: `K8S-CLUSTER.md`, `docs/04-kubernetes/`

### 2. Bases de Datos y Servicios
- [x] MariaDB 11.4 LTS con storage HA
- [x] Redis 7 desplegado
- [x] Gitea 1.25.3 con Container Registry habilitado
- [x] ArgoCD para GitOps

**Credenciales**: `CLUSTER-CREDENTIALS.md`
**Acceso Gitea**: https://git.fuq.tv (admin/admin123)

### 3. Backend Inicial
- [x] Estructura del proyecto creada
- [x] Bun 1.3.6 configurado
- [x] Database schema (projects, agents, tasks) con Drizzle
- [x] Dockerfile multi-stage
- [x] Gitea Actions Runner configurado
- [x] Workflow CI/CD básico

**Repo**: https://git.fuq.tv/admin/aiworker-backend

---

## 🎯 PRÓXIMOS PASOS

### FASE 1: Completar Backend

#### 1.1 Verificar y corregir CI/CD
**Objetivo**: Build automático funcionando
**Tareas**:
- [ ] Verificar build en https://git.fuq.tv/admin/aiworker-backend/actions
- [ ] Corregir errores si los hay
- [ ] Confirmar imagen en registry: `git.fuq.tv/admin/aiworker-backend:latest`

**Comandos útiles**:
```bash
# Ver runner logs
kubectl logs -n gitea-actions deployment/gitea-runner -c runner --tail=50

# Ver packages en Gitea
https://git.fuq.tv/admin/-/packages
```

#### 1.2 Implementar API Routes con Bun.serve()
**Objetivo**: Endpoints REST funcionales
**Tareas**:
- [ ] Crear `/api/projects` (CRUD)
- [ ] Crear `/api/tasks` (CRUD)
- [ ] Crear `/api/agents` (list, status)
- [ ] Implementar validación con Zod
- [ ] Health check mejorado con DB/Redis status

**Referencia**: `docs/02-backend/api-endpoints.md`

**Estructura**:
```
src/api/
├── routes/
│   ├── projects.ts
│   ├── tasks.ts
│   └── agents.ts
└── middleware/
    ├── auth.ts
    └── validate.ts
```

#### 1.3 Implementar MCP Server
**Objetivo**: Herramientas para agentes Claude Code
**Tareas**:
- [ ] Instalar `@modelcontextprotocol/sdk`
- [ ] Crear MCP server en puerto 3100
- [ ] Implementar tools: `get_next_task`, `update_task_status`, etc.
- [ ] Conectar con Gitea API
- [ ] Conectar con Kubernetes API

**Referencia**: `docs/02-backend/mcp-server.md`, `docs/05-agents/mcp-tools.md`

**Archivo**: `src/services/mcp/server.ts`

#### 1.4 Integración con Gitea
**Objetivo**: Gestión de repos y PRs
**Tareas**:
- [ ] Cliente API de Gitea
- [ ] Webhooks handler
- [ ] Operaciones: create repo, create PR, merge, etc.

**Referencia**: `docs/02-backend/gitea-integration.md`

**Token Gitea**: `159a5de2a16d15f33e388b55b1276e431dbca3f3` (full access)

#### 1.5 Integración con Kubernetes
**Objetivo**: Crear/gestionar deployments y namespaces
**Tareas**:
- [ ] Cliente K8s usando `@kubernetes/client-node`
- [ ] Crear namespaces dinámicos
- [ ] Crear deployments de preview
- [ ] Crear ingress automáticos
- [ ] Gestionar pods de agentes

**Referencia**: `docs/04-kubernetes/deployments.md`

**Kubeconfig**: `~/.kube/aiworker-config`

#### 1.6 Sistema de Colas (BullMQ)
**Objetivo**: Jobs asíncronos para deployments
**Tareas**:
- [ ] Setup BullMQ con Redis
- [ ] Queue para tasks
- [ ] Queue para deployments
- [ ] Workers para procesar jobs

**Referencia**: `docs/02-backend/queue-system.md`

#### 1.7 WebSocket Real-time
**Objetivo**: Notificaciones en tiempo real
**Tareas**:
- [ ] WebSocket server con Bun.serve()
- [ ] Eventos: `task:created`, `task:status_changed`, etc.
- [ ] Autenticación de conexiones

**Referencia**: `docs/01-arquitectura/flujo-de-datos.md`

#### 1.8 Deploy Backend en K8s
**Objetivo**: Backend corriendo en producción
**Tareas**:
- [ ] Crear manifests K8s (deployment, service, ingress)
- [ ] Configurar secrets (DB, Gitea, etc.)
- [ ] Deploy en namespace `control-plane`
- [ ] Verificar en `api.fuq.tv`

**Comandos**:
```bash
kubectl apply -f k8s/backend/
kubectl get pods -n control-plane
```

---

### FASE 2: Frontend React 19.2

#### 2.1 Inicializar Proyecto
**Objetivo**: Setup base de React
**Tareas**:
- [ ] Crear proyecto con Vite + React 19.2
- [ ] Instalar TailwindCSS 4
- [ ] Configurar TypeScript
- [ ] Estructura de carpetas

**Stack**:
- React 19.2.0
- Vite 6.x
- TailwindCSS 4.x
- Bun como package manager

**Auth**: Lucia Auth (`https://github.com/lucia-auth/lucia`)
**Skills**: Vercel Agent Skills (`https://github.com/vercel-labs/agent-skills`)

#### 2.2 Componentes Base
**Objetivo**: UI components library
**Tareas**:
- [ ] Layout (Header, Sidebar)
- [ ] Componentes UI (Button, Card, Modal, etc.)
- [ ] TailwindCSS config con tema

**Referencia**: `docs/03-frontend/componentes.md`

#### 2.3 Kanban Board
**Objetivo**: Gestión visual de tareas
**Tareas**:
- [ ] Implementar con `@dnd-kit`
- [ ] Columnas por estado (backlog, in_progress, etc.)
- [ ] Drag & drop funcional
- [ ] Filtros y búsqueda

**Referencia**: `docs/03-frontend/kanban.md`

#### 2.4 Consolas Web
**Objetivo**: Terminales para agentes
**Tareas**:
- [ ] Implementar con `xterm.js`
- [ ] WebSocket a pods de agentes
- [ ] Tabs manager

**Referencia**: `docs/03-frontend/consolas-web.md`

#### 2.5 Deploy Frontend
**Objetivo**: Frontend en producción
**Tareas**:
- [ ] Build para producción
- [ ] Dockerfile con nginx
- [ ] Deploy en `app.fuq.tv`

---

### FASE 3: Agentes Claude Code

#### 3.1 Docker Image del Agente
**Objetivo**: Imagen base para agentes
**Tareas**:
- [ ] Dockerfile con Claude Code CLI
- [ ] Git config
- [ ] SSH keys setup
- [ ] Script de trabajo (agent-loop.sh)

**Referencia**: `docs/05-agents/claude-code-pods.md`

#### 3.2 Gestión de Agentes desde Backend
**Objetivo**: Crear/eliminar pods de agentes
**Tareas**:
- [ ] API endpoint `/agents` (create, delete, list)
- [ ] Auto-scaling basado en tareas pendientes
- [ ] Healthcheck de agentes

**Referencia**: `docs/05-agents/ciclo-vida.md`

#### 3.3 Comunicación MCP
**Objetivo**: Agentes conectados al backend
**Tareas**:
- [ ] MCP client en agentes
- [ ] Herramientas implementadas (get_next_task, etc.)
- [ ] Heartbeat system

**Referencia**: `docs/05-agents/comunicacion.md`

---

### FASE 4: GitOps y Deployments

#### 4.1 ArgoCD Setup
**Objetivo**: GitOps funcional
**Tareas**:
- [ ] Conectar repos de Gitea a ArgoCD
- [ ] Crear Applications
- [ ] Auto-sync configurado

**Referencia**: `docs/06-deployment/gitops.md`
**URL**: https://argocd.fuq.tv (admin/LyPF4Hy0wvp52IoU)

#### 4.2 Preview Environments
**Objetivo**: Deploy automático por tarea
**Tareas**:
- [ ] Lógica para crear namespace temporal
- [ ] Deploy app en `task-{id}.r.fuq.tv`
- [ ] Cleanup automático (TTL)

**Referencia**: `docs/06-deployment/preview-envs.md`

#### 4.3 Staging y Production
**Objetivo**: Pipeline completo
**Tareas**:
- [ ] Merge a staging branch
- [ ] Deploy staging automático
- [ ] Aprobación manual para production
- [ ] Rollback capability

**Referencia**: `docs/06-deployment/staging-production.md`

---

## 📚 DOCUMENTACIÓN EXISTENTE

### Arquitectura
- `docs/01-arquitectura/overview.md` - Visión general
- `docs/01-arquitectura/stack-tecnologico.md` - Stack completo
- `docs/01-arquitectura/flujo-de-datos.md` - Diagramas de flujo
- `docs/01-arquitectura/modelo-datos.md` - Database schema

### Backend
- `docs/02-backend/estructura.md` - Estructura del proyecto
- `docs/02-backend/database-schema.md` - Drizzle schema
- `docs/02-backend/mcp-server.md` - MCP implementation
- `docs/02-backend/gitea-integration.md` - Gitea API client
- `docs/02-backend/queue-system.md` - BullMQ
- `docs/02-backend/api-endpoints.md` - REST API specs

### Frontend
- `docs/03-frontend/estructura.md` - Estructura
- `docs/03-frontend/componentes.md` - Componentes principales
- `docs/03-frontend/estado.md` - React Query + Zustand
- `docs/03-frontend/kanban.md` - Kanban board
- `docs/03-frontend/consolas-web.md` - xterm.js

### Kubernetes
- `docs/04-kubernetes/cluster-setup.md` - Setup inicial
- `docs/04-kubernetes/namespaces.md` - Estructura
- `docs/04-kubernetes/deployments.md` - Manifests
- `docs/04-kubernetes/gitea-deployment.md` - Gitea en K8s
- `docs/04-kubernetes/networking.md` - Ingress y red

### Agentes
- `docs/05-agents/claude-code-pods.md` - Pods de agentes
- `docs/05-agents/mcp-tools.md` - Herramientas MCP
- `docs/05-agents/comunicacion.md` - MCP protocol
- `docs/05-agents/ciclo-vida.md` - Lifecycle

### Deployment
- `docs/06-deployment/ci-cd.md` - Pipelines
- `docs/06-deployment/gitops.md` - ArgoCD
- `docs/06-deployment/preview-envs.md` - Previews
- `docs/06-deployment/staging-production.md` - Promoción

### Cluster
- `K8S-CLUSTER.md` - Estado del cluster
- `CLUSTER-CREDENTIALS.md` - Credenciales (⚠️ sensible)
- `AGENT-GUIDE.md` - Guía para agentes IA
- `docs/CONTAINER-REGISTRY.md` - Uso del registry
- `k8s-cluster-info.md` - Info técnica

---

## 🔑 CREDENCIALES RÁPIDAS

**Gitea**:
- URL: https://git.fuq.tv
- User: admin / admin123
- Token: `159a5de2a16d15f33e388b55b1276e431dbca3f3`

**Registry**:
- URL: git.fuq.tv
- Token: `7401126cfb56ab2aebba17755bdc968c20768c27`

**ArgoCD**:
- URL: https://argocd.fuq.tv
- User: admin / LyPF4Hy0wvp52IoU

**Longhorn**:
- URL: https://longhorn.fuq.tv
- User: admin / aiworker2026

**MariaDB** (interno):
- Host: mariadb.control-plane.svc.cluster.local:3306
- DB: aiworker
- User: aiworker / AiWorker2026_UserPass!

**Kubeconfig**:
```bash
export KUBECONFIG=~/.kube/aiworker-config
```

---

## ⚡ COMANDOS ÚTILES

### Cluster
```bash
# Ver nodos
kubectl get nodes -o wide

# Ver todos los pods
kubectl get pods -A

# Namespaces
kubectl get ns
```

### Backend
```bash
cd backend
bun run dev           # Desarrollo local
bun run db:generate   # Generar migraciones
```

### Gitea
```bash
# Ver Actions
https://git.fuq.tv/admin/aiworker-backend/actions

# Ver packages/imágenes
https://git.fuq.tv/admin/-/packages
```

### Logs
```bash
# MariaDB
kubectl logs -n control-plane mariadb-0

# Redis
kubectl logs -n control-plane deployment/redis

# Gitea
kubectl logs -n gitea gitea-0

# Runner
kubectl logs -n gitea-actions deployment/gitea-runner -c runner
```

---

## 🎯 PRÓXIMA SESIÓN - Plan Sugerido

### Opción A: Completar Backend (Recomendado)
1. Verificar CI/CD funcional
2. Implementar API routes básicas
3. Implementar MCP Server básico
4. Deploy backend en K8s
5. Probar end-to-end

**Tiempo estimado**: 2-3 horas

### Opción B: Frontend Paralelo
1. Inicializar React 19.2 + Vite
2. Setup TailwindCSS
3. Componentes básicos UI
4. Kanban board inicial

**Tiempo estimado**: 2-3 horas

### Opción C: Agentes Primero
1. Crear imagen Docker de agente
2. Deploy agente de prueba
3. Conectar con MCP
4. Primera tarea automática

**Tiempo estimado**: 3-4 horas

---

## 📊 PROGRESO GENERAL

```
Infraestructura:     ████████████████████ 100%
Backend:             ████░░░░░░░░░░░░░░░░  20%
Frontend:            ░░░░░░░░░░░░░░░░░░░░   0%
Agentes:             ░░░░░░░░░░░░░░░░░░░░   0%
GitOps/Deploy:       ██░░░░░░░░░░░░░░░░░░  10%
──────────────────────────────────────────
Total:               ██████░░░░░░░░░░░░░░  26%
```

---

## 🚀 QUICK START para Próxima Sesión

```bash
# 1. Verificar cluster
export KUBECONFIG=~/.kube/aiworker-config
kubectl get nodes

# 2. Verificar servicios
kubectl get pods -n control-plane
kubectl get pods -n gitea
kubectl get pods -n gitea-actions

# 3. Acceder a Gitea
open https://git.fuq.tv

# 4. Continuar con backend
cd backend
bun run dev

# 5. Ver Actions
open https://git.fuq.tv/admin/aiworker-backend/actions
```

---

## 🎓 APRENDIZAJES DE ESTA SESIÓN

### Lo que funcionó bien ✅
- CubeCLI para gestionar VPS
- K3s con instalación manual (control total)
- Longhorn para storage HA
- Gitea como plataforma todo-en-uno
- Bun.serve() nativo (más simple que Express)

### Challenges superados 💪
- Configurar red privada en K3s
- TLS automático con Cert-Manager
- Container Registry en Gitea
- Gitea Actions Runner con DinD
- Auto-migrations en la app

### Tips para futuras sesiones 💡
- Port-forward solo para testing, nunca para migrations
- Migrations deben ser automáticas en la app
- Usar TCP probes en vez de exec para MariaDB
- DinD necesita privileged + volumen compartido
- Gitea Actions compatible con GitHub Actions

---

## 📞 REFERENCIAS EXTERNAS

### Tecnologías
- **Bun**: https://bun.sh/docs
- **K3s**: https://docs.k3s.io
- **Drizzle ORM**: https://orm.drizzle.team/docs
- **Longhorn**: https://longhorn.io/docs/
- **Gitea**: https://docs.gitea.com
- **Cert-Manager**: https://cert-manager.io/docs/
- **Lucia Auth**: https://github.com/lucia-auth/lucia
- **Vercel Agent Skills**: https://github.com/vercel-labs/agent-skills

### APIs
- **MCP Protocol**: `@modelcontextprotocol/sdk`
- **Kubernetes**: `@kubernetes/client-node`
- **Gitea API**: https://git.fuq.tv/api/swagger

---

## 🎯 OBJETIVO FINAL

Sistema completo de orquestación de agentes IA que automatiza:
1. Usuario crea tarea en Dashboard
2. Agente Claude Code toma tarea vía MCP
3. Agente trabaja: código, commits, PR
4. Deploy automático en preview environment
5. Usuario aprueba → Staging → Production

**Todo automático, todo con HA, todo monitoreado.**

---

**💪 ¡Hemos construido bases sólidas! El siguiente paso más lógico es completar el Backend para tener la API funcional.**