admin/aiworker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete documentation for future sessions

Browse Source 
- CLAUDE.md for AI agents to understand the codebase
- GITEA-GUIDE.md centralizes all Gitea operations (API, Registry, Auth)
- DEVELOPMENT-WORKFLOW.md explains complete dev process
- ROADMAP.md, NEXT-SESSION.md for planning
- QUICK-REFERENCE.md, TROUBLESHOOTING.md for daily use
- 40+ detailed docs in /docs folder
- Backend as submodule from Gitea

Everything documented for autonomous operation.

Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hector Ros
2026-01-20 00:36:53 +01:00
commit db71705842
49 changed files with 19162 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

531
ROADMAP.md Normal file
View File

@@ -0,0 +1,531 @@
# 🗺️ 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**: `CLUSTER-READY.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
- `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**:
```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.**