Configuration

1. Environment Variables

Source: packages/core/src/common/environments.ts + packages/taxation/.env.development.

Core / Server

Name	Type	Default	Required	Description
RUN_MODE	startup|migrate	startup	✓	startup boots app + CDC consumer; migrate runs seeds
NODE_ENV	string	development		Runtime env
TZ	string	Asia/Ho_Chi_Minh		Timezone
APP_ENV_APPLICATION_NAME	string	taxation		App name
APP_ENV_APPLICATION_CODE	string	SVC-00130-TAXATION		Service code
APP_ENV_SERVER_HOST	string	localhost		Bind host
APP_ENV_SERVER_PORT	number	31130		HTTP port (container 3000)
APP_ENV_SERVER_BASE_PATH	string	/v1/api/taxation		Route prefix
APP_ENV_SNOWFLAKE_WORKER_ID	number	13	✓	Snowflake worker id (hardcoded — collision risk if scaled)
APP_ENV_SNOWFLAKE_EPOCH_CHECKPOINT	number	1735689600000		Snowflake epoch base

Database

Name	Type	Default	Required	Description
APP_ENV_POSTGRES_HOST	string	—	✓	PostgreSQL host
APP_ENV_POSTGRES_PORT	number	35432	✓	Port
APP_ENV_POSTGRES_USERNAME	string	—	✓	User
APP_ENV_POSTGRES_PASSWORD	string	—	✓	Password
APP_ENV_POSTGRES_DATABASE	string	nx_seller	✓	Database (schemas tax, pricing)

Identity / Auth

Name	Type	Default	Required	Description
APP_ENV_IDENTITY_SERVICE_BASE_URL	string	—	✓	Identity base URL for JWKS
APP_ENV_JWKS_REST_PATH	string	/jw-certs	✓	JWKS endpoint path
APP_ENV_APPLICATION_SECRET	string	—	✓	App secret

Kafka (CDC consumer)

Name	Type	Default	Required	Description
APP_ENV_KAFKA_BROKERS	string	—	✓	Comma-separated brokers
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00130-TAXATION		Consumer client id
APP_ENV_KAFKA_GROUP_ID	string	SVC-00130-TAXATION_CONSUMER_GROUP		Consumer group
APP_ENV_KAFKA_SASL_ENABLE	boolean	true		Enable SASL
APP_ENV_KAFKA_SASL_MECHANISM	string	SCRAM-SHA-512		SASL mechanism
APP_ENV_KAFKA_SASL_USERNAME / _PASSWORD	string	—		SASL credentials

2. Feature Flags

None. Behavior is driven by env vars and CDC payloads.

3. Seeded Data

Migration processes in src/migrations/processes/. Run in RUN_MODE=migrate via bun run migrate:dev. All four are alwaysRun: true (idempotent upsert). VN reference data is NOT seeded here.

File	Seeds	Idempotent	Notes
taxation-0001-seed-discrimination-types.ts	Tax classifications (scope tax_classification): VAT, Excise, Environmental, Luxury, PIT, Custom	✓	Backs TaxGroupItem.discriminationTypeId
taxation-0002-seed-tax-groups.ts	13 system tax groups + their TaxGroupItems (9 DIRECT + 4 DEDUCTION)	✓	Resolves items by DiscriminationType
taxation-0003-seed-permissions.ts	TaxationPermissions (TaxGroup, TaxGroupItem, Vn* read perms)	✓	Upsert by code
taxation-0004-seed-role-permissions.ts	Grants all taxation perms to OWNER, EMPLOYEE, CASHIER	✓	Lenient baseline; tightened later via policy-definition API

System tax groups (13)

DIRECT method (9 — VAT + PIT by industry):

Identifier	VAT	PIT	Industry
VN_DIRECT_VAT0_PIT05_DISTRIBUTION	0%	0.5%	Distribution
VN_DIRECT_VAT1_PIT05_DISTRIBUTION	1%	0.5%	Distribution
VN_DIRECT_VAT0_PIT2_SERVICES	0%	2%	Services
VN_DIRECT_VAT0_PIT5_SERVICES	0%	5%	Services
VN_DIRECT_VAT5_PIT2_SERVICES	5%	2%	Services
VN_DIRECT_VAT5_PIT5_SERVICES	5%	5%	Services
VN_DIRECT_VAT0_PIT15_MANUFACTURING	0%	1.5%	Manufacturing
VN_DIRECT_VAT3_PIT15_MANUFACTURING	3%	1.5%	Manufacturing
VN_DIRECT_VAT2_PIT1_OTHER	2%	1%	Other

DEDUCTION method (4 — VAT brackets):

Identifier	VAT
VN_DEDUCTION_VAT0	0%
VN_DEDUCTION_VAT5	5%
VN_DEDUCTION_VAT8	8%
VN_DEDUCTION_VAT10	10%

Reference enums

Enum	Source	Values
TaxMethods	tax/tax-group/constants.ts	000_DIRECT, 100_DEDUCTION
FixedTaxTypes	pricing/tax-type/constants.ts	000_VAT, 100_EXCISE, 200_ENVIRONMENTAL, 300_LUXURY, 400_PIT, 999_CUSTOM
TaxModes	pricing/tax/constants.ts	000_AMOUNT, 100_PERCENTAGE, 200_PER_UNIT_AMOUNT
TaxUsages	pricing/tax/constants.ts	000_SALE, 100_PURCHASE
TaxChargeTargets	pricing/tax-type/constants.ts	000_CUSTOMER, 100_MERCHANT

4. Configuration Storage (Configuration table)

Not used. Taxation holds no per-merchant runtime config or encrypted credentials.

5. Related Pages

• Operations
• Domain Model — Entities
• Decisions