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

```json
{
  "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

```bash
# 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