Running the platform

Day-to-day commands for the local development environment - prerequisites, database scripts, apps, and quality gates.

This page is the operating manual for a local development environment. Everything below runs from the repository root unless stated otherwise.

Prerequisites

Node 22.12 or newer (the repo targets modern toolchains).
pnpm 11.20.0 (pinned via packageManager). Never npm.
A local Postgres instance, and a DATABASE_URL that points at it (see Configuration).
Portless handles local hostnames (web.africaos, admin.africaos) for the apps.

One-time setup

pnpm install
cp .env.example .env      # then edit DATABASE_URL and any other values
pnpm db:migrate
pnpm db:seed              # development seed: users, orgs, registry, roles
pnpm db:register-apps     # register app.config.ts entries into platform.applications
pnpm db:seed:admin        # create the admin console credentials

db:seed:admin prints the admin name and password it creates - sign in to the admin console with them.

Running everything

pnpm dev                  # nx run-many -t dev: every app with a dev target

Or run apps individually:

App	Command
Web (main host)	`pnpm --filter @africaos/web dev` (served at `web.africaos`)
Admin console	`pnpm --filter @africaos/admin dev` (served at `admin.africaos`)
Any single app	`pnpm nx run <project>:dev`

Database scripts

Command	What it does
`pnpm db:migrate`	Applies pending migrations (idempotent).
`pnpm db:seed`	Development seed; re-runnable.
`pnpm db:seed:production`	Production baseline seed.
`pnpm db:register-apps`	Upserts all `app.config.ts` entries into the registry.
`pnpm db:seed:admin`	Creates/updates the admin account.
`pnpm db:verify:org`	Inspects an organization’s state (dev helper).

Quality gates

Run these before pushing or opening a PR:

pnpm typecheck
pnpm test
pnpm lint
pnpm format

All four are Nx-aware - they run across every package that has the target, in dependency order. Scoped variants:

pnpm nx affected -t typecheck test lint
pnpm nx run @africaos/retail:test
pnpm --filter @africaos/web typecheck

Common scenarios

Adding or editing an application config. Run pnpm db:register-apps after changing app.config.ts - the launcher and access gates read the registry.

Changing the schema. Add a migration (see Migrations) and run pnpm db:migrate. Re-run pnpm db:seed if the new table needs seed data.

The admin console does not list an organization. The organization must be verified (the app shows active organizations). See the lifecycle.

A new application does not appear in the launcher. Check three things: it is registered (pnpm db:register-apps), it is enabled for the organization (platform.organization_applications), and the member holds platform.applications.access.

Ports and hostnames

Web app: web.africaos (portless maps the local hostname).
Admin console: admin.africaos.
The knowledgebase itself runs with pnpm --filter knowledgebase dev (see its package scripts).