aiworker/ROADMAP.md

🗺️ 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

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

Docs: CLUSTER-READY.md, docs/04-kubernetes/

2. Bases de Datos y Servicios

• MariaDB 11.4 LTS con storage HA
• Redis 7 desplegado
• Gitea 1.25.3 con Container Registry habilitado
• ArgoCD para GitOps

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

3. Backend Inicial

• Estructura del proyecto creada
• Bun 1.3.6 configurado
• Database schema (projects, agents, tasks) con Drizzle
• Dockerfile multi-stage
• Gitea Actions Runner configurado
• 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:

# 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:

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

• CLUSTER-READY.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:

export KUBECONFIG=~/.kube/aiworker-config

---

⚡ COMANDOS ÚTILES

Cluster

# Ver nodos
kubectl get nodes -o wide

# Ver todos los pods
kubectl get pods -A

# Namespaces
kubectl get ns

Backend

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

Gitea

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

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

Logs

# 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

# 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.