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,uistub). No hayapps/adminni 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_idy 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.