Configuration

1. Environment Variables

Source: packages/core/src/common/environments.ts (EnvironmentKeys) + this package's src/common/.

Core

Name	Type	Default	Required	Description
APP_ENV_PORT	number	3000		HTTP listen port (dev external 31040)
APP_ENV_HOST	string	0.0.0.0		Bind host
APP_ENV_BASE_PATH	string	/v1/api/finance		Route prefix
APP_ENV_NODE_ID	number	4	✓	Snowflake worker ID
APP_ENV_LOG_LEVEL	info|debug|warn|error	info		Logger level
NODE_ENV	string	production		Environment partition stamped onto accounts

Database

Name	Type	Default	Required	Description
APP_ENV_DB_URL	string	—	✓	PostgreSQL connection URL
APP_ENV_DB_POOL_MAX	number	10		Max pool size

Kafka

Name	Type	Default	Required	Description
APP_ENV_KAFKA_BROKERS	string	—	✓	Comma-separated brokers (empty → component throws on boot)
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00040-FINANCE_PRODUCER / _CONSUMER		Client id
APP_ENV_KAFKA_GROUP_ID	string	SVC-00040-FINANCE_CONSUMER_GROUP		Consumer group
APP_ENV_KAFKA_SASL_ENABLE	boolean	false		Enable SASL
APP_ENV_KAFKA_SASL_MECHANISM / _USERNAME / _PASSWORD	string	—		SASL credentials (when enabled)

WebSocket Redis

Name	Type	Default	Required	Description
APP_ENV_WEBSOCKET_REDIS_MODE	single|cluster	single		Emitter Redis topology
APP_ENV_WEBSOCKET_REDIS_HOST	string	localhost		—
APP_ENV_WEBSOCKET_REDIS_PORT	number	6379		—
APP_ENV_WEBSOCKET_REDIS_PASSWORD	string	—		—
APP_ENV_WEBSOCKET_REDIS_DB	number	0		—
APP_ENV_WEBSOCKET_REDIS_IDENTIFIER	string	finance-ws-redis		Connection name

Cache / Authorization Redis

Name	Type	Default	Required	Description
APP_ENV_REDIS_HOST	string	—	✓	Authorization cache host (useCacheRedis)
APP_ENV_REDIS_PORT	number	6379		—

2. Feature Flags

None. Finance has no runtime feature flags. Behavioral switches (single-currency, control-account presence) are structural, not flag-gated. Multi-currency is dormant: the exchangeRate column exists but is hard-set to 1.

3. Seeded Data

Migration processes in src/migrations/processes/ — loaded by migration-process.ts, idempotent.

File	Seeds	Always-run	Notes
finance-0001-seed-categories.ts	14 system FinanceCategory rows (merchantId=null)	no	Upserts by (name, type, identifier, merchantId=null)
finance-0002-seed-permissions.ts	All finance Permission rows	yes	Upsert by code
finance-0003-seed-role-permissions.ts	Grants ALL finance permissions to OWNER, EMPLOYEE, CASHIER	yes	Lenient baseline; tightened later via merchant policy API

14 system categories

Identifier	Type	Name (en)
000_SALE	INCOME	Sales Revenue
001_OTHER_INCOME	INCOME	Other Income
002_REFUND_INCOME	INCOME	Refund Received
300_COLLECT_INTEREST	INCOME	Interest Income
100_PURCHASE	EXPENSE	Purchase - Inventory
101_OTHER_EXPENSE	EXPENSE	Other Expenses
102_REFUND_EXPENSE	EXPENSE	Refund to Customer
200_OPERATING	EXPENSE	Operating Expenses
201_SALARY	EXPENSE	Salaries & Wages
202_RENT_UTILITIES	EXPENSE	Rent & Utilities
203_MARKETING	EXPENSE	Marketing & Advertising
204_SHIPPING	EXPENSE	Transportation & Delivery
205_MAINTENANCE	EXPENSE	Maintenance & Repairs
301_PAY_INTEREST	EXPENSE	Interest Expense

Constants in FixedFinanceCategories. Merchants add custom children under these via the category API. INVENTORY/COGS control accounts are not seeds — they are reconciled per-merchant on the first merchant CDC event.

4. Configuration Storage (Configuration table)

Per-merchant / system runtime configs read via ConfigurationRepository.

Configuration	Group	Read by	Purpose
DEFAULT_FINANCE_ACCOUNTS	SYSTEM (principal null)	FinanceWorkerService._loadDefaultAccountConfig	Template array of default accounts seeded for a new merchant when merchant.metadata.finance.accounts is absent; validated by DefaultFinanceAccountsConfigSchema
PaymentIntegration.credential	— (own table)	PaymentIntegrationService / FinanceIntegrationService	Encrypted gateway credentials; masked in API responses

5. Related Pages

• Operations
• API Events
• Decisions