System Architecture
Service Registry
Ports, service codes, Snowflake worker IDs and base paths are generated from source - this is the single source of truth (also on Platform Facts):
| Service | Port | Base path | Snowflake | Service code |
|---|---|---|---|---|
| identity | 31010 | /v1/api/identity | 1 | SVC-00010-IDENTITY |
| commerce | 31020 | /v1/api/commerce | 2 | SVC-00020-COMMERCE |
| sale | 31030 | /v1/api/sale | 3 | SVC-00030-SALE |
| finance | 31040 | /v1/api/finance | 4 | SVC-00040-FINANCE |
| inventory | 31050 | /v1/api/inventory | 5 | SVC-00050-INVENTORY |
| ledger | 31060 | /v1/api/ledger | 6 | SVC-00060-LEDGER |
| pricing | 31070 | /v1/api/pricing | 7 | SVC-00070-PRICING |
| payment | 31080 | /v1/api/payment | 8 | SVC-00080-PAYMENT |
| signal | 31090 | /v1/api/signal | 9 | SVC-00090-SIGNAL |
| outreach | 31110 | /v1/api/outreach | 10 | SVC-00110-OUTREACH |
| helpdesk | 31032 | /v1/api/helpdesk | 0 | SVC-00120-HELPDESK |
| taxation | 31130 | /v1/api/taxation | 13 | SVC-00130-TAXATION |
| licensing | 31120 | /v1/api/licensing | 11 | SVC-00140-LICENSING |
| invoice | 1190 | /v1/api | - | SVC-00150-INVOICE |
Auto-generated from packages/* env files + ServiceCodes + the schema tree at build time - never hand-typed.
Application base class - identity is the single trust root (issues JWKS); every other service verifies against it:
| Base class | Services |
|---|---|
IssuerApplication | identity |
VerifierApplication | commerce, sale, finance, inventory, ledger, pricing, payment, signal, outreach, helpdesk, taxation, licensing, invoice |
| infra (Traefik + Astro) | gateway |
Payment supports mode-based deployment:
full(default, all-in-one),api(REST only, Snowflake 8),worker(BullMQ only, Snowflake 91, 92, ...).
Network Topology
Application Hierarchy
BaseApplication (@venizia/ignis)
└── BaseApplication (@nx/core - CORS, Swagger, health check)
├── IssuerApplication (JWKS issuer - signs JWTs, serves /jw-certs)
│ └── identity
└── VerifierApplication (JWKS verifier - fetches remote /jw-certs)
└── commerce, sale, finance, inventory, pricing, payment,
signal, ledger, outreach, licensing, taxation,
helpdesk, invoiceAll services verify JWTs by fetching the identity service's /jw-certs JWKS endpoint. Only identity signs tokens.
Package Dependency Chain
Build order (from Makefile): third-parties first, then core, then all packages in dependency order. See Build System for the full target reference.
Database Schema Mapping
All schemas are defined in @nx/core and shared across services via the PostgresCoreDataSource. Each service connects to the same PostgreSQL database but operates on different schemas.
| Schema | Tables | Primary Service | Purpose |
|---|---|---|---|
helpdesk | 30 | helpdesk | Tickets, SLA, knowledge base, surveys, agents, notifications |
public | 26 | identity, commerce | Users, roles, permissions, merchants, organizers, products, categories, variants, devices, sale channels, configurations |
inventory | 17 | inventory | Stock, purchase orders, purchase items, stock movements, materials, BOM |
sale | 21 | sale | Sale orders, order items, checks, kitchen tickets, reservations, shifts |
invoice | 9 | invoice | E-invoices, numbering, signatures, provider records |
pricing | 9 | pricing | Fares, fare rules, costs, taxes, price evaluations |
identity | 8 | identity | User credentials, identifiers, profiles, mail verification |
ledger | 8 | ledger | Ledger jobs, generated documents, data sources |
finance | 6 | finance | Wallets, transactions, categories, vouchers |
tax | 6 | taxation | Tax groups, tax templates, product tax provisioning |
licensing | 5 | licensing | Policies, policy features, licenses, activations, license events |
allocation | 4 | commerce | Event seating, venue layouts |
outreach | 2 | outreach | Inquiries, subscribers |
payment | 0 | payment | PaymentIntegration lives in the finance schema |
Total: 151 tables across 14 schemas.
See Database Guide for migration workflow and ORM patterns.
Component Matrix
Which packages register which infrastructure components:
| Package | Kafka Producer | Kafka Consumer | WebSocket | Cache Redis | Mail / SMS |
|---|---|---|---|---|---|
| core | - | - | - | Yes | - |
| identity | - | - | Yes | - | Yes (SMS + Mail) |
| commerce | Yes | - | Yes | - | - |
| sale | Yes | - | Yes | - | - |
| finance | - | Yes | Yes | - | - |
| inventory | Yes | Yes | Yes | - | - |
| pricing | - | Yes | - | - | - |
| ledger | Yes | Yes | - | - | - |
| taxation | - | Yes | - | - | - |
| search | - | - (CDC) | - | - | - |
| payment | - | - | Yes | - | - |
| signal | - | - | Yes (E2E encrypted) | - | - |
| outreach | - | - | Yes | - | - |
| licensing | - | - | - | Yes | - |
See Event Architecture for the full topic and queue reference.
Frontend Applications
| App | Framework | Purpose | Port |
|---|---|---|---|
@nx-app/client | React 19 + Vite 7 + shadcn/ui | Admin dashboard | 3001 |
@nx-app/bo | React 19 + Vite 7 + shadcn/ui | Back office (merchant management) | 3000 |
@nx-app/sale-renderer | React 19 + Tauri 2 WebView | POS desktop UI | 3002 |
@nx-app/sale-main | Rust + Tauri 2 | POS desktop backend (SQLite, hardware plugins) | - |
@nx-app/overture | Astro | Marketing / landing page | 4321 |
@nx-app/admin-ui-kit | React + Radix UI | Shared component library (43 shadcn + custom) | - |
@nx-app/core | TypeScript | Shared constants, hooks, locales, utilities | - |
Third-Party Integrations
| Package | Purpose | Provider |
|---|---|---|
@nx/mq-pay | Multi-provider payment (QR, Phone POS, Smart POS) | VNPAY |
@nx/mq-sms | Multi-provider SMS gateway | VNPAY |
@nx/iiapi | Vietnam e-invoice service | VNPAY viiAPI |
@nx/t-van | Vietnam Tax Authority data transmission | T-VAN |
Related Pages
| Page | Description |
|---|---|
| Getting Started | Local setup walkthrough |
| Build System | Makefile targets, dependency graph |
| Event Architecture | Kafka topics, queues, WebSocket, CDC |
| Database Guide | Schema details, migrations, ORM patterns |
| IGNIS Patterns | Application hierarchy, DI, controller factory |
| Packages Overview | Per-package documentation index |