Configuration

1. Environment Variables

Core keys inherited from @nx/core EnvironmentKeys; ledger-specific keys in src/common/environments.ts.

Core (selected)

Name	Type	Default	Required	Description
APP_ENV_PORT	number	3000		HTTP listen port (external 31060)
APP_ENV_BASE_PATH	string	/v1/api/ledger		Route prefix
APP_ENV_NODE_ID	number	—	✓	Snowflake worker ID (6)
APP_ENV_DB_URL	string	—	✓	PostgreSQL connection
APP_ENV_S3_BUCKET	string	ledger		Target S3 bucket
RUN_MODE	string	—		migrate short-circuits component/service/controller registration

Kafka

Name	Type	Default	Required	Description
APP_ENV_KAFKA_BROKERS	string	—	✓	Comma-separated brokers
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00060-LEDGER		Producer/consumer client id
APP_ENV_KAFKA_GROUP_ID	string	SVC-00060-LEDGER_GROUP		Consumer group
APP_ENV_KAFKA_CONSUMER_COUNT	number	1*		Worker consumer instances
APP_ENV_KAFKA_SASL_ENABLE	boolean	true		Toggle SASL
APP_ENV_KAFKA_SASL_MECHANISM	string	SCRAM-SHA-512		SASL mechanism
APP_ENV_KAFKA_SASL_USERNAME / _PASSWORD	string	—		SASL credentials

* int() of an unset value — set explicitly for >1.

WebSocket (worker role)

Name	Type	Default	Description
APP_ENV_WEBSOCKET_REDIS_MODE	single|cluster	single	Emitter Redis topology
APP_ENV_WEBSOCKET_REDIS_HOST / _PORT / _PASSWORD / _DB	—	localhost/6379/—/0	Single-mode connection
APP_ENV_WEBSOCKET_REDIS_CLUSTER_NODES	string	—	Cluster-mode nodes (required if cluster)
APP_ENV_WEBSOCKET_REDIS_IDENTIFIER / _MAX_RETRY	—	ledger-ws-redis/5	—

Service-specific

Name	Type	Default	Description
APP_ENV_APPLICATION_ROLES	string	api,worker	CSV of api/worker; invalid/empty falls back to both
APP_ENV_LEDGER_ENCRYPTION_KEY	string	—	AES-256-GCM key (required for encrypt/decrypt)
APP_ENV_SWEEP_INTERVAL_MS	number	300000	Recovery sweep interval
APP_ENV_STALL_THRESHOLD_MS	number	180000	Job-stall cutoff
APP_ENV_JOB_TIMEOUT_MS	number	120000	Per-job generate timeout (Promise.race)
APP_ENV_WORKER_IDLE_TIMEOUT_MS	number	—	Worker idle timeout
APP_ENV_FORCE_GENERATE	boolean	false	Bypass in-flight skip + use latest job (testing)
APP_ENV_ALLOW_CURRENT_PERIOD	boolean	false	Include the current month/quarter in batch expansion
APP_ENV_EXTERNAL_DATA_BASE_URL	string	—	External data source base URL

2. Feature Flags

Flag	Default	Effect
APP_ENV_FORCE_GENERATE	false	Regenerate even when no PENDING job exists (testing)
APP_ENV_ALLOW_CURRENT_PERIOD	false	Batch generation includes the in-progress period

3. Seeded Data

src/migrations/processes/migration-process.ts runs these in order. alwaysRun: true = idempotent permission seeds; false = one-time.

File	Seeds	Always run	Notes
ledger-0001-seed-permissions	LedgerSystemPermissions rows	✓	Upsert by code
ledger-0002-seed-tax-declaration-levels	TaxDeclarationLevel — TIRE_1, TIRE_2, TIRE_3	—	Tax bands + filing-schedule rules
ledger-0003-seed-merchant-ledger-configs	One MerchantLedgerConfig per merchant (current year, requiredLedgerTypes=[S1a-HKD], origin: migration)	—	Skips if config exists; skips entirely if TIRE_1 level absent
ledger-0004-seed-role-permissions	Role→permission grants for ledger permissions	✓	Maps LedgerSystemPermissions codes to roles

4. Configuration Storage

Per-merchant runtime config lives in the MerchantLedgerConfig table (not the generic Configuration table). No encrypted credentials are stored by this service; the only secret is APP_ENV_LEDGER_ENCRYPTION_KEY (env).

Config	Storage	Read by
Required ledger types, filing schedules, tax level	ledger.MerchantLedgerConfig	MerchantLedgerConfigService, batch validation

5. Related Pages

• Operations
• Domain Model
• Decisions