# 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
- **MySQL 8.0**: 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.