# Africa OS Knowledgebase

> The complete developer documentation for Africa OS - a modular, multi-tenant SaaS operating system built on Effect, TanStack Start, and PostgreSQL.

## Docs

- [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.
- [Getting started](/getting-started): Set up Africa OS on your machine - prerequisites, install, environment configuration, database setup, and running the apps.
- [Repository overview](/repository-overview): How the Africa OS monorepo is organized - apps, platform packages, application modules, shared packages, and tooling.

## Architecture

- [Architecture](/architecture): The mental model behind Africa OS - how tenants, identity, request context, permissions, and the application registry fit together.
- [Multi-tenancy](/architecture/multi-tenancy): How organizations act as the tenant boundary - the organization model, lifecycle, memberships, and the active-organization context.
- [Authentication](/architecture/authentication): How identity works - Better Auth behind an Effect service, sessions, Google OAuth, WorkOS enterprise SSO, and the session helpers server code uses.
- [Request context](/architecture/request-context): How Africa OS turns one HTTP request into a fully provisioned Effect runtime - user, organization, permissions, and a run function for server programs.
- [Permissions](/architecture/permissions): Capability-based authorization - permission strings, roles, resolution, and the guards server and client code use.
- [Application registry](/architecture/application-registry): How applications self-describe through app.config.ts, register with RegistryService, and get mounted by the web app.
- [Unified shell](/architecture/unified-shell): How the web app composes authentication, the sidebar, the organization switcher, and application mounts into one navigable product surface.

## Platform

- [Platform](/platform): The shared platform packages and how they serve as the backend of record for the whole product.
- [Database](/platform/database): The Database Effect service - the only way platform code talks to PostgreSQL, with scoping helpers, transactions, and a test layer.
- [Organizations](/platform/organizations): The organizations package - OrganizationService, MembershipService, RegistryService, schemas, and the errors they raise.
- [Admin auth](/platform/admin-auth): Operator identity for the admin console - a separate admin schema, scrypt password hashing, and SHA-256-hashed session tokens.
- [Admin console](/platform/admin): The admin app - how operators log in and manage the platform's organizations and admins.
- [Configuration](/platform/configuration): Central configuration - validated environment variables, product constants, feature flags, and the ApplicationConfig contract.

## Applications

- [Applications](/applications): How application modules are structured - self-describing packages mounted inside the unified shell.
- [Anatomy of an application](/applications/anatomy-of-an-app): The structure every application module follows - package layout, app.config.ts, the mountable root, features, routes, and exports.
- [Retail reference](/applications/retail-reference): A complete walkthrough of the retail application - the reference implementation every other vertical should mirror.
- [Building an application](/applications/building-an-application): The step-by-step recipe for adding a new application module to the platform - package, config, shell, feature, routes, registry, and mount.

## Frontend

- [Frontend](/frontend): The frontend stack - the shared UI package, TanStack Start conventions, data fetching, and the web app structure.
- [UI library](/frontend/ui-library): The @africaos/ui component package - structure, theming, and conventions.
- [TanStack Start](/frontend/tanstack-start): The app framework conventions - file routing, server functions, server-first rendering, and the web app's route tree.
- [Data fetching](/frontend/data-fetching): How server functions, TanStack Query, and hooks compose - the client-side data pattern applications use.
- [Web app](/frontend/web-app): The @africaos/web app - its routes, guards, shell components, and server functions, and how they compose into the product surface.

## Database

- [Database](/database): How the database is organized - schemas, the migration flow, seeds, and the scripts that drive it.
- [Data model](/database/data-model): Every table in the database - the public identity schema, the platform schema, the retail vertical schema, and the admin schema.
- [Migrations](/database/migrations): The migration workflow - how schema changes are authored, applied, and recorded, plus the seeds and registry scripts.

## Tooling

- [Tooling](/tooling): The developer toolchain - pnpm, Nx, vite-plus, and the testing conventions that keep the monorepo predictable.
- [Nx and pnpm](/tooling/nx-and-pnpm): How the monorepo is managed - pnpm workspaces, the dependency catalog, and Nx task orchestration.
- [vite-plus](/tooling/vite-plus): The developer experience toolchain - vp commands for linting, testing, typechecking, and formatting.
- [Testing](/tooling/testing): The testing conventions - @effect/vitest, in-memory PGlite, focused tests, and the strongest-invariant rule.

## Guides

- [Guides](/guides): Practical, step-by-step recipes for the most common development tasks.
- [Adding a feature](/guides/adding-a-feature): The end-to-end recipe for adding a domain feature to an application module - schema, service, server functions, hooks, and UI.
- [Adding an application](/guides/adding-an-application): The full recipe for a new application module - scaffold, register, mount, enable, and build the first feature.
- [Running the platform](/guides/running-the-platform): Day-to-day commands for the local development environment - prerequisites, database scripts, apps, and quality gates.