---
title: Applications
description: How application modules are structured - self-describing packages mounted inside the unified shell.
---

Application modules (the "verticals") live in `packages/applications/*`. Each one is a host-agnostic package that self-describes through an `app.config.ts`, renders inside the unified shell, and owns its domain. The retail application is the reference implementation; the others are shells waiting for their domains.

<CardGroup cols={2}>
  <Card title="Anatomy of an application" href="/applications/anatomy-of-an-app" icon="box">
    The structure every application package follows.
  </Card>
  <Card title="Retail reference" href="/applications/retail-reference" icon="shopping-cart">
    A complete walkthrough of the reference implementation.
  </Card>
  <Card title="Building an application" href="/applications/building-an-application" icon="hammer">
    The step-by-step recipe for a new vertical.
  </Card>
</CardGroup>

### What an application module is

An application module is **not** a standalone deployable. It is a library that:

- Declares its identity and features in `app.config.ts`.
- Exports a mountable root component (`<XApplication organizationSlug={...} />`).
- Renders the shared shell chrome (`@africaos/shell`) or its own.
- Ships its domain as a feature folder with Effect service, server functions, hooks, schemas, and errors.
- Runs every server function through the request runtime.

The web app mounts it lazily at `/:organization/:application/*`. The shell is host-agnostic: the web app provides the sidebar (embedded mode), and a standalone host could render the application with the shell's own sidebar.

### The current roster

| Package | State |
| --- | --- |
| `@africaos/retail` | Reference implementation - full products feature. |
| `@africaos/agriculture`, `@africaos/government`, `@africaos/hospital`, `@africaos/logistics`, `@africaos/sacco`, `@africaos/school` | Shell modules with placeholder pages. |
| `@africaos/shell` | The shared shell machinery, not a vertical itself. |

### Feature-based structure

Each application organizes its domain as **features**. A feature folder bundles everything about one domain slice:

```txt
src/features/products/
├── service.ts                 Effect service - the business program
├── schemas/product.ts         Zod schemas and derived types
├── errors.ts                  typed errors
├── services/products.functions.ts  TanStack Start server functions
├── hooks/useProducts.ts       TanStack Query hooks
└── components/                page and UI components
```

This is the structure [Building an application](/applications/building-an-application) walks through end to end.

### Next steps

Start with [Anatomy of an application](/applications/anatomy-of-an-app) to see how a package is laid out.