Skip to content

🏛️ System Architecture

Our engine utilizes an event-driven, transactional outbox pattern designed for absolute consistency and financial auditing.

🗺️ Data Flow Blueprint

graph TD
    subgraph Client Layer
        Web[apps/web: React + Vite]
    end

    subgraph API Tier
        API[apps/api: Go Standard Library]
    end

    subgraph Persistence Layer
        DB[(PostgreSQL 16 Engine)]
        Outbox[(outbox_events Table)]
    end

    subgraph Processing Tier
        Worker[apps/worker: Python Async Engine]
        Artifacts[PDF Receipts & UBL-TR XML Invoices]
    end

    Web -->|HTTP /api/v1| API
    API -->|Write State & Event| Outbox
    API -->|Transaction Boundary| DB
    Worker -->|SELECT FOR UPDATE SKIP LOCKED| Outbox
    Worker -->|Generate| Artifacts

Key Architectural Tenets

  1. Transactional Outbox Pattern: All asynchronous side effects (e-invoicing, receipt PDFs, notifications) are written directly to outbox_events in the same database transaction as business state changes.
  2. Deterministic Financial Precision: Never use standard binary floating-point numbers (float, float64) for financial calculations. Always enforce shopspring/decimal in Go and Python's Decimal module.
  3. Optimistic Locking / SKIP LOCKED: The worker uses FOR UPDATE SKIP LOCKED to allow scalable parallel processing across workers without record locking contention.