---
title: Database
description: 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.

```mermaid
flowchart TB
    PG[("PostgreSQL")]
    subgraph Public["public schema"]
        Identity["user / session / account / verification (Better Auth)"]
    end
    subgraph Platform["platform schema"]
        Users["users"]
        Orgs["organizations"]
        Members["organization_members"]
        Perms["permissions"]
        Roles["roles / role_permissions / member_roles"]
        Apps["applications"]
        OrgApps["organization_applications"]
    end
    subgraph Retail["retail schema"]
        Products["products"]
    end
    subgraph Admin["admin schema"]
        Admins["admins"]
        Sessions["sessions"]
    end

    PG --- Public
    PG --- Platform
    PG --- Retail
    PG --- Admin
```

### 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

```mermaid
flowchart LR
    SQL["migrations/*.sql"] -->|pnpm db:migrate| Migrate["PgMigrator"]
    Migrate -->|applies in order| DB[(PostgreSQL)]
    DB -->|records in| Migrations["platform_migrations"]
    Seeds["seeds/development.sql"] -->|pnpm db:seed| Seed["seed script"]
    Config["app.config.ts files"] -->|pnpm db:register-apps| Register["register script"]
```

- **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](/database/data-model) - every table and relationship.
- [Migrations](/database/migrations) - the migration workflow in full.