Build System

The monorepo is orchestrated by a root Makefile (~750 lines). All build, lint, dev, deploy, and database operations go through it.

Run make help for the full target list.

Package Dependency Graph

make build runs build-3rd first, then build-packages in the order shown above.

Setup

Target	Command	Purpose
make install	bun install + gateway portal install	Install all workspace dependencies
make clean	bun run --filter "*" clean	Remove dist/ from all packages
make purge	find . -name node_modules -exec rm -rf	Delete all node_modules (nuclear option)
make setup-tools	git config core.hooksPath .githooks	Enable project git hooks
make rebuild	purge → clean → install → build	Full clean rebuild from scratch

Build Targets

Aggregate

Target	What it builds
make build	Everything (alias for build-all)
make build-all	build-3rd then build-packages
make build-packages	All packages/* in dependency order
make build-3rd	All third-parties/* (iiapi, mq-pay, mq-sms, t-van)

Individual packages

Each target automatically builds its dependencies first (via Makefile prerequisites).

Target	Dependencies	Package
make core	-	@nx/core
make asset	core	@nx/asset
make search	core	@nx/search
make identity	core, mq-sms	@nx/identity
make inventory	core	@nx/inventory
make finance	core	@nx/finance
make outreach	core	@nx/outreach
make ledger	core, asset	@nx/ledger
make pricing	core	@nx/pricing
make taxation	core	@nx/taxation
make commerce	asset, search	@nx/commerce
make sale	core	@nx/sale
make payment	core, mq-pay	@nx/payment
make signal	core	@nx/signal
make licensing	core	@nx/licensing

Third-parties

Target	Package
make iiapi	@nx/iiapi
make mq-pay	@nx/mq-pay
make mq-sms	@nx/mq-sms
make t-van	@nx/t-van

Frontend apps

Target	Package
make bo	@nx-app/bo
make client	@nx-app/client
make overture	@nx-app/overture
make app-core	@nx-app/core

Frontend builds run bun run apps:rebuild first (rebuilds shared app libraries), then the app-specific build.

Per-Package Build Internals

Every backend package has identical build scripts:

bun run rebuild     # → scripts/rebuild.sh → clean.sh + compile.sh
bun run build       # → scripts/build.sh
bun run compile     # → scripts/compile.sh (tsc + tsc-alias)
bun run clean       # → scripts/clean.sh (rm -rf dist/)

Always use bun run rebuild or make <pkg>

Never invoke tsc or npx directly. The build uses tsc-alias to resolve path aliases like @/services to relative paths in the compiled output. Raw tsc produces broken imports.

Compile (Standalone Binaries)

Bun can compile services into single-file executables:

Target	Builds first	Output
make compile-commerce	commerce	packages/commerce/dist/bin/
make compile-finance	finance	packages/finance/dist/bin/
make compile-identity	identity	packages/identity/dist/bin/
make compile-inventory	inventory	packages/inventory/dist/bin/
make compile-payment	payment	packages/payment/dist/bin/
make compile-pricing	pricing	packages/pricing/dist/bin/
make compile-sale	sale	packages/sale/dist/bin/
make compile-signal	signal	packages/signal/dist/bin/
make compile-ledger	ledger	packages/ledger/dist/bin/
make compile-licensing	licensing	packages/licensing/dist/bin/
make compile-outreach	outreach	packages/outreach/dist/bin/

Docker

Build Docker images for deployment:

# Current version
make docker pkg=identity

# Bump patch version (0.0.1 → 0.0.2) then build
make docker pkg=identity v=patch

# Set explicit version
make docker pkg=identity v=0.2.0

# Bump prerelease (0.0.1 → 0.0.1-1)
make docker pkg=identity v=pre

# Build with tag only (no package.json change)
make docker pkg=identity tag=0.0.1-2

# Build ALL images
make docker-all

Available package names: identity, commerce, sale, finance, inventory, ledger, payment, pricing, signal.

The build script is at scripts/build-docker.sh. Images are pushed to the project's container registry.

Lint

Target	Scope
make lint	Everything (alias for lint-all)
make lint-all	lint-apps + lint-packages + lint-3rd + lint-docs
make lint-apps	All apps/*
make lint-packages	All packages/*
make lint-3rd	All third-parties/*
make lint-docs	All docs/*
make lint-wiki	@nexpando/eventry-docs only
make lint-packages-fix	Auto-fix all packages
make lint-<package>	Single package (e.g. lint-identity, lint-commerce)
make lint-app-<app>	Single app (e.g. lint-app-client, lint-app-bo)

Pass --elide-lines=0 to a bun run command for verbose (un-elided) output in a terminal. Note: this flag only works in a TTY and errors in CI, so the Makefile does not use it.

Dev Servers

Target	Service	Port
make dev-identity	Identity	31010
make dev-commerce	Commerce	31020
make dev-sale	Sale	31030
make dev-finance	Finance	31040
make dev-inventory	Inventory	31050
make dev-ledger	Ledger	31060
make dev-pricing	Pricing	31070
make dev-payment	Payment	31080
make dev-signal	Signal	31090
make dev-outreach	Outreach	31110
make dev-taxation	Taxation	31130
make dev-app-bo	Back Office	3000
make dev-app-client	Admin Dashboard	3001
make dev-overture	Marketing Site	4321
make dev-portal	Gateway Portal	-
make dev-wiki	This documentation	5175

Database

Target	Usage
make db-generate schema=<name> env=<env>	Generate migration SQL for a schema
make db-generate-all env=development	Generate migrations for all 14 schemas
make db-migrate schema=<name> env=<env>	Apply migrations for a schema
make db-migrate-all env=development	Apply migrations for all schemas
make db-migrate-<pkg>-dev	Dev seed migration for one package (e.g. db-migrate-ledger-dev)

Schema names: allocation, finance, helpdesk, identity, inventory, invoice, ledger, licensing, outreach, payment, pricing, public, sale, tax

Database commands run in packages/core which owns the shared Drizzle ORM schema definitions.

Deploy (Dev Server)

Target	Deploys
make deploy-develop-infra	Infrastructure dependencies
make deploy-develop-gateway	Traefik gateway
make deploy-develop-backend-services	All backend services (identity through licensing)
make deploy-develop-<service>	Individual service (e.g. deploy-develop-identity)
make deploy-develop-client	Admin dashboard
make deploy-develop-bo	Back office
make deploy-develop-overture	Marketing site
make deploy-develop-wiki	Documentation
make deploy-develop-prototypes	Design prototypes

Deploy scripts live in infrastructure/deployments/develop/scripts/.

Benchmark

Target	Purpose
make benchmark-ledger	Run PDF + XLSX generation benchmark for all 6 ledger types

Git Hooks

Target	Purpose
make setup-tools	Configure git to use .githooks/
make pre-commit	Run all linting checks (used by pre-commit hook)

Related Pages

Page	Description
Getting Started	First-time setup walkthrough
Environment Reference	All environment variables
Git Workflow	Branch naming, commits, MRs