Modulo makers3d desarrollado con codex V 0.0.1

docs/Makers3D_Arquitectura_Infraestructura.md

@@ -0,0 +1,405 @@
+# Makers3D - Arquitectura e Infraestructura
+
+## 1. Principios tecnicos
+
+1. Un solo sistema, no un conjunto de promesas futuras.
+2. PostgreSQL como fuente canonica unica.
+3. Monolito modular antes que microservicios.
+4. Infraestructura suficiente para beta, no para una escala imaginaria.
+5. Todo servicio debe justificar claramente su existencia.
+
+## 2. Arquitectura elegida
+
+### Vision general
+
+```text
+Usuario web
+   |
+ Nginx
+   |
+ Next.js (web)
+   |
+ NestJS API
+   |
+ PostgreSQL + PostGIS
+   |
+ MinIO
+   |
+ Worker
+```
+
+### Decisiones clave
+
+- una sola aplicacion web para publico, cuenta, area maker y admin;
+- una sola API de negocio;
+- una sola base de datos;
+- un solo worker para tareas asincronas y tareas programadas simples;
+- un solo proxy perimetral;
+- un solo sistema de almacenamiento de objetos.
+
+## 3. Stack aprobado
+
+### Web
+
+- Next.js App Router;
+- renderizado SSR para vistas publicas principales;
+- llamadas a API REST propia;
+- responsive web;
+- sin app nativa en MVP;
+- sin PWA avanzada en MVP.
+
+### API
+
+- NestJS;
+- Fastify;
+- versionado `/api/v1`;
+- validacion de entrada;
+- contratos JSON claros;
+- auth por cookie segura.
+
+### Datos
+
+- PostgreSQL 16;
+- PostGIS;
+- `pg_trgm`;
+- `unaccent`.
+
+### Archivos
+
+- MinIO;
+- buckets publicos y privados separados;
+- URLs firmadas para privados;
+- imagenes publicas optimizadas.
+
+### Asincronia
+
+- worker unico;
+- cola con PostgreSQL;
+- reintentos controlados;
+- tareas idempotentes.
+
+### Mapa
+
+- MapLibre en frontend;
+- teselas o PMTiles servidas por Nginx;
+- fallback completo a lista si el mapa falla.
+
+### Pagos
+
+- Mercado Pago para la suscripcion maker;
+- webhooks verificados;
+- conciliacion basica;
+- pago aprobado no publica automaticamente.
+
+## 4. Servicios y por que existen
+
+| Servicio | Existe porque |
+|---|---|
+| `web` | Entrega toda la experiencia visible del producto. |
+| `api` | Centraliza reglas de negocio, auth, publicacion, pagos y moderacion. |
+| `worker` | Evita bloquear la API con email, imagenes y webhooks. |
+| `postgres` | Conserva datos transaccionales, geograficos y de auditoria. |
+| `minio` | Permite archivos desacoplados del contenedor y faciles de respaldar. |
+| `nginx` | Publica web, API, activos y TLS en una sola capa simple. |
+
+No se crean por ahora:
+
+- `scheduler` separado;
+- `redis`;
+- `grafana`;
+- `prometheus`;
+- `loki`;
+- `tempo`;
+- `rabbitmq`;
+- `kafka`;
+- `elasticsearch`;
+- `opensearch`;
+- `kubernetes`.
+
+## 5. Estructura del proyecto
+
+```text
+makers3d/
+├── apps/
+│   ├── web/
+│   ├── api/
+│   └── worker/
+├── packages/
+│   ├── contracts/
+│   ├── database/
+│   ├── shared/
+│   └── ui/
+├── infrastructure/
+│   ├── docker/
+│   ├── nginx/
+│   ├── scripts/
+│   └── backups/
+└── docs/
+```
+
+Esta estructura es suficiente para trabajar con un equipo pequeno y agentes de IA sin crear paquetes vacios.
+
+## 6. Base de datos
+
+### Entidades principales
+
+- accounts
+- sessions
+- maker_profiles
+- maker_locations
+- maker_services
+- maker_works
+- inquiries
+- conversations
+- messages
+- subscriptions
+- payments
+- relationships
+- reviews
+- moderation_cases
+- audit_events
+
+### Reglas de modelado
+
+- UUID internos;
+- slugs publicos solo donde aporten valor;
+- `timestamptz` para fechas;
+- dinero en enteros por moneda;
+- integridad por claves y restricciones antes que por logica suelta;
+- historial solo donde cambie el comportamiento del negocio.
+
+### PostGIS
+
+Se usa para:
+
+- guardar coordenada privada del maker;
+- derivar punto publico aproximado;
+- calcular distancia real;
+- filtrar por radio;
+- soportar cobertura local.
+
+No se usa para:
+
+- analitica compleja;
+- tracking continuo;
+- multiples geometrias innecesarias en MVP.
+
+## 7. Busqueda
+
+La busqueda inicial se resuelve en PostgreSQL con:
+
+- texto libre;
+- trigramas;
+- campos normalizados;
+- filtros estructurados;
+- radio geografico;
+- distincion entre recogida local y envio.
+
+No se incorpora motor externo hasta que exista evidencia de que PostgreSQL no alcanza.
+
+## 8. Archivos y multimedia
+
+### Tipos permitidos en MVP
+
+- JPG;
+- PNG;
+- WebP;
+- PDF.
+
+### Tipos excluidos en MVP
+
+- STL publico;
+- ZIP;
+- RAR;
+- 3MF;
+- videos largos.
+
+### Flujo
+
+1. La API autoriza una subida.
+2. El archivo se guarda en MinIO.
+3. El worker valida y genera derivados cuando aplique.
+4. El sistema actualiza el estado.
+5. Solo entonces el recurso puede usarse publicamente.
+
+Esto simplifica mucho seguridad y moderacion.
+
+## 9. Autenticacion y autorizacion
+
+### Autenticacion
+
+- email y contrasena;
+- hash Argon2id;
+- verificacion de email;
+- recuperacion por token de un solo uso;
+- sesiones opacas con cookie HttpOnly.
+
+### Autorizacion
+
+Roles fijos del MVP:
+
+- guest;
+- user;
+- maker;
+- admin.
+
+No se implementa un motor de permisos granulares en la primera version. El admin concentra soporte, moderacion y gestion comercial en beta.
+
+## 10. Mensajeria
+
+### Decision
+
+La mensajeria usa polling controlado.
+
+### Motivo
+
+- reduce complejidad operativa;
+- no exige infraestructura de tiempo real;
+- es suficiente para una beta cerrada.
+
+### Frecuencia sugerida
+
+- refresco manual siempre disponible;
+- polling cada 20 a 30 segundos en conversacion abierta;
+- pausa cuando la pestana queda inactiva.
+
+WebSockets quedan fuera del MVP. SSE puede evaluarse mas adelante.
+
+## 11. Infraestructura de despliegue
+
+### Entornos
+
+- local;
+- staging;
+- produccion beta.
+
+No hace falta un cuarto entorno al principio.
+
+### Orquestacion
+
+- Docker Compose en todos los entornos;
+- imagenes versionadas;
+- variables y secretos por entorno;
+- volumentes persistentes claros;
+- despliegue manual asistido al inicio.
+
+### Proxy y TLS
+
+- Nginx como entrada unica;
+- HTTPS obligatorio;
+- certificados automaticos;
+- sin puertos internos expuestos al exterior.
+
+## 12. Backups y restore
+
+### Base de datos
+
+- backup completo nocturno;
+- archivado frecuente de WAL o estrategia equivalente;
+- prueba de restauracion antes de abrir beta.
+
+### Objetos
+
+- copia diaria de buckets;
+- verificacion por hash cuando sea posible.
+
+### Regla de salida
+
+No se abre beta con usuarios reales sin una restauracion comprobada.
+
+## 13. Seguridad
+
+### Obligatoria en MVP
+
+- HTTPS;
+- cookies seguras;
+- CSRF en formularios autenticados;
+- rate limiting;
+- proteccion basica contra brute force;
+- validacion estricta de entrada;
+- sanitizacion de archivos permitidos;
+- ocultacion de coordenadas privadas;
+- URLs firmadas para privados;
+- auditoria de acciones admin.
+
+### Diferida
+
+- MFA para todos los usuarios;
+- SIEM;
+- trazas distribuidas;
+- WAF externo;
+- secretos centralizados avanzados.
+
+## 14. Logs y observabilidad
+
+### Minimo obligatorio
+
+- logs JSON en web, API y worker;
+- request ID;
+- endpoint de health;
+- registro de errores de pagos, uploads y webhooks;
+- panel simple o lectura directa de logs en staging y produccion beta.
+
+### No obligatorio al inicio
+
+- paneles complejos;
+- trazas distribuidas exhaustivas;
+- metricas de alta cardinalidad.
+
+## 15. CI CD
+
+### Pipeline minimo
+
+- install reproducible;
+- lint;
+- typecheck;
+- tests unitarios;
+- tests de integracion esenciales;
+- build de web, api y worker;
+- construccion de imagenes.
+
+### Despliegue minimo
+
+- merge a rama principal;
+- build de imagenes versionadas;
+- despliegue manual a staging;
+- smoke test;
+- aprobacion;
+- despliegue a produccion beta.
+
+Esto es mas realista que automatizar completamente el release desde el primer dia.
+
+## 16. Hardening operativo
+
+Antes de abrir beta:
+
+- backups verificados;
+- conciliacion de pagos probada;
+- moderacion operable;
+- logs utiles;
+- restores probados;
+- rutas privadas revisadas;
+- direccion exacta protegida;
+- contenido minimo de soporte.
+
+## 17. Lo que no se debe construir todavia
+
+- cache distribuida si no hay cuello de botella;
+- cola externa si PostgreSQL aun responde;
+- varios proxies;
+- varios paneles de observabilidad;
+- app movil;
+- publicidad;
+- algoritmos complejos de ranking;
+- permisos internos granulares;
+- ingestion de cualquier tipo de archivo.
+
+## 18. Criterio final
+
+La arquitectura correcta para Makers3D no es la mas sofisticada. Es la que permite:
+
+- lanzar rapido;
+- cobrar sin sustos;
+- moderar sin caos;
+- recuperar datos;
+- y evolucionar sin rehacer el nucleo.