STACK.md
Stack Tecnológico Oficial
1. Principio
Ningún agente puede cambiar tecnología, librería principal, framework o patrón de arquitectura sin aprobación del Orchestrator y registro de ADR.
2. Backend
| Componente |
Tecnología |
Versión / Nota |
| Lenguaje |
Python |
3.11+ |
| Framework |
Django |
5.x |
| API |
Django REST Framework (DRF) |
Última estable |
| Multi-tenant |
django-tenants |
Shared DB, Separate Schemas |
| Autenticación |
JWT |
djangorestframework-simplejwt |
| Tareas async |
Celery |
Para importación masiva y sync offline |
| Cache / broker |
Redis |
Requerido para Celery y blacklist JWT |
3. Base de datos
| Componente |
Tecnología |
| Motor principal |
PostgreSQL (obligatorio — requerido por django-tenants) |
| Estrategia multi-tenant |
Separate Schemas via django-tenants |
| Migraciones |
migrate_schemas --shared (public) + migrate_schemas (tenants) |
| Índices especiales |
GIN sobre Producto.especificaciones (JSONB) |
| Backups |
pg_dump global diario 02:00 AM — GFS: 7 diarios + 4 semanales + 3 mensuales. Dev: bind mount a C:\ops\venuo\backups\. Prod: /opt/venuo/backups/ + copia offsite via rclone (proveedor configurable en .env). Ver ADR-001 |
| Offsite backup |
rclone — compatible con Cloudflare R2, Backblaze B2, Amazon S3. Proveedor a definir al momento del deploy de producción |
4. Frontend
| Componente |
Tecnología |
| Framework |
React |
| Build tool |
Vite |
| Lenguaje |
TypeScript |
| Estilos |
Tailwind CSS |
| Tipo de app |
SPA / PWA |
| Offline storage |
IndexedDB + localStorage (catálogo POS + cola de ventas) |
| Server state |
TanStack Query |
| Estado cliente |
Zustand |
| Formularios |
React Hook Form |
| Validaciones |
Zod |
| Íconos |
Lucide React |
5. DevOps
Entornos
| Entorno |
Plataforma |
Propósito |
| Desarrollo |
Windows + Docker Desktop |
Desarrollo local — hot reload, datos de prueba, puertos expuestos |
| Producción |
VPS Linux + Docker Engine |
Clientes reales — SSL, Gunicorn, restart policies, backups activos |
Stack
| Componente |
Tecnología |
| Contenedores |
Docker + Docker Compose |
| Config desarrollo |
docker-compose.yml (hot reload, puertos expuestos, sin SSL) |
| Config producción |
docker-compose.prod.yml (Gunicorn, restart policies, SSL) — preparado en Sprint 0, desplegado al momento del release |
| Puertos desarrollo |
Django 8000, PostgreSQL 5432, Redis 6379, Nginx 80, Vite 5173 — todos expuestos al host |
| Puertos producción |
Nginx 80 y 443 únicamente — resto interno en red Docker |
| Versiones de imágenes |
PostgreSQL 16, Redis 7-alpine, Python 3.11-slim, Nginx 1.25-alpine, Node 20-alpine (solo build). Estrategia: versión mayor fija — parches automáticos, saltos de versión mayor manuales. Nunca usar latest |
| Settings Django |
Módulo dividido por entorno: config/settings/base.py + development.py + production.py. Variable DJANGO_SETTINGS_MODULE=config.settings.development (dev) / config.settings.production (prod) |
| Media files |
Volumen Docker local. Dev: ./media/ → /app/media. Prod: /opt/venuo/media/ → /app/media. Estructura: media/imports/tenant_X/. Eliminación automática: la tarea Celery elimina el archivo al finalizar + sweep periódico via Celery Beat cada 24h para archivos huérfanos. Migración a S3/R2 via django-storages sin cambio de arquitectura cuando escale |
| Proxy / Static |
Nginx (frontend compilado estáticamente en contenedor optimizado) |
| SSL |
Let's Encrypt / Certbot — solo en producción VPS |
| CI/CD |
GitHub Actions — CI en cada PR (tests + lint + build), CD al mergear a main (build imagen + deploy via SSH). Imágenes en GHCR. CD desactivado hasta VPS definido. Ver ADR-002 |
| Logs MVP |
Logging estructurado JSON a stdout + archivo con rotación 7 días. Sentry para captura de errores con contexto de tenant/usuario. Ver ADR-003 |
| Logs producción |
Loki + Grafana (self-hosted) — activar cuando haya más de 3 tenants activos. Sin cambios de código — solo infraestructura |
| Variables de entorno |
.env estricto — nunca secretos en repo. .env.example como referencia completa |
6. Testing
| Capa |
Herramienta |
| Backend unit |
Pytest + Django TestCase |
| API tests |
Pytest + DRF APIClient |
| Multi-tenant tests |
Tests con schema switching explícito |
| Frontend |
Vitest + Testing Library |
| E2E |
Playwright |
| Lint backend |
Ruff |
| Lint frontend |
ESLint |
| Format backend |
Black |
| Format frontend |
Prettier |
7. Comandos base
# Backend — migraciones multi-tenant
python manage.py migrate_schemas --shared # tablas del esquema public
python manage.py migrate_schemas # tablas de todos los tenants
# Backend — desarrollo
python manage.py runserver
pytest
# Frontend
npm install
npm run dev
npm run build
npm run test
# Docker
docker compose up -d --build
docker compose -f docker-compose.prod.yml up -d --build
docker compose logs -f
8. Librerías prohibidas sin ADR
- Librerías que gestionen multi-tenancy de forma distinta a
django-tenants.
- Librerías de autenticación que reemplacen
simplejwt sin migración planificada.
- ORMs alternativos a Django ORM.
- Librerías de estado en frontend que dupliquen TanStack Query o Zustand.
- Cualquier librería abandonada o sin mantenimiento activo.