Complete documentation for future sessions

- 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>

docs/01-arquitectura/overview.md

@@ -0,0 +1,140 @@
+# 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.