Arquitectura del sistema

Principios, componentes y límites

La arquitectura se plantea como un backend modular donde PostgreSQL protege la integridad y Go orquesta los casos de uso del negocio.

Principios no negociables

Un comando = una transacción

La operación de negocio debe confirmar o fallar como unidad.

PostgreSQL valida invariantes

Constraints, FKs compuestas y triggers protegen el estado incluso ante errores de aplicación.

SQL-first

El backend trabaja con SQL explícito y repositorios tipados, no con un ORM como modelo dominante.

Ledgers inmutables

Pagos e inventario se compensan con nuevos movimientos, no con ediciones destructivas.

Componentes

Componente	Responsabilidad
API	Autenticación, autorización, contexto operativo, contratos HTTP y transacciones de negocio.
Worker	Procesamiento de outbox, proyecciones, sync saliente y tareas diferidas.
PostgreSQL	Fuente de verdad, integridad, snapshots y validaciones duras.
Control-plane	Posterior. Provisioning, DSN por cliente y gobierno global.

Topología lógica

Cliente / Terminal / API Consumer
            |
            v
          API (Go)
            |
            +---- PostgreSQL
            |      - truth
            |      - triggers
            |      - ledgers
            |      - idempotencia
            |      - outbox
            |
            +---- Worker (Go)
                   - projections
                   - sync events
                   - deferred jobs

Límites transaccionales

Apertura de sesión POS
Mutación de orden
Envío a producción
Registro de pago
Posteo de recepción
Registro y aplicación de pago AP

Invariantes críticas

Una terminal no puede tener más de una sesión POS abierta.
Los pagos se compensan con nuevos movimientos, no con updates destructivos.
Los movimientos de inventario se compensan, no se corrigen editando el ledger.
Una recepción debe ser consistente con su orden de compra, proveedor y almacén destino.
Una aplicación AP no puede exceder el saldo del documento ni el monto del pago.
Un comando con la misma llave de idempotencia no puede ejecutar dos veces el mismo efecto.

La parte asíncrona no decide el estado del negocio. Solo distribuye y proyecta efectos ya confirmados transaccionalmente.

Estructura sugerida del código

cmd/
  api/
  worker/
  control-plane/

internal/
  platform/
    auth/
    config/
    db/
    http/
    observability/
    tenant/
  modules/
    iam/
    catalog/
    pos/
    orders/
    payments/
    inventory/
    purchasing/
    ap/
    sync/
    reporting/
    hospitality/

db/
  migrations/
  queries/