aiworker/docs/01-arquitectura/overview.md

Overview General - AiWorker

Concepto

AiWorker es un sistema de orquestación de agentes IA que automatiza el ciclo completo de desarrollo de software mediante:

1. Dashboard Web: Interfaz central para gestionar proyectos y tareas
2. Consolas Web Persistentes: Terminales web conectadas a pods de Claude Code en K8s
3. Kanban Board Inteligente: Gestión visual de tareas con estados automáticos
4. Agentes Autónomos: Claude Code trabajando en tareas asignadas
5. Deployments Automatizados: Preview, staging y producción orquestados

Arquitectura de Alto Nivel

┌─────────────────────────────────────────────────────────────────┐
│                        Dashboard Web                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │   Kanban    │  │  Consolas   │  │   Project   │            │
│  │    Board    │  │     Web     │  │   Manager   │            │
│  └─────────────┘  └─────────────┘  └─────────────┘            │
└────────────────────────┬────────────────────────────────────────┘
                         │ HTTP/WebSocket
┌────────────────────────▼────────────────────────────────────────┐
│                     Backend (Bun + Express)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │   API    │  │   MCP    │  │  Gitea   │  │   K8s    │       │
│  │  Server  │  │  Server  │  │  Client  │  │  Client  │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
└────────┬───────────────┬─────────────┬─────────────┬───────────┘
         │               │             │             │
    ┌────▼────┐     ┌───▼────┐   ┌───▼────┐   ┌────▼─────┐
    │  MySQL  │     │ Redis  │   │ Gitea  │   │   K8s    │
    └─────────┘     └────────┘   └────────┘   └──────────┘
                                                    │
                    ┌───────────────────────────────┘
                    │
         ┌──────────▼──────────────────────────────────────┐
         │         Kubernetes Cluster                      │
         │  ┌──────────────┐  ┌─────────────────────────┐ │
         │  │    Agents    │  │  Project Namespaces     │ │
         │  │  Namespace   │  │  ├── dev                │ │
         │  │              │  │  ├── preview/<task-id>  │ │
         │  │ Claude Code  │  │  ├── staging            │ │
         │  │    Pods      │  │  └── production         │ │
         │  └──────────────┘  └─────────────────────────┘ │
         └─────────────────────────────────────────────────┘

Componentes Principales

1. Dashboard Web (Frontend)

• Tecnología: React 19.2 + TailwindCSS + Vite
• Funciones:
  • Kanban board para gestión de tareas
  • Consolas web interactivas (xterm.js)
  • Gestión de proyectos
  • Monitoring en tiempo real

2. Backend API

• Tecnología: Bun 1.3.6 + Express + TypeScript
• Funciones:
  • API REST para frontend
  • MCP Server para agentes
  • Orquestación de tareas
  • Integración con Gitea y K8s

3. Base de Datos

• MariaDB 11.4 LTS: Almacenamiento persistente
• Redis: Colas, cache, pub/sub

4. Gitea

• Servidor Git auto-alojado
• API compatible con GitHub
• Gestión de repos, branches, PRs

5. Kubernetes Cluster

• Orquestación de contenedores
• Namespaces por proyecto y entorno
• Auto-scaling de agentes

6. Claude Code Agents

• Pods persistentes en K8s
• Conectados vía MCP Server
• Workspace aislado por agente

Estados de Tareas

Backlog → En Progreso → Necesita Respuestas
                              ↓
                         Usuario responde
                              ↓
              ┌───────────────┘
              ↓
         Listo para Probar
              ↓
         (Preview deploy)
              ↓
         Aprobado
              ↓
         Staging (merge grupal)
              ↓
         Producción

Flujo de Trabajo Típico

1. Usuario crea proyecto → Sistema crea repo en Gitea + namespace en K8s
2. Usuario crea tareas → Se añaden al backlog del kanban
3. Agente disponible → Toma siguiente tarea vía MCP
4. Agente trabaja → Clone, branch, código, commits
5. ¿Necesita info? → Cambia estado a "Necesita Respuestas"
6. Completa tarea → Push + PR + deploy preview
7. Usuario prueba → En ambiente preview aislado
8. Aprueba → Marca para staging
9. Merge grupal → Agrega 2-3 tareas + merge a staging
10. Deploy staging → Tests automáticos
11. Deploy producción → Aprobación final

Ventajas del Sistema

✅ Automatización completa: Desde tarea hasta producción ✅ Aislamiento: Cada tarea en su propio preview environment ✅ Trazabilidad: Todo cambio vinculado a tarea y PR ✅ Escalabilidad: Agentes auto-escalables en K8s ✅ Flexibilidad: Agentes pueden pedir ayuda al usuario ✅ Control: Usuario aprueba cada fase importante

Seguridad

• Namespaces aislados en K8s
• RBAC por agente
• Secrets management
• Network policies
• Auditoría de acciones

Próximos Pasos

Ver documentación específica de cada componente en las secciones correspondientes.