System Architecture
Service Registry
| Service | Code | Port | Snowflake | Base Path | Base Class |
|---|---|---|---|---|---|
| identity | SVC-00010 | 31010 | 1 | /v1/api/identity | IssuerApplication |
| commerce | SVC-00020 | 31020 | 2 | /v1/api/commerce | VerifierApplication |
| sale | SVC-00030 | 31030 | 3 | /v1/api/sale | VerifierApplication |
| finance | SVC-00040 | 31040 | 4 | /v1/api/finance | VerifierApplication |
| inventory | SVC-00050 | 31050 | 5 | /v1/api/inventory | VerifierApplication |
| ledger | SVC-00060 | 31060 | 6 | /v1/api/ledger | VerifierApplication |
| pricing | SVC-00070 | 31070 | 7 | /v1/api/pricing | VerifierApplication |
| payment | SVC-00080 | 31080 | 8 / 91,92 | /v1/api/payment | VerifierApplication |
| signal | SVC-00090 | 31090 | 9 | /v1/api/signal | VerifierApplication |
| outreach | SVC-00100 | 31110 | 10 | /v1/api/outreach | VerifierApplication |
| licensing | SVC-00110 | 31120 | 11 | /v1/api/licensing | VerifierApplication |
| taxation | SVC-00130 | 31130 | 13 | /v1/api/taxation | VerifierApplication |
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, taxationAll 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 |
|---|---|---|---|
public | 15 | identity, commerce | Users, roles, permissions, merchants, organizers, products, categories, variants, devices, sale channels, configurations |
pricing | 11 | pricing | Fares, fare rules, costs, taxes, price evaluations |
allocation | 4 | commerce | Event seating, venue layouts |
sale | 9 | sale | Sale orders, order items, checks, kitchen tickets |
inventory | 12 | inventory | Stock, purchase orders, purchase items, stock movements |
finance | 3 | finance | Wallets, transactions, categories |
payment | 1 | payment | Webhook configurations |
ledger | 2 | ledger | Ledger jobs, generated documents |
identity | 8 | identity | User credentials, identifiers, profiles, mail verification |
licensing | 5 | licensing | Policies, policy features, licenses, activations, license events |
outreach | 2 | outreach | Inquiries, subscribers |
Total: 72 tables across 11 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 (28 screen modules) | 5173 |
@nx-app/bo | React 19 + Vite 7 + shadcn/ui | Back office (merchant management) | 5174 |
@nx-app/sale-renderer | React 19 + Tauri 2 WebView | POS desktop UI | — |
@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 (38 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 |