---
title: Platform
description: The shared platform packages and how they serve as the backend of record for the whole product.
---

The `platform/` directory holds the cross-cutting backend packages. These implement the concerns every application module depends on: the database gateway, identity, tenants, permissions, request context, and admin identity. This section documents each one in code-level detail.

The platform packages are deliberately small in number - a locked set that the architecture deliberately limits. `auth`, `database`, `organizations`, and `permissions` carry the load; `request-context` composes them; `admin-auth` handles the admin console separately.

<CardGroup cols={2}>
  <Card title="Database" href="/platform/database" icon="database">
    The one gateway to Postgres: services, scoping helpers, and transactions.
  </Card>
  <Card title="Organizations" href="/platform/organizations" icon="building-2">
    The full service surface for tenants, memberships, and the registry.
  </Card>
  <Card title="Admin auth" href="/platform/admin-auth" icon="shield">
    Operator identity for the admin console, in its own schema.
  </Card>
  <Card title="Admin console" href="/platform/admin" icon="gauge">
    The admin app itself and what it manages.
  </Card>
  <Card title="Configuration" href="/platform/configuration" icon="settings">
    Environment variables, constants, and feature flags.
  </Card>
</CardGroup>

### The platform dependency graph

Platform packages depend only on each other and on shared core packages (`@africaos/config`, `@africaos/logger`). They never depend on apps or application modules, keeping the platform independent of any single vertical.

```mermaid
flowchart TB
    Config["@africaos/config"]
    Logger["@africaos/logger"]
    Database["@africaos/database"]
    Organizations["@africaos/organizations"]
    Permissions["@africaos/permissions"]
    Auth["@africaos/auth"]
    AdminAuth["@africaos/admin-auth"]
    RequestContext["@africaos/request-context"]

    Database --> Config
    Logger --> Config
    Organizations --> Database
    Organizations --> Logger
    Permissions --> Database
    Auth --> Database
    AdminAuth --> Database
    AdminAuth --> Logger
    RequestContext --> Database
    RequestContext --> Logger
    RequestContext --> Auth
    RequestContext --> Organizations
    RequestContext --> Permissions
```

### The Effect service pattern

Every platform package follows the same structure:

1. A `Context.Service` class defines the tag and its method surface (the `Service` type).
2. A `static Live` layer builds the production implementation, wired to whatever `Database` and `Logger` provide.
3. Where relevant, a `static Test` layer replaces the database with `Database.Test`, so tests run without Postgres.
4. The implementation is factored into a `makeXService` function, so tests can construct one directly.

Server functions never instantiate services. They `yield*` them inside an Effect program, and the request runtime provides them.

### A note on placeholder packages

`notifications`, `offline`, `sdk`, `search`, and `storage` exist as workspace members but export nothing yet. They are reserved slots for future platform work. Do not import them - they have nothing to offer.

### Next steps

Start with [Database](/platform/database) - every other platform package builds on it.