Developer Getting Started

This guide gets you from zero to running your first BANA backend service locally.

Prerequisites

Tool	Version	Purpose
Bun	>= 1.3.8	Runtime, package manager, test runner
PostgreSQL	>= 14	Primary database
Redis	>= 7	Cache, pub/sub, BullMQ job queues
S3-compatible storage	-	Asset storage (MinIO for local dev)
Typesense	>= 0.25	Full-text search
Git	-	Version control
glab	-	GitLab CLI for MRs (optional but recommended)

For POS desktop development only:

• Rust + Tauri CLI

Clone & Install

git clone ssh://git@git.nexpando.com:2268/eventry/nx-seller.git
cd nx-seller
make install        # bun install + gateway portal install
make setup-tools    # configure git to use .githooks/

make install runs bun install at the workspace root plus a separate install for the gateway portal. make setup-tools sets core.hooksPath so the project's pre-commit hooks run on every commit.

Local Infrastructure

Start all dependencies using Docker Compose from the dev deployment directory:

cd infrastructure/deployments/develop

# Core dependencies (PostgreSQL, Redis, Kafka, Typesense, MinIO)
docker compose -f services/docker-compose.yml up -d

# CDC pipeline (Debezium: PostgreSQL -> Kafka -> Typesense)
docker compose -f cdc/docker-compose.yml up -d

Create the database:

psql -h localhost -U postgres -c "CREATE DATABASE nx_seller;"

Configure Environment

Each backend package uses dotenv-flow. Copy the example file to create your local config:

cp packages/identity/.env.development.example packages/identity/.env.development
cp packages/commerce/.env.development.example packages/commerce/.env.development
# repeat for each package you need to run

At minimum, verify these values in each .env.development:

Variable	What to check
APP_ENV_POSTGRES_*	Points to your local PostgreSQL
APP_ENV_CACHE_REDIS_*	Points to your local Redis
APP_ENV_SERVER_PORT	No port conflicts between services
APP_ENV_IDENTITY_SERVICE_BASE_URL	Points to your running identity service

See Environment Reference for the complete variable catalog.

Build

The monorepo has a strict build order because packages depend on each other. The Makefile handles this:

make build    # builds everything in the correct dependency order

This runs build-3rd (third-party integrations) then build-packages (all backend packages) in the dependency order:

core → asset, search, identity, inventory, finance, ledger, pricing, taxation, outreach, signal, sale
     → commerce (depends on asset + search)
     → payment (depends on core + mq-pay)

To build a single package (with its dependencies):

make identity    # builds core → mq-sms → identity
make commerce    # builds core → asset → search → commerce

Always use make or bun run rebuild

Never run tsc or npx directly. The build scripts handle path alias resolution (tsc-alias) that raw TypeScript compilation misses.

Run Migrations

Migrations are run per-package. The core package owns the shared database schemas:

# 1. Core schemas first (public, pricing, allocation, sale, inventory, finance, payment)
make db-migrate-all env=development

# 2. Per-package seed data (permissions, default configs)
cd packages/identity && bun run migrate:dev
cd ../commerce && bun run migrate:dev
cd ../sale && bun run migrate:dev
# ... repeat for each package you need

Or migrate a specific schema:

make db-migrate schema=public env=development
make db-migrate schema=pricing env=development
make db-migrate schema=inventory env=development

Run Your First Service

Identity is the best starting point - all other services depend on it for JWT verification.

make dev-identity

This starts the identity service on port 31010. Verify it's running:

curl http://localhost:31010/v1/api/identity/health
# Should return { "status": "ok" }

curl http://localhost:31010/v1/api/identity/jw-certs
# Should return the JWKS public keys

Then start other services as needed:

make dev-commerce    # port 31020
make dev-sale        # port 31030
make dev-finance     # port 31040
make dev-pricing     # port 31070

Each service exposes a Swagger UI at its base URL (e.g., http://localhost:31020/v1/api/commerce).

Service Registry

Service ports, codes, Snowflake IDs and base paths are generated from source and listed on Platform Facts - the single source of truth. The dev server you just started (identity) runs on 31010.

The helpdesk service build is currently broken.

Run Frontend Apps

make dev-app-client  # Admin dashboard - http://localhost:3001
make dev-app-bo      # Back office - http://localhost:3000
make dev-overture    # Marketing site - http://localhost:4321
make dev-wiki        # This documentation - http://localhost:5175

The POS desktop app requires Tauri:

cd apps/sale-main
cargo tauri dev

Run Tests

# Per-package unit tests (no DB required)
cd packages/licensing
bun run test:unit

# Per-package full test suite (may need .env.test + DB)
bun run test

Run Linting

make lint            # lint everything (apps + packages + third-parties + docs)
make lint-identity   # lint a single package
make lint-app-client # lint a single app

Zero lint errors

Lint errors are a hard gate - every commit and MR must pass make lint with zero errors. Run bun run lint:fix in the affected package to auto-fix most issues.

Common Scripts (Per Package)

Every backend package has the same script interface:

Script	Purpose
bun run rebuild	Clean + compile (always use this)
bun run server:dev	Dev server with .env.development
bun run server:local	Dev server with .env.local
bun run migrate:dev	Run migrations
bun run test	Full test suite
bun run test:unit	Unit tests only (if configured)
bun run lint:fix	ESLint + Prettier auto-fix

Next Steps

Topic	Page
All Makefile targets	Build System
Environment variables	Environment Reference
Git workflow & MRs	Git Workflow
IGNIS framework patterns	IGNIS Patterns
Backend packages	Packages Overview
Frontend apps	Apps Overview