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>
2026-01-20 00:36:53 +01:00
commit db71705842
49 changed files with 19162 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,245 @@
+# 🤖 AiWorker - AI Agent Orchestration Platform
+
+Sistema de orquestación de agentes IA (Claude Code) para automatización del ciclo completo de desarrollo de software.
+
+**Estado**: 🚧 En desarrollo - Infraestructura completa ✅
+
+---
+
+## 🎯 ¿Qué es AiWorker?
+
+Plataforma que permite a agentes IA (Claude Code) trabajar autónomamente en tareas de desarrollo:
+
+1. **Dashboard Web** - Kanban board para gestionar tareas
+2. **Agentes Autónomos** - Claude Code en pods de Kubernetes
+3. **Comunicación MCP** - Agentes piden/dan información
+4. **Deployments Automáticos** - Preview, staging, production
+5. **GitOps** - Todo versionado en Git
+
+**Flujo completo**:
+```
+Tarea → Agente → Código → PR → Preview Deploy → Aprobación → Staging → Production
+```
+
+---
+
+## 📚 DOCUMENTACIÓN
+
+### 🚀 Start Here
+- **[ROADMAP.md](ROADMAP.md)** - Plan general y progreso
+- **[NEXT-SESSION.md](NEXT-SESSION.md)** - Próximos pasos detallados
+- **[DEVELOPMENT-WORKFLOW.md](DEVELOPMENT-WORKFLOW.md)** - Cómo trabajamos (Git, CI/CD, Deploy)
+- **[QUICK-REFERENCE.md](QUICK-REFERENCE.md)** - Comandos y URLs importantes
+- **[GITEA-GUIDE.md](GITEA-GUIDE.md)** - Guía completa de Gitea (API, Registry, CI/CD)
+
+### 🏗️ Infraestructura
+- **[CLUSTER-READY.md](CLUSTER-READY.md)** - Estado del cluster K8s
+- **[CLUSTER-CREDENTIALS.md](CLUSTER-CREDENTIALS.md)** - Credenciales (⚠️ sensible)
+- **[AGENT-GUIDE.md](AGENT-GUIDE.md)** - Guía para agentes IA
+- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Solución de problemas
+
+### 📖 Documentación Completa
+- **[docs/](docs/)** - 40+ archivos de documentación detallada
+  - `01-arquitectura/` - Diseño del sistema
+  - `02-backend/` - Backend (Bun + Express + MCP)
+  - `03-frontend/` - Frontend (React 19.2 + TailwindCSS)
+  - `04-kubernetes/` - Kubernetes setup
+  - `05-agents/` - Claude Code agents
+  - `06-deployment/` - CI/CD y GitOps
+  - `CONTAINER-REGISTRY.md` - Uso del registry
+
+---
+
+## ✅ COMPLETADO
+
+### Infraestructura Kubernetes HA
+- ✅ Cluster K3s v1.35.0+k3s1 (Houston, Texas)
+- ✅ 3 Control Planes + 3 Workers + 2 Load Balancers
+- ✅ Longhorn Storage HA (3 réplicas)
+- ✅ Nginx Ingress + Cert-Manager (TLS automático)
+- ✅ Red privada con HAProxy
+- ✅ DNS: *.fuq.tv (round-robin HA)
+
+### Servicios Base
+- ✅ MariaDB 11.4 LTS
+- ✅ Redis 7
+- ✅ Gitea 1.25.3 + Container Registry
+- ✅ ArgoCD
+- ✅ Gitea Actions Runner (CI/CD)
+
+### Backend Inicial
+- ✅ Estructura del proyecto
+- ✅ Bun 1.3.6 con Bun.serve()
+- ✅ Database schema (Drizzle ORM)
+- ✅ Dockerfile
+- ✅ Workflow CI/CD
+
+**Costo**: $148/mes | **Capacidad**: 48 vCPU, 104 GB RAM
+
+---
+
+## 🚧 EN DESARROLLO
+
+- [ ] Backend API routes completas
+- [ ] MCP Server para agentes
+- [ ] Frontend React 19.2
+- [ ] Pods de agentes Claude Code
+- [ ] Preview environments automáticos
+
+---
+
+## ⚡ QUICK START
+
+### Acceder al Cluster
+```bash
+export KUBECONFIG=~/.kube/aiworker-config
+kubectl get nodes
+kubectl get pods -A
+```
+
+### Desarrollo Local (Backend)
+```bash
+cd backend
+
+# Port-forward services
+kubectl port-forward -n control-plane svc/mariadb 3306:3306 &
+kubectl port-forward -n control-plane svc/redis 6379:6379 &
+
+# Run dev server
+bun run dev
+
+# Test
+curl http://localhost:3000/api/health
+```
+
+### Ver Actions CI/CD
+```bash
+open https://git.fuq.tv/admin/aiworker-backend/actions
+```
+
+### Deploy en K8s (cuando esté listo)
+```bash
+kubectl apply -f k8s/backend/
+kubectl get pods -n control-plane
+```
+
+---
+
+## 🏗️ ARQUITECTURA
+
+```
+                    Internet
+                       ↓
+                [DNS: *.fuq.tv]
+                       ↓
+          ┌────────────┴────────────┐
+          ↓                         ↓
+     [LB-01]                    [LB-02]
+     HAProxy                    HAProxy
+          ↓                         ↓
+          └────────────┬────────────┘
+                       ↓
+           [Private Network 10.100.0.0/24]
+                       ↓
+       ┌───────────────┼───────────────┐
+       ↓               ↓               ↓
+  [CP etcd]       [CP etcd]       [CP etcd]
+  10.100.0.2      10.100.0.3      10.100.0.4
+       ↓               ↓               ↓
+  ─────┴───────────────┴───────────────┴─────
+       ↓               ↓               ↓
+  [Worker+Storage] [Worker+Storage] [Worker+Storage]
+  10.100.0.5       10.100.0.6       10.100.0.7
+       ↓               ↓               ↓
+     [Apps]          [Apps]          [Apps]
+       │               │               │
+  [Longhorn 3x Replica Storage HA]
+```
+
+---
+
+## 📦 STACK TECNOLÓGICO
+
+| Layer | Tecnología | Versión |
+|-------|-----------|---------|
+| **Runtime** | Bun | 1.3.6 |
+| **Backend** | Bun.serve() + Drizzle | - |
+| **Frontend** | React + TailwindCSS | 19.2 + 4.x |
+| **Database** | MariaDB | 11.4 LTS |
+| **Cache** | Redis | 7 |
+| **Git** | Gitea | 1.25.3 |
+| **Registry** | Gitea Container Registry | - |
+| **K8s** | K3s | v1.35.0+k3s1 |
+| **Storage** | Longhorn | v1.8.0 |
+| **Ingress** | Nginx | latest |
+| **TLS** | Cert-Manager | v1.16.2 |
+| **GitOps** | ArgoCD | stable |
+| **CI/CD** | Gitea Actions | - |
+
+---
+
+## 🎓 LEARN BY DOING - Sesiones
+
+### Sesión 1 (2026-01-19) - Infraestructura ✅
+- Desplegar cluster K3s HA en CubePath
+- Configurar storage, networking, ingress
+- Instalar Gitea, MariaDB, Redis
+- Setup CI/CD con Gitea Actions
+- Inicializar backend
+
+**Ver**: `CLUSTER-READY.md` para detalles completos
+
+### Sesión 2 (Próxima) - Backend API
+- Completar API routes
+- Implementar MCP Server
+- Integración con Gitea y K8s
+- Deploy backend en cluster
+
+**Ver**: `NEXT-SESSION.md` para pasos exactos
+
+---
+
+## 📞 SOPORTE
+
+- **Issues**: Documentadas en `TROUBLESHOOTING.md`
+- **CubePath**: https://cubepath.com/support
+- **K3s Docs**: https://docs.k3s.io
+- **Bun Docs**: https://bun.sh/docs
+
+---
+
+## 🤝 CONTRIBUCIÓN
+
+Este es un proyecto en desarrollo activo. La documentación se actualiza en cada sesión.
+
+**Estructura de commits**:
+```
+Title line (imperativo)
+
+Detailed description
+
+Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
+```
+
+---
+
+## 📜 LICENSE
+
+Proyecto privado - AiWorker Platform
+
+---
+
+## 🎉 HIGHLIGHTS
+
+- **Alta Disponibilidad**: 3 réplicas de todo (storage, control planes)
+- **TLS Automático**: Let's Encrypt con Cert-Manager
+- **CI/CD Integrado**: Build automático en cada push
+- **GitOps Ready**: ArgoCD configurado
+- **Escalable**: 48 vCPU, 104 GB RAM disponibles
+- **Moderno**: Últimas versiones de todo (K3s, Bun, React 19.2)
+
+---
+
+**🚀 ¡Proyecto con bases sólidas! Listo para construir features increíbles!**
+
+**Siguiente paso**: Abre `NEXT-SESSION.md` y continúa donde lo dejaste.