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 declares the seedPaths order. alwaysRun: true = idempotent permission seeds; false = one-time reference data (upsert by natural key).

File	Seeds	Always run	Notes
ledger-0001-seed-permissions	Ledger permission rows	✓	Upsert by code
ledger-0004-seed-role-permissions	Role→permission grants for ledger permissions	✓	Maps ledger permission codes to roles
ledger-0005-seed-ledger-identifiers	6 LedgerIdentifier rows (S1a-HKD..S2e-HKD) with i18n name/description	-	Upsert by identifier
ledger-0006-seed-tax-tiers	4 TaxTier rows (TIRE_1..TIRE_4) with revenue bounds	-	Upsert by code
ledger-0007-seed-ledger-tax-configs	LedgerTaxConfig tax approaches per tier (requiredLedgers, metadata.isDefault/isSelectable)	-	Upsert by (taxTierId, code); skips an approach if its TaxTier is missing (run 0006 first)

4. Configuration Storage

Reference data (form catalogue, tiers, approaches) is seeded into dedicated ledger.* tables, 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
HKD form catalogue	ledger.LedgerIdentifier	LedgerIdentifierController, generation pipeline
Revenue tiers	ledger.TaxTier	TaxTierController
Tax approaches + required forms	ledger.LedgerTaxConfig	LedgerTaxConfigController
Per-merchant per-year tax onboarding	ledger.MerchantTaxConfig	schema-only (no repository/service wired yet)

5. Related Pages

• Operations
• Domain Model
• Decisions