Configuration

Overview

The Core package provides centralized configuration management through environment variables, constants, event channel definitions, and queue definitions. All services inherit these configurations for consistent behavior across the entire BANA platform.

Quick Links

Section	Description
Constants	Static constants, enumerations, and schema definitions
Environment Variables	Complete environment variable reference
Events	Event definitions and payload types for cross-service communication
Cross-Package Messaging (Kafka / CDC)	Kafka domain-event + Debezium CDC topic contracts

Directory Structure

packages/core/src/common/
├── index.ts              # All exports
├── environments.ts       # Environment key definitions (re-exported via keys.ts)
├── constants.ts          # Static constants
├── decorators.ts         # Custom decorators
├── validations.ts        # Validation utilities
├── events/               # Event definitions
│   ├── index.ts
│   ├── commerce-events.ts
│   ├── ledger-events.ts
│   ├── payment-events.ts
│   └── websocket-events.ts
├── kafka/                # Kafka topic + message contracts
│   ├── index.ts
│   ├── topics.ts         # KafkaTopics + CDCKafkaTopics
│   └── types.ts
└── cdc/                  # Debezium CDC table constants
    ├── index.ts
    └── tables.ts

Environment Variables

The EnvironmentKeys class extends Ignis Framework's base keys with application-specific configuration:

import { EnvironmentKeys as BaseEnvironmentKeys } from '@venizia/ignis';

export class EnvironmentKeys extends BaseEnvironmentKeys {
  // Application
  static readonly APP_ENV_NODE_ENV = 'APP_ENV_NODE_ENV';
  static readonly APP_ENV_APPLICATION_EXPLORER_URL = 'APP_ENV_APPLICATION_EXPLORER_URL';

  // Database
  static readonly APP_ENV_POSTGRES_HOST = 'APP_ENV_POSTGRES_HOST';
  static readonly APP_ENV_POSTGRES_PORT = 'APP_ENV_POSTGRES_PORT';
  // ... more keys
}

Categories

Category	Examples	Description
Application	APP_ENV_NODE_ENV, APP_ENV_APPLICATION_NAME	Core app settings
Database	APP_ENV_POSTGRES_HOST, APP_ENV_POSTGRES_PORT	PostgreSQL connection
Redis/BullMQ	APP_ENV_BULLMQ_REDIS_HOST	Job queue connection
Storage	APP_ENV_MINIO_HOST, APP_ENV_MINIO_ACCESS_KEY	MinIO/S3 storage
Mail	APP_ENV_MAIL_HOST, APP_ENV_MAIL_USER	SMTP configuration
ID Generation	APP_ENV_SNOWFLAKE_WORKER_ID	Snowflake ID config
Services	APP_ENV_IDENTITY_SERVICE_BASE_URL	Inter-service URLs

View all Environment Variables -->

Constants

Static configuration values used across the application:

PostgreSQL Schemas

export class PostgresSchemas {
  static readonly PUBLIC = 'public';
  static readonly PRICING = 'pricing';
  static readonly ALLOCATION = 'allocation';
  static readonly SALE = 'sale';
  static readonly INVENTORY = 'inventory';
  static readonly FINANCE = 'finance';
  static readonly PAYMENT = 'payment';
}

Fixed User Roles

export class FixedUserRoles {
  static readonly SUPER_ADMIN = '999-super-admin';
  static readonly ADMIN = '998-admin';
  static readonly OPERATOR = '997-operator';
  static readonly ORGANIZER_OWNER = '899-organizer-owner';
  static readonly EMPLOYEE = '898-employee';

  static readonly ALWAYS_ALLOW_ROLES = new Set([
    FixedUserRoles.SUPER_ADMIN,
    FixedUserRoles.ADMIN,
  ]);
}

View all Constants -->

Events

Typed event definitions for cross-service communication, published/subscribed via the event bus (IEventBus, Redis Pub/Sub adapter). Defined in src/common/events/: commerce-events.ts, ledger-events.ts, payment-events.ts, websocket-events.ts.

The exact event-class list below is a partial snapshot — see Events and the source files for the current set.

WebSocket Utilities

Class	Description
WebSocketRooms	Build standardized room identifiers (wr:{prefix}/{paths})
WebSocketTopics	Build standardized topic identifiers (ws:{paths})

View all Events -->

Cross-Package Messaging (Kafka / CDC)

The cross-package seam is Kafka (domain events) and Debezium CDC, not a BullMQ queue subsystem. Topic constants live in src/common/kafka/topics.ts.

Class	Purpose
KafkaTopics	Domain-event topic names + build({ paths }) prefixer (nx.seller)
CDCKafkaTopics	Debezium CDC topic names built from CdcTables

View Cross-Package Messaging -->

Usage

Access Environment Variables

import { applicationEnvironment } from '@venizia/ignis';
import { EnvironmentKeys } from '@nx/core';

// Get required variable
const dbHost = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);

// Get with default
const port = applicationEnvironment.get<number>(EnvironmentKeys.APP_ENV_POSTGRES_PORT) ?? 5432;

Use Constants

import { FixedUserRoles, DeviceTypes, PostgresSchemas } from '@nx/core';

// Role checking
if (userRoles.includes(FixedUserRoles.SUPER_ADMIN)) {
  // Super admin logic
}

// Device type validation
if (DeviceTypes.isValid(device.type)) {
  // Valid device type
}

// Schema reference
const schema = PostgresSchemas.PRICING;

Configuration Flow

Best Practices

1. Use Type-Safe Keys

// Good -- type-safe
const host = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);

// Bad -- error-prone
const host = process.env.APP_ENV_POSTGRES_HOST;

2. Validate Required Configuration

// At application startup
function validateConfig() {
  const required = [
    EnvironmentKeys.APP_ENV_POSTGRES_HOST,
    EnvironmentKeys.APP_ENV_POSTGRES_DATABASE,
    EnvironmentKeys.APP_ENV_SNOWFLAKE_WORKER_ID,
  ];

  for (const key of required) {
    if (!applicationEnvironment.get(key)) {
      throw new Error(`Missing required environment variable: ${key}`);
    }
  }
}

3. Use Constants for Magic Values

// Good -- use constant
if (user.role === FixedUserRoles.SUPER_ADMIN) { }

// Bad -- magic string
if (user.role === '999-super-admin') { }

Related Documentation

• DefaultApplication
• Core Utilities
• Database Overview