db71705842
- 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>
141 lines
6.8 KiB
Markdown
141 lines
6.8 KiB
Markdown
# 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.
|