Architecture

A buyer-friendly map of how AI Starter is put together. For implementation rules and code layout, see Architecture (technical).

High-level picture

Rule of thumb: the browser never holds secrets. Credits, billing, and generation finalize on the server; the UI only calls ports.

Benefit	What it means for your team
Demo without Docker	Sales and design use `apps/demo` while backend catches up
Testable features	Mock adapters in CI; swap one line for production
Fork-friendly	Replace fal with another provider at the Edge layer, not in every component

Ports live in libs/ports. Supabase implementations live in libs/data-access-supabase. Feature code does not import SQL or SDKs directly.

Layer	Responsibility
Angular guards	UX routing only — not security
RLS policies	Who can read/write which rows
Edge Functions	Service-role writes, webhooks, provider calls
Webhooks	Stripe / custom billing verified before plan changes

Domain	Responsibility
Auth & org	Users, workspaces, members, invites
Credits	Ledger RPCs, reserve/finalize, monthly reset
Generation	Boards, jobs, batches, provider registry
Billing	Plans, checkout, subscription sync
Shell	Layout, nav, help, shared UX patterns

Generation and credits are tightly coupled by design: a job only debits when it succeeds.

App	Backend	Typical use
`apps/demo`	Mock adapters only	Public demo, fast UI iteration
`apps/web`	Supabase	Studio — your production-shaped app
`apps/api-console`	Supabase	API keys, usage, billing, playground
`apps/docs`	Static (this site)	Customer + engineer documentation

Marketing landing (ai-saas-starter-landing) is a separate repository — Vite + React, links here for pre-purchase research.

Change	Where to work
New AI model	`libs/generation-core` catalog + provider adapter
New payment region	Custom billing webhook + `BillingPort` adapter
New vertical UI	New `libs/features-*` consuming existing ports
White-label email	Edge env (`BRAND_*`, Resend)

Philosophy and layer boundaries: Philosophy & layers.