Skip to main content

​
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.