Database

How the database is organized - schemas, the migration flow, seeds, and the scripts that drive it.

The database is one PostgreSQL instance hosting several schemas. This section covers the schema layout, the migration workflow, and the data model in detail.

The schemas

Schema	Owned by	Holds
`public`	Better Auth	Identity tables (`user`, `session`, `account`, `verification`).
`platform`	`@africaos/database` + platform services	Users, organizations, memberships, roles, permissions, applications, enablements.
`retail`	`@africaos/retail`	Vertical data - the reference vertical’s `products` table.
`admin`	`@africaos/admin-auth`	Admin identities and sessions.

The workflow

Migrations are ordered .sql files applied once each, recorded in platform_migrations.
Seeds are re-runnable upsert scripts for development (and a production baseline).
db:register-apps reads every app.config.ts and upserts the application registry.

Next steps

Data model - every table and relationship.
Migrations - the migration workflow in full.