aiworker/docs/01-arquitectura/stack-tecnologico.md

Stack Tecnológico

Frontend

Core

• React 19.2: Framework UI principal
• Vite: Build tool y dev server
• TypeScript: Type safety
• TailwindCSS 4.x: Styling utility-first

Librerías UI

• @dnd-kit/core: Drag and drop para kanban
• xterm.js: Emulador de terminal web
• lucide-react: Iconos modernos
• react-hot-toast: Notificaciones
• recharts: Gráficas y métricas

Estado y Data Fetching

• @tanstack/react-query: Server state management
• zustand: Client state management (ligero y simple)
• socket.io-client: WebSocket para real-time

Routing

• react-router-dom: Navegación SPA

Backend

Core

• Bun 1.3.6: Runtime JavaScript ultra-rápido
• Express: Framework HTTP
• TypeScript: Type safety

Database

• MariaDB 11.4 LTS: Base de datos relacional principal
• mysql2: Driver MySQL para Node.js
• Drizzle ORM: ORM TypeScript-first moderno
  • Type-safe
  • Ligero
  • Excelente DX con Bun

Cache y Colas

• Redis 7.x: Cache y message broker
• BullMQ: Sistema de colas robusto
• ioredis: Cliente Redis

Comunicación con Agentes

• @modelcontextprotocol/sdk: SDK oficial MCP
• socket.io: WebSocket server

Integraciones

• @kubernetes/client-node: Cliente oficial K8s
• octokit (adaptado): Cliente API Gitea
• axios: HTTP client

Desarrollo

• tsx: TypeScript execution
• nodemon: Hot reload
• prettier: Code formatting
• eslint: Linting

Infrastructure

Containerización

• Docker 24.x: Containerización
• Docker Compose: Orquestación local

Orchestration

• Kubernetes 1.28+: Orquestación de contenedores
  • kubectl: CLI
  • helm: Package manager
  • kustomize: Configuration management

Git Server

• Gitea latest: Servidor Git auto-alojado
  • Ligero (~100MB)
  • API REST compatible GitHub
  • Webhooks nativos

CI/CD y GitOps

• ArgoCD: GitOps continuous delivery
• GitHub Actions (o Gitea Actions): CI pipelines

Monitoring y Logging

• Prometheus: Métricas
• Grafana: Visualización
• Loki: Logs aggregation
• Jaeger: Distributed tracing (opcional)

Networking

• Nginx Ingress Controller: Routing
• cert-manager: TLS certificates

Agentes

Claude Code

• Claude Code CLI: Herramienta oficial de Anthropic
• Model: Claude Sonnet 4.5
• MCP Tools: Comunicación con backend

Development Tools

Package Management

• bun: Package manager principal
• npm: Fallback para compatibilidad

Testing

• Vitest: Unit testing (compatible con Bun)
• @testing-library/react: React testing
• Playwright: E2E testing

Code Quality

• TypeScript 5.x: Type checking
• ESLint: Linting
• Prettier: Formatting
• husky: Git hooks

Versiones Específicas

{
  "frontend": {
    "react": "19.2.0",
    "vite": "^6.0.0",
    "typescript": "^5.6.0",
    "tailwindcss": "^4.0.0"
  },
  "backend": {
    "bun": "1.3.6",
    "express": "^4.19.0",
    "mysql2": "^3.11.0",
    "drizzle-orm": "^0.36.0",
    "bullmq": "^5.23.0",
    "@modelcontextprotocol/sdk": "^1.0.0"
  },
  "infrastructure": {
    "kubernetes": "1.28+",
    "docker": "24.0+",
    "gitea": "1.22+",
    "redis": "7.2+",
    "mysql": "8.0+"
  }
}

Justificación de Tecnologías

¿Por qué Bun?

• Velocidad: 3-4x más rápido que Node.js
• TypeScript nativo: Sin configuración adicional
• APIs modernas: Compatibilidad Web Standard
• Tooling integrado: Bundler, test runner, package manager

¿Por qué MariaDB?

• Madurez: Batalla-probado en producción
• Rendimiento: Excelente para lecturas/escrituras
• Transacciones: ACID compliance
• Ecosistema: Herramientas maduras (backup, replicación)

¿Por qué Drizzle ORM?

• Type-safety: Inferencia total de tipos
• Performance: Query builder sin overhead
• DX: Migraciones automáticas
• Bun compatible: Primera clase

¿Por qué Gitea?

• Ligero: Binario único, bajo consumo
• Auto-alojado: Control total
• API familiar: Compatible con GitHub
• Simple: Instalación en minutos

¿Por qué React 19.2 sin Next.js?

• Simplicidad: SPA sin server-side complexity
• Control total: Sin abstracciones extra
• Rendimiento: Nuevo compilador React
• Features: Transitions, Server Actions cliente-side

Alternativas Consideradas

Necesidad	Elegido	Alternativas	Razón
Runtime	Bun	Node, Deno	Velocidad + DX
DB	MariaDB	PostgreSQL, MongoDB	Familiaridad + Madurez
ORM	Drizzle	Prisma, TypeORM	Type-safety + Performance
Git	Gitea	GitLab, Gogs	Simplicidad + Features
Frontend	React	Vue, Svelte	Ecosistema + React 19
Orchestration	K8s	Docker Swarm, Nomad	Industry standard

Dependencias Críticas

# Backend
bun add express mysql2 drizzle-orm ioredis bullmq
bun add @modelcontextprotocol/sdk socket.io
bun add @kubernetes/client-node axios

# Frontend
bun add react@19.2.0 react-dom@19.2.0
bun add @tanstack/react-query zustand
bun add socket.io-client xterm
bun add @dnd-kit/core react-router-dom

Roadmap Tecnológico

Fase 1 (MVP): Stack actual Fase 2: Añadir Prometheus + Grafana Fase 3: Implementar tracing con Jaeger Fase 4: Multi-tenancy y sharding de DB