Applications

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.

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

Feature-based structure

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

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 walks through end to end.

Next steps

Start with Anatomy of an application to see how a package is laid out.