Makers3D/docs/Makers3D_Arquitectura_Infraestructura.md

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

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

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.