Core Package
@nx/core is the foundation library of the BANA monorepo. It is not a microservice — it ships no runtime of its own. Every other backend package imports and extends it, so core must be built first.
This is a light-touch identity card. Core legitimately deviates from the standard 8-file service template — its mature structure (
architecture,components/*,configuration/*,database/*,utilities/*) is documented in the linked sub-pages below.
Identity Card
| Property | Value |
|---|---|
| Package | @nx/core |
| Type | Shared library / framework extension (no standalone runtime) |
| Snowflake worker ID | 0 (reserved for core) |
| Framework | IGNIS (@venizia/ignis, @venizia/ignis-helpers) |
| Runtime | Bun |
| ORM | Drizzle ORM + node-postgres (PostgreSQL) |
| Build | bun run rebuild (clean + tsc + tsc-alias) — never raw tsc |
| Source | packages/core/src/ |
What Core Provides
| Capability | What it is | Lives in |
|---|---|---|
| Base application classes | BaseApplication (shared middleware), IssuerApplication (JWKS issuer, ES256 — Identity), VerifierApplication (JWKS verifier — all other services), DefaultApplication (legacy symmetric JWT) | src/application/ |
| Bootstrap helpers | bootstrapApplication(), bootstrapMigration(), createAppConfig(), createMigrationProcessLoader() | src/helpers/bootstraps/, src/common/app-config.ts |
| Centralized Drizzle schemas | The single home for every schema in the monorepo — <domain>/<entity>/{schema.ts, model.ts, constants.ts, index.ts} across 14 domains | src/models/schemas/<domain>/<entity>/ |
| Shared column defs | generateCommonColumnDefs() (id, timestamps, soft-delete, metadata jsonb), isoTimestamp(), i18n column helpers | src/models/schemas/common/ |
| Repositories | One per entity, grouped by domain; extend SoftDeletableRepository or ArchivedRepository | src/repositories/<domain>/ |
| Repository base classes | SoftDeletableRepository (re-exported from @venizia/ignis), ArchivedRepository (status-based archive lifecycle) | src/base/repository/ |
| Service base classes | BaseSocketEventService (WebSocket emit via Signal), MerchantScopedService (merchant-scoped CRUD) | src/base/service/ |
| Snowflake IdGenerator | Singleton wrapping IGNIS SnowflakeUidHelper | src/utilities/id-generator.utility.ts |
| Kafka / CDC topic contracts | KafkaTopics (domain event names + build() prefixer), CDCKafkaTopics (Debezium), CdcTables | src/common/kafka/, src/common/cdc/ |
| Event bus | IEventBus interface + Redis Pub/Sub adapter; typed event definitions | src/helpers/event-bus/, src/common/events/ |
| Redis | RedisConnectionFactory (single / cluster) | src/helpers/redis/ |
| Shared utilities | CryptoUtility, dayjs (timezone-configured), useRequestContext(), merchant-access + postgres + transform + slug helpers | src/utilities/ |
| Constants & types | Statuses (IGNIS, reused — no custom enums), PostgresSchemas, FixedUserRoles, validations, shared decorators | src/common/ |
Cross-Package Seam
Kafka/CDC is the dominant cross-package communication seam — not a BullMQ queue subsystem.
| Mechanism | Purpose |
|---|---|
KafkaTopics | Domain event topic names (e.g. PAYMENT_SUCCESS, INVENTORY_ISSUED_FOR_SALE, LEDGER_GENERATE), with build({ paths }) prefixing nx.seller |
CDCKafkaTopics | Debezium CDC topics built from CdcTables (e.g. MERCHANT, PRODUCT, SALE_ORDER) |
Event bus (IEventBus) | In-process pub/sub abstraction with a Redis Pub/Sub adapter |
| Redis | Shared connection management for caching and pub/sub |
Who Depends On Core
Every backend package depends on @nx/core and connects to the same database via the re-exported PostgresCoreDataSource.
| Package | Application base | Role |
|---|---|---|
@nx/identity | IssuerApplication | JWT issuer (JWKS, ES256); auth, RBAC, users |
@nx/commerce | VerifierApplication | Products, pricing, merchants, organizers |
@nx/sale | VerifierApplication | Sale orders, checkout |
@nx/finance | VerifierApplication | Income/expense, wallets |
@nx/payment | VerifierApplication | Payment orchestration, webhooks |
@nx/inventory | VerifierApplication | Stock management, purchase orders |
@nx/signal | VerifierApplication | Centralized WebSocket service |
| Other services (invoice, ledger, licensing, outreach, tax, helpdesk, search, asset) | VerifierApplication | Consume core schemas, repos, and contracts |
Documentation Map
| Page | What you'll find |
|---|---|
| Architecture | Application hierarchy, lifecycle, runtime patterns |
| Components | |
| Components Overview | Index of base classes and shared infrastructure |
| DefaultApplication | Base app class, middleware, lifecycle methods |
| SoftDeletableRepository | Soft-delete + restore pattern (re-exported from IGNIS) |
| BaseSocketEventService | WebSocket event broadcasting |
| Network Services | IdentityNetworkService cross-service HTTP |
| Bootstrap Helpers | bootstrapApplication / bootstrapMigration |
| RedisConnectionFactory | Redis single/cluster connections |
| Event Bus | IEventBus + Redis Pub/Sub adapter |
| Configuration | |
| Configuration Overview | Environment, constants, events, topics |
| Environment Variables | EnvironmentKeys reference |
| Constants | PostgresSchemas, FixedUserRoles, etc. |
| Events | Event definitions + WebSocket topic builders |
| Queues / Kafka | Cross-package messaging contracts |
| Database | |
| Database Overview | Schema layout, generateCommonColumnDefs, DataSource |
| Public Schema | Users, products, merchants, organizers |
| Pricing Schema | Fares, costs, taxes |
| Allocation Schema | Event seating |
| Sale Schema | Sale orders + items |
| Inventory Schema | Stock, purchase orders, vendors |
| Finance Schema | Wallets, categories, transactions |
| Payment Schema | Webhook configurations |
| Outreach Schema | Outreach domain |
| ERD | Entity-relationship diagram |
| Migrations | Per-domain migrator CLI, Drizzle Kit, seeds |
| Utilities | |
| Utilities Overview | Index of shared utilities |
| IdGenerator | Snowflake ID singleton |
| CryptoUtility | Encryption + HMAC signing |
| DateUtility | Timezone-configured dayjs |
| RequestContext | Auth context + response formatting |
Schema Domains
Schemas live under src/models/schemas/<domain>/<entity>/; repositories mirror them under src/repositories/<domain>/. There are 14 domains — service packages consume these schemas, they do not define their own.
public · pricing · allocation · sale · inventory · finance · payment · invoice · ledger · identity · licensing · outreach · tax · helpdesk
The
database/sub-pages currently document a 7-schema snapshot. See the Database Overview for the documented schemas; the full 14-domain layout is the source of truth (packages/core/AGENTS.md).
Build & Scripts
| Script | Purpose |
|---|---|
bun run rebuild | Clean + build (always use this) |
bun run lint:fix | ESLint + Prettier auto-fix |
bun run test | Run tests (requires .env.test) |
bun run db:generate / db:migrate | Generate / apply migrations for one domain |
bun run db:generate:all / db:migrate:all | All domains |
IGNIS References
- IGNIS docs · Application · Repositories · DataSources · DI