---
title: Welcome to Africa OS
description: Everything you need to understand, run, and extend the Africa OS monorepo - from the request lifecycle to shipping your first application module.
---

Africa OS is a modular, multi-tenant SaaS operating system. It provides the shared platform that every industry-specific application module plugs into: identity, organizations, permissions, and a unified shell, with a reference application built on top.

This knowledgebase is the developer guide to the monorepo. It is written for someone who knows nothing about the project yet and wants to go from zero to shipping a feature, an application, or a platform change.

<CardGroup cols={2}>
  <Card title="Getting started" href="/getting-started" icon="rocket">
    Clone the repo, install dependencies, and run the whole platform locally.
  </Card>
  <Card title="Repository overview" href="/repository-overview" icon="folder">
    Understand the monorepo layout: apps, platform packages, and shared packages.
  </Card>
  <Card title="Architecture" href="/architecture" icon="git-branch">
    Learn how tenants, identity, request context, and permissions fit together.
  </Card>
  <Card title="Guides" href="/guides" icon="graduation-cap">
    Follow step-by-step recipes for adding features and application modules.
  </Card>
</CardGroup>

### What Africa OS is

Africa OS is not a single product. It is a platform plus a collection of pluggable application modules. The platform handles the hard, cross-cutting concerns once, so each application module can focus on its domain:

- **Identity and authentication** - Better Auth under the hood, wrapped in an Effect service, with WorkOS for enterprise SSO.
- **Multi-tenancy** - Every organization is a tenant with a lifecycle and its own member roster.
- **Permissions** - Capability-based authorization where a permission is an `application.resource.action` string.
- **Request context** - One Effect runtime per HTTP request that resolves the current user, their organization, and their permissions.
- **The unified shell** - A single web app that mounts every application module into one navigable experience.
- **PostgreSQL** - One schema with migrations, scoped queries, and transactions managed by a single Effect database service.

```mermaid
flowchart LR
    subgraph Web["apps/web - TanStack Start"]
        Auth["Authentication"]
        Shell["Unified shell"]
        Registry["Application registry"]
    end

    subgraph Platform["platform/* packages"]
        RequestContext["request-context"]
        Permissions["permissions"]
        Organizations["organizations"]
        AuthService["auth"]
        Database["database"]
    end

    subgraph Modules["packages/applications/*"]
        Retail["retail"]
        Agriculture["agriculture"]
        School["school"]
    end

    PostgreSQL[("PostgreSQL")]

    Auth --> AuthService
    Shell --> Registry
    Registry --> Modules
    RequestContext --> AuthService
    RequestContext --> Organizations
    RequestContext --> Permissions
    Modules --> Database
    Platform --> PostgreSQL
```

### A short tour of the sections

- **Getting started** - prerequisites, install, environment, and running each app.
- **Repository overview** - how the monorepo is split and why.
- **Architecture** - the mental model behind multi-tenancy, authentication, the request context, and permissions.
- **Platform** - the details of each shared platform package: database, organizations, admin auth, and configuration.
- **Applications** - how application modules are structured, with the retail application as a full reference implementation.
- **Frontend** - the UI package, TanStack Start conventions, and data fetching patterns.
- **Database** - the full data model and the migration workflow.
- **Tooling** - pnpm, Nx, vite-plus, and testing conventions.
- **Guides** - practical recipes for common development tasks.

### Conventions used in this documentation

All code paths are relative to the repository root. Package names follow the `@africaos/*` scope, for example `@africaos/retail` or `@africaos/platform-database`. Where a concept lives in code, the documentation points at the exact file so you can open it and read the implementation.

<Panel title="A note on naming">
Africa OS applications are called **application modules** or just **applications**. They are not standalone deployables - they are libraries mounted inside the web app's unified shell. The word "application" in `packages/applications/*` refers to these modules.
</Panel>