Welcome to Africa OS

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.

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.

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.