> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributor Architecture

> Repo shape and runtime boundaries for contributors.

# Contributor Architecture

This page is the contributor-oriented architecture view. The product architecture pages go deeper on business logic; this page answers the simpler question:

Where should a contributor make a change?

## Active apps

* **`apps/app`**: operator UI for inbox, contacts, templates, campaigns, journeys, settings, and runtime views.

* **`apps/web`**: public-facing site and marketing-adjacent pages.

* **`apps/api`**: Next.js API surface for internal endpoints, compatibility routes, and the current hosted alpha ingress on Vercel.

* **`apps/control-plane`**: dedicated Node runtime for webhook-oriented and queue-oriented control-plane work. It remains in the repository, but is not part of the current hosted alpha contract.

* **`apps/worker`**: background worker loop for outbox processing and reconciliation, intended for Railway in alpha.

* **`apps/storybook`**: shared component workbench.

## Shared packages

* **`packages/auth`**: Supabase auth helpers and session plumbing
* **`packages/database`**: the only supported data-plane boundary, including repository contracts, adapters, and migration-facing ownership
* **`packages/design-system`**: shared UI primitives
* **`packages/domain`**: domain contracts, mock data, and runtime env parsing
* **`packages/feature-flags`**: flag helpers and toolbar utilities
* **`packages/observability`**: logging and lightweight runtime instrumentation
* **`packages/security`**: proxy/security middleware helpers
* **`packages/whatsapp`**: provider schemas, payload validation, and constraint constants

## Active workspace boundary

The `0.1.x` release line intentionally supports the active workspaces listed above.

The repo also retains several `next-forge`-derived apps and packages outside the active workspace set. Those files are scaffold material for later feature activation, not part of the default verification contract yet.

## Runtime split

Contributors should think about the repo as three execution layers:

1. **Frontend layer** in `apps/app`, `apps/web`, and `apps/docs`
2. **Request/HTTP layer** in `apps/api` and `apps/control-plane`
3. **Background processing layer** in `apps/worker`

Supabase is the common data plane across those layers.

## Where to put common changes

* Add shared types or domain contracts in `packages/domain`.
* Add provider validation or payload schemas in `packages/whatsapp`.
* Add shared data access logic in `packages/database`.
* Add operator-facing reusable UI in `packages/design-system`, with Storybook stories.
* Add route-specific behavior in the app that actually owns the runtime.

## Current implementation note

* The repo already carries a Supabase schema baseline and auth/env contract.
* Many contributor-visible product surfaces still run against the typed mock-backed repository layer.
* The repo does not yet have a true ORM abstraction; do not describe it that way until mock and Supabase adapters conform to shared repository interfaces.
* When changing behavior, document whether your change affects the mock path, the Supabase path, or both.

## Read next

* [Development](/development)
* [Persistence Boundary](/contributing/persistence)
* [Platform Architecture](/platform/architecture)
* [Contribution Workflow](/contributing/workflow)