Platform architecture

Public site, client portal and admin ERP on one Next app (DOC-017).

Source: docs/architecture/DOC-017-platform-architecture.md

DOC-017: Arquitectura objetivo de LogicCore Platform

Estado: Alineada con DOC-001 v2.0 Approved, ADR-034…040 Accepted el 2026-11-12. Registro de aprobación. Las decisiones de proveedor de producción y los diseños de dominio permanecen abiertos.

Topología

flowchart TD
  P["Public website"] --> API["NestJS REST API"]
  C["Client portal"] --> API
  A["Admin ERP"] --> API
  H["Help Center / Developer Docs"] --> API
  API --> DB[("PostgreSQL / Prisma")]
  API --> S["Object storage"]
  API --> O["Email / payments / tax adapters"]
  API --> T["Telemetry collector"]

Decisión de diseño inicial

  • Un monorepo pnpm/Turborepo con apps/web (público + portal + admin, route groups y authorization boundaries), apps/help (Help Center), apps/docs (Developer Docs), apps/api (NestJS modular monolith) y paquetes compartidos (types, api-contract, ui stub). No hay apps/admin ni app nativa (ADR-023, ADR-038).
  • Backend por contextos definidos en DOC-002, hexagonal/DDD pragmático (ADR-010/024), casos de uso y acceso Prisma tras repositorios.
  • PostgreSQL compartido para el ERP de LogicCore. Cada registro externo lleva organization_id y autorización explícita; no declarar una plataforma SaaS multi-tenant sin ADR separado.
  • Contratos REST/OpenAPI /api/v1 (ADR-032), correlación, paginación, idempotencia en submissions y dinero.
  • Autenticación OIDC Google + email por proveedor a seleccionar; autorización server-side con roles y alcance de recursos (ADR-034 Accepted).
  • Transacciones y eventos internos; outbox y jobs persistentes solo con diseño por caso. Evitar doble ejecución de facturas o pagos.
  • Observabilidad con OpenTelemetry, logs JSON estructurados, trazas y métricas, alertas y auditoría diferenciada (ADR-037 Accepted).
  • Billing: ERP genera receivables y registros; emisión fiscal y cobro externo tras ADR de país/proveedor (ADR-036 Accepted).
  • No exponer base de datos o sistemas internos en Developer Docs. API pública acotada mediante auth y controles de cuota cuando se apruebe.

Límites de confianza

Internet → web/portal → API → DB; sesiones protegidas y CSRF según mecanismo; validación inputs; RBAC y policy de objeto en cada use case; webhooks firmados y deduplicados; secreto de proveedor en vault/secret store; mínimo privilegio para workers; archivos con URLs temporales.

Entornos y operación

Dev local Docker Compose: Postgres + Mailpit; perfil dev con API, web, help y docs; overlay opt-in Loki/Prometheus/Grafana (ADR-040). Staging y producción separados, migraciones gestionadas, backups/restores probados y deploy con rollback. Hosting, colas, storage, SMTP de producción y CMS quedan abiertos con ADR/Spike.

Fases técnicas

Foundation: identity, RBAC, organizations, design system y telemetry. Luego intake + CRM; después Sales/Contracts/Delivery; finalmente Finance/Payments/Support. No modificar apps/api/prisma/schema.prisma hasta brief y contratos aprobados.