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>
16 KiB
16 KiB
Flujo de Datos
Arquitectura de Comunicación
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Frontend │ ◄─────► │ Backend │ ◄─────► │ MySQL │
└──────────┘ └──────────┘ └──────────┘
│ │ │
│ ├──────────────────────┤
│ │ Redis │
│ └──────────────────────┘
│ │
│ ┌─────┴─────┐
│ │ │
│ ┌────▼────┐ ┌───▼────┐
│ │ Gitea │ │ K8s │
│ └─────────┘ └───┬────┘
│ │
│ ┌────▼────────┐
└────────────────────┤ Claude Code │
WebSocket │ Agents │
└─────────────┘
1. Flujo Completo: Creación de Tarea
1.1 Usuario Crea Tarea
Frontend Backend MySQL Redis
│ │ │ │
│ POST /api/tasks │ │ │
├──────────────────────►│ │ │
│ │ INSERT task │ │
│ ├──────────────────►│ │
│ │ │ │
│ │ PUBLISH task.new │ │
│ ├───────────────────┼────────────────►│
│ │ │ │
│ { taskId, status } │ │ │
│◄──────────────────────┤ │ │
│ │ │ │
│ WS: task_created │ │ │
│◄──────────────────────┤ │ │
Detalle:
-
Frontend envía POST a
/api/taskscon JSON:{ "projectId": "uuid", "title": "Implementar login", "description": "Crear sistema de autenticación..." } -
Backend:
- Valida datos
- Inserta en MySQL tabla
tasks - Publica evento en Redis:
task:new - Añade job a cola BullMQ:
task-queue - Responde con task creada
-
WebSocket notifica a todos los clientes conectados
1.2 Agente Toma Tarea
Agent (K8s) Backend (MCP) MySQL BullMQ
│ │ │ │
│ MCP: get_next_task │ │ │
├──────────────────────►│ │ │
│ │ SELECT task │ │
│ ├──────────────────►│ │
│ │ │ │
│ │ UPDATE status │ │
│ ├──────────────────►│ │
│ │ │ │
│ { task details } │ DEQUEUE job │ │
│◄──────────────────────┤◄─────────────────┼─────────────────┤
│ │ │ │
Detalle:
- Agente llama herramienta MCP
get_next_task - Backend:
- Query:
SELECT * FROM tasks WHERE state='backlog' ORDER BY created_at LIMIT 1 - Actualiza:
UPDATE tasks SET state='in_progress', assigned_agent_id=? - Elimina job de BullMQ
- Query:
- Responde con detalles completos de la tarea
2. Flujo: Agente Pide Información
Agent Backend (MCP) MySQL Frontend (WS)
│ │ │ │
│ ask_user_question │ │ │
├─────────────────────►│ │ │
│ │ UPDATE task │ │
│ ├──────────────────►│ │
│ │ state=needs_input │ │
│ │ │ │
│ │ INSERT question │ │
│ ├──────────────────►│ │
│ │ │ │
│ { success: true } │ WS: needs_input │ │
│◄─────────────────────┤──────────────────┼───────────────────►│
│ │ │ │
│ │ │ [Usuario ve] │
│ │ │ [notificación] │
│ │ │ │
│ │ POST /api/tasks/ │ │
│ │ :id/respond │ │
│ │◄──────────────────┼────────────────────┤
│ │ │ │
│ MCP: check_response │ UPDATE response │ │
├─────────────────────►├──────────────────►│ │
│ │ state=in_progress │ │
│ { response: "..." } │ │ │
│◄─────────────────────┤ │ │
Detalle:
- Agente detecta necesita info (ej: "¿Qué librería usar para auth?")
- Llama
ask_user_question(taskId, question) - Backend:
- Actualiza
tasks.state = 'needs_input' - Inserta en tabla
task_questions - Emite WebSocket
task:needs_input
- Actualiza
- Frontend muestra notificación y badge en kanban
- Usuario responde vía UI
- Backend guarda respuesta
- Agente hace polling o recibe notificación vía MCP
3. Flujo: Completar Tarea y Deploy Preview
Agent Backend(MCP) Gitea API MySQL K8s API Frontend
│ │ │ │ │ │
│ create_branch │ │ │ │ │
├─────────────────►│ │ │ │ │
│ │ POST /repos/│ │ │ │
│ │ :owner/:repo│ │ │ │
│ │ /branches │ │ │ │
│ ├────────────►│ │ │ │
│ { branch } │ │ │ │ │
│◄─────────────────┤ │ │ │ │
│ │ │ │ │ │
│ [agent works] │ │ │ │ │
│ [commits code] │ │ │ │ │
│ │ │ │ │ │
│ create_pr │ │ │ │ │
├─────────────────►│ │ │ │ │
│ │ POST /pulls │ │ │ │
│ ├────────────►│ │ │ │
│ { pr_url } │ │ │ │ │
│◄─────────────────┤ │ │ │ │
│ │ │ │ │ │
│ trigger_preview │ │ │ │ │
├─────────────────►│ │ │ │ │
│ │ UPDATE task │ │ │ │
│ ├────────────┼────────────►│ │ │
│ │ │ │ │ │
│ │ CREATE │ │ CREATE │ │
│ │ namespace │ │ Deployment │
│ ├────────────┼────────────┼──────────►│ │
│ │ │ │ │ │
│ { preview_url } │ │ WS:ready_to_test │ │
│◄─────────────────┤─────────────┼───────────┼───────────┼───────────►│
Detalle:
- create_branch: Backend usa Gitea API para crear rama
task-{id}-feature - Agente trabaja: Clone, cambios, commits, push
- create_pr: Crea PR con descripción generada
- trigger_preview:
- Backend crea namespace K8s:
preview-task-{id} - Aplica deployment con imagen del proyecto
- Configura ingress con URL:
task-{id}.preview.aiworker.dev - Actualiza
tasks.state = 'ready_to_test'
- Backend crea namespace K8s:
- Frontend muestra botón "Ver Preview" con URL
4. Flujo: Merge a Staging
User (Frontend) Backend Gitea API K8s API ArgoCD
│ │ │ │ │
│ POST /merge │ │ │ │
│ taskIds[] │ │ │ │
├──────────────►│ │ │ │
│ │ Validate │ │ │
│ │ all approved │ │ │
│ │ │ │ │
│ │ POST /pulls │ │ │
│ │ (merge PRs) │ │ │
│ ├──────────────►│ │ │
│ │ │ │ │
│ │ POST /branches│ │ │
│ │ staging │ │ │
│ ├──────────────►│ │ │
│ │ │ │ │
│ │ Trigger │ Apply │ │
│ │ ArgoCD sync │ manifests │ │
│ ├───────────────┼──────────────┼────────────►│
│ │ │ │ │
│ { status } │ │ │ [Deploys] │
│◄──────────────┤ │ │ │
Detalle:
- Usuario selecciona 2-3 tareas aprobadas
- Click "Merge a Staging"
- Backend:
- Valida todas están en estado
approved - Mergea cada PR a
stagingbranch - Actualiza estado a
staging - Triggerea ArgoCD sync
- Valida todas están en estado
- ArgoCD detecta cambios y deploya a namespace
staging
5. Comunicación Real-Time (WebSocket)
Eventos emitidos por Backend:
// Usuario se conecta
socket.on('connect', () => {
socket.emit('auth', { userId, token })
})
// Backend emite eventos
socket.emit('task:created', { taskId, projectId })
socket.emit('task:status_changed', { taskId, oldState, newState })
socket.emit('task:needs_input', { taskId, question })
socket.emit('task:ready_to_test', { taskId, previewUrl })
socket.emit('agent:status', { agentId, status, currentTaskId })
socket.emit('deploy:started', { environment, taskIds })
socket.emit('deploy:completed', { environment, url })
Cliente subscribe:
socket.on('task:status_changed', (data) => {
// Actualiza UI del kanban
queryClient.invalidateQueries(['tasks'])
})
socket.on('task:needs_input', (data) => {
// Muestra notificación
toast.info('Un agente necesita tu ayuda')
// Mueve card a columna "Needs Input"
})
6. Caching Strategy
Redis Cache Keys:
task:{id} → TTL 5min (task details)
task:list:{projectId} → TTL 2min (lista de tareas)
agent:{id}:status → TTL 30s (estado agente)
project:{id} → TTL 10min (config proyecto)
Invalidación:
// Al actualizar tarea
await redis.del(`task:${taskId}`)
await redis.del(`task:list:${projectId}`)
// Al cambiar estado agente
await redis.setex(`agent:${agentId}:status`, 30, status)
7. Queue System (BullMQ)
Colas:
task-queue → Tareas pendientes de asignar
deploy-queue → Deploys a ejecutar
merge-queue → Merges programados
cleanup-queue → Limpieza de preview envs antiguos
Workers:
// task-worker.ts
taskQueue.process(async (job) => {
const { taskId } = job.data
// Notifica agentes disponibles vía MCP
await notifyAgents({ taskId })
})
// deploy-worker.ts
deployQueue.process(async (job) => {
const { taskId, environment } = job.data
await k8sClient.createDeployment(...)
})
Resumen de Protocolos
| Comunicación | Protocolo | Uso |
|---|---|---|
| Frontend ↔ Backend | HTTP REST + WebSocket | CRUD + Real-time |
| Backend ↔ MySQL | TCP/MySQL Protocol | Persistencia |
| Backend ↔ Redis | RESP | Cache + PubSub |
| Backend ↔ Gitea | HTTP REST | Git operations |
| Backend ↔ K8s | HTTP + Kubernetes API | Orquestación |
| Backend ↔ Agents | MCP (stdio/HTTP) | Herramientas |
| Agents ↔ Gitea | Git Protocol (SSH) | Clone/Push |