# AI Starter — full documentation export

Generated: 2026-06-11T18:52:22.078Z

---

## Custom billing provider

URL: https://docs.oequ.io/billing/custom-provider

# Custom billing provider

Use this when Stripe is not available (e.g. YooKassa, CloudPayments, invoice billing).

See [Credits overview](/billing) and the monorepo guide `docs/BILLING_CUSTOM_PROVIDER.md`.

---

## Credits & billing

URL: https://docs.oequ.io/billing

# Credits & billing

## Credit ledger

Balances live in `credit_balances`; every movement is recorded in `credit_transactions`.

| Type | Meaning |
|------|---------|
| `grant` / `topup` | Add credits |
| `debit` | Job completed |
| `refund` | Job failed / cancelled |
| `monthly_reset` | Allowance top-up |

**Reserve** moves credits from `available` → `reserved` at submit. **Finalize** debits or refunds.

## Plans

| Plan | Generation credits / month |
|------|----------------------------|
| free | 500 |
| pro | 3,000 |
| team | 10,000 |

Plan changes sync allowance via `sync_org_generation_credits_for_plan` (service role / internal RPC only).

## Billing providers

| `billingProvider` | Checkout |
|-------------------|----------|
| `mock` | In-memory + `update_organization_plan` (local only, gated) |
| `stripe` | Stripe Checkout + webhooks |
| `custom` | Your Edge webhook → `apply_billing_subscription` |

UI uses `BillingPort` — no payment SDK in features.

## Web app adapter

`WebBillingAdapter` merges Postgres billing snapshot with mock plan metadata for display. Stripe paths invoke Edge functions; mock paths sync plan to Postgres after checkout.

See [Custom provider](/billing/custom-provider) and [Monthly reset](/billing/monthly-reset).

---

## Monthly reset

URL: https://docs.oequ.io/billing/monthly-reset

# Monthly reset

## Behavior

`reset_monthly_generation_credits()` runs on a schedule (pg_cron on hosted Supabase, or `credits-monthly-reset` Edge function).

For each org due for reset:

1. Compute allowance from plan (`free` / `pro` / `team`)
2. Set `available = max(current_available, allowance)` — **never reduces** carryover or purchased top-ups
3. Log positive delta as `monthly_reset` transaction
4. Advance `reset_at` to next UTC month boundary

Orgs with active `reserved` credits are **still reset** (allowance metadata); reserved amounts are unchanged.

## Stale jobs

`reap_stale_generation_jobs()` fails jobs stuck in `queued`/`processing` past a timeout (default 30 minutes) and refunds reserves via `finalize_generation_job`.

Schedule via pg_cron every 5 minutes or call `generation-reap-stale` Edge function with cron secret / service role.

## Operations

```bash
# Edge (self-hosted)
curl -X POST https://your-api/functions/v1/credits-monthly-reset \
  -H "Authorization: Bearer $SERVICE_ROLE_KEY"

curl -X POST https://your-api/functions/v1/generation-reap-stale \
  -H "X-Cron-Secret: $CREDITS_CRON_SECRET"
```

See ADR `docs/adr/0007-monthly-credit-reset.md`.

---

## Architecture

URL: https://docs.oequ.io/concepts/architecture

# Architecture

## Hexagonal layout

```text
apps (demo, web)
  provideDemoAdapters() / provideWebAdapters()
        ↓
libs/features-*  → inject *PORT, resource()
        ↓
libs/ports       → interfaces only
        ↓
adapters-mock | data-access-supabase
```

## Hard rules

1. **Never** import adapters from `libs/features-*` or `libs/ui`.
2. Features inject port tokens: `GENERATION_PORT`, `CREDIT_PORT`, `ORG_PORT`, …
3. `libs/ports` must not import `@angular/*` or `rxjs` in port logic.
4. Adapter swap **only** in `apps/*/src/app/app.config.ts`.

## Angular conventions

| Use | Avoid |
|-----|--------|
| Standalone components | New NgModules |
| `input()`, `computed()`, `resource()` | `@Input`, `subscribe()` in templates |
| `@if`, `@for` | `*ngIf`, `*ngFor` |
| Functional guards | Class guards |

### Critical: `inject()` in guards

Call `inject()` **before** any `await` in guards. After the first await there is no injection context → **NG0203**.

### `resource()` stability

Pass a **stable string key** in `params`, not a new object each computed run — avoids gallery flicker.

## Port results

Adapters return `PortResult<T>` (`ok` + `data` or `error`). Features branch on `result.ok`; templates use `resource()` loaders.

## Apps

| App | Backend | Use |
|-----|---------|-----|
| `apps/demo` | Mock only | Static hosting, PWA, fast E2E |
| `apps/web` | Supabase | Studio — full stack local + production |
| `apps/api-console` | Supabase | Public API developer portal |

---

## Concepts

URL: https://docs.oequ.io/concepts

# Concepts

AI Starter is organized around a few core ideas. Read these before changing code.

## Diátaxis map

| Section | Purpose |
|---------|---------|
| [Getting started](/getting-started) | Tutorials — run the stack |
| **Concepts** (here) | Explanations — why things are shaped this way |
| [Generation](/generation) | Domain + pipeline |
| [Billing](/billing) | Credits & payments |
| [Security](/security/production-hardening) | Production hardening |
| [Operations](/operations/stack) | Stack & workflow |

## Core principles

1. **Contracts over implementations** — ports in `libs/ports`, adapters in `libs/data-access-supabase` / `libs/adapters-mock`.
2. **Backend is authority** — RLS + Edge service role; Angular guards are UX only.
3. **Provider ignorance in UI** — logical model ids; fal/Stripe/YooKassa live at the edge or in config.
4. **Progressive productization** — mock path works without API keys; real providers behind env flags.

See [Philosophy & layers](/concepts/philosophy) and [Architecture](/concepts/architecture).

---

## Philosophy & layers

URL: https://docs.oequ.io/concepts/philosophy

# Philosophy & layers

## Mission

AI Starter is a **product-agnostic foundation** for SaaS apps that need organizations, **credits**, **async AI runs**, and a **creative studio** UX (boards, batch variants, gallery).

The platform investment stays reusable if a single vertical product fails.

## Three repository layers

```text
Product fork (e.g. ai-media-hub)
  fal catalog, regional payments, GTM
        ↓ fork from ai-starter
AI Starter (this repo)
  credits, generation, boards, chat shell
        ↓ merge starter/main
SaaS Starter
  auth, org, base billing, shell, RLS
```

## Decision checklist

| Question | If yes → |
|----------|----------|
| Auth, org shell, generic billing UI? | Upstream **saas-starter**, merge here |
| Credits, generation, boards, Edge pipeline? | **This repo** |
| fal-only GTM, video-first UX, one market? | **Product fork** |

## What does not belong here

- Product-only GTM docs
- Replacing Stripe adapters when `billingProvider: 'custom'` is enough
- Provider SDKs inside `libs/features-*`

Canonical detail: `docs/adr/0004-ai-starter-layer.md` in the monorepo.

---

## Security model

URL: https://docs.oequ.io/concepts/security

# Security model

## Trust boundaries

| Layer | Role |
|-------|------|
| Browser | Untrusted — anon key only |
| Angular guards | UX — redirect guests, hide billing |
| Postgres RLS | **Authorization** for reads |
| Edge Functions (service role) | **Authorization** for writes (credits, jobs, billing apply) |

## Generation

- `generate` / `generate-batch`: JWT + org membership + project editor
- `generation-webhook`: shared secret or provider signature; SSRF allow-list on output URLs
- `generation-process`: project editor (aligned with cancel)
- Credit RPCs: `service_role` only

## Billing

- Plan changes in production: `apply_billing_subscription` via verified webhooks
- `update_organization_plan`: gated by `private.platform_settings.self_serve_billing` (off by default; seed enables for local mock)

## Tables

`generation_jobs`, `credit_balances`, `credit_transactions` — SELECT for org members; no authenticated INSERT on jobs.

See [Production hardening](/security/production-hardening) for the full backlog and P0/P1 checklist.

---

## Generation domain

URL: https://docs.oequ.io/generation

# Generation domain

## Concepts

| Concept | Storage / port |
|---------|----------------|
| Board | `organization_projects` · `ProjectPort` |
| Generation job | `generation_jobs` · `GenerationPort` |
| Credits | ledger RPCs · `CreditPort` |
| Conversation | `conversations` · `ConversationPort` |
| Model | catalog in `libs/generation-core` |

## User flows

**Boards home** — prompt + model → create board → `submitJobBatch` → navigate to studio.

**Board studio** (`/boards/:slug`) — chat + gallery; batch rows with 4 variants; video uses `<video>`, not `<img>`.

## Credits per plan

| Plan | Monthly credits |
|------|-----------------|
| free | 500 |
| pro | 3,000 |
| team | 10,000 |

Insufficient credits → `CreditsUpsellDialogService` on HTTP 402 / `INSUFFICIENT_CREDITS`.

## Reference images (I2V)

Kling models require `referenceImage: 'required'`. UI uploads to Storage; local dev may use data URIs so fal never receives `127.0.0.1` URLs.

See [Pipeline](/generation/pipeline) and [Providers](/generation/providers).

---

## Generation pipeline

URL: https://docs.oequ.io/generation/pipeline

# Generation pipeline

## Request flow

```text
Angular → generate / generate-batch (JWT)
       → reserve_generation_credits (idempotent by job_id)
       → insert generation_jobs (queued)
       → provider.submitJob (mock | fal queue)
       → generation-webhook OR generation-process (sync)
       → persist output to Storage (prod)
       → finalize_generation_job
       → Realtime → studio UI
```

## Edge Functions

| Function | Auth | Purpose |
|----------|------|---------|
| `generate` | JWT | Single job |
| `generate-batch` | JWT | Up to 4 variants |
| `generation-webhook` | Secret / signature | Provider callback |
| `generation-process` | JWT + editor | Poll/sync fal job |
| `generation-reap-stale` | Cron / service role | Fail stuck jobs, refund |

## Credit lifecycle

1. **Reserve** on submit (`reserve_generation_credits`)
2. **Debit** on `completed` (`finalize_generation_job`)
3. **Refund** on `failed` / `cancelled` / timeout (reaper)

Finalize is **idempotent** — concurrent webhook + poll cannot double-charge.

## Catalog sync

Source of truth: `libs/generation-core`. Sync to Edge:

```bash
npm run catalog:sync
```

## Local dev

Without `FAL_API_KEY`, provider falls back to **mock** (picsum placeholders). With fal, local may defer to `generation-process` (client worker) when queue webhooks are unreachable on localhost.

---

## Providers

URL: https://docs.oequ.io/generation/providers

# Providers

## Registry

Edge provider selection (`supabase/functions/_shared/providers/registry.ts`):

| Env | Provider |
|-----|----------|
| `GENERATION_PROVIDER=fal` | fal.ai |
| `GENERATION_PROVIDER=muapi` | MuAPI (when `MUAPI_API_KEY` is set) |
| `GENERATION_PROVIDER=mock` | Local simulation |
| `FAL_API_KEY` set (auto) | fal |

`replicate` / `custom` are stubs that route to **mock** until implemented — do not use in production.

## fal.ai

- Queue mode with `generation-webhook` callback URL
- `GENERATION_WEBHOOK_SECRET` required in production
- Output URLs validated against allow-list (SSRF protection)

## Adding a provider

1. Implement `GenerationProvider` in `supabase/functions/_shared/providers/`
2. Register in `registry.ts`
3. Add catalog entries in `libs/generation-core`
4. Run `npm run catalog:sync`

UI and features stay unchanged — they only pass logical `modelId` and `parameters`.

See ADR `docs/adr/0005-generation-multi-provider.md` in the monorepo.

---

## Commands

URL: https://docs.oequ.io/getting-started/commands

# Commands

From the **monorepo root** (`ai-saas-starter/`).

## Development

| Task | Command |
|------|---------|
| Install | `npm install` |
| Demo (mock) | `npx nx serve demo` |
| Web (Supabase) | `npm run db:start` then `npm run start:web` |
| API console | `npm run start:api-console` (port 4202) |
| Docs site | `npm run docs:dev` |

## Quality

| Task | Command |
|------|---------|
| Lint all | `npx nx run-many -t lint` |
| Port unit tests | `npx nx run-many -t test --projects=ports` |
| E2E demo | `npm run e2e` |
| E2E web | `npm run e2e:web:release` |
| Edge shared tests | `npm run test:edge-shared` |

## Build

| Task | Command |
|------|---------|
| Build web | `npx nx build web` |
| Build demo (static hosting) | `npm run build:pages` |
| Build docs | `npm run docs:build` |

## Database

| Task | Command |
|------|---------|
| Start Supabase | `npm run db:start` |
| Stop | `npm run db:stop` |
| Reset (local) | `npm run db:reset` |
| Status | `npm run db:status` |

## Generation catalog sync

After editing `libs/generation-core`:

```bash
npm run catalog:sync
```

---

## Quick start

URL: https://docs.oequ.io/getting-started

# Quick start

Get from zero to a running board with generation in about **15 minutes**.

## Prerequisites

- **Node.js** ≥ 22, **npm** ≥ 11
- **Docker** (for full-stack `web` app + Supabase)
- Optional: **fal.ai** API key for real image generation

## Path A — Demo (no backend)

Best for exploring UI and running E2E locally without Docker.

```bash
# From your licensed source package
cd ai-saas-starter
npm install
npx nx serve demo
```

Open `http://localhost:4200`. Mock adapters simulate credits, billing, and generation.

## Path B — Full stack (Supabase)

```bash
npm install
npm run db:start          # Docker Supabase stack
npm run db:reset          # migrations + seed (local only!)
```

Copy `apps/web/src/app/supabase.settings.example.ts` → `supabase.settings.ts` and set `url` + `anonKey` from `npm run db:status` (or run `node scripts/write-web-supabase-settings.mjs`).

```bash
npm run start:web         # Angular web on :4201
```

### Optional: real fal generation

In `supabase/functions/.env`:

```env
FAL_API_KEY=your_key
GENERATION_PROVIDER=fal
```

Serve Edge functions: `npm run functions:serve`

## What to try

1. Sign up / sign in
2. Open **Boards** → create a board from the prompt composer
3. Watch batch variants in the studio gallery
4. Click **credits** in the toolbar to open plans

## Next steps

- [Local setup](/getting-started/local-setup) — env vars, Stripe, troubleshooting
- [Commands](/getting-started/commands) — full command reference
- [Architecture](/concepts/architecture) — ports & adapters

---

## Local setup

URL: https://docs.oequ.io/getting-started/local-setup

# Local setup

## Web app configuration

Create `apps/web/src/app/supabase.settings.ts` from the example file:

```ts
export const webSupabaseSettings = {
  url: 'http://127.0.0.1:54321',
  anonKey: '<from supabase status>',
  billingProvider: 'mock', // or 'stripe' | 'custom'
  // requireEmailConfirmation defaults to true (matches config.toml)
};
```

## Supabase

| Task | Command |
|------|---------|
| Start stack | `npm run db:start` |
| Reset DB (local only) | `npm run db:reset` |
| Status / keys | `npm run db:status` |

**Never** run `db:reset` on shared or production databases.

Studio is available at the URL printed by `db:status`.

## Edge Functions

Environment file: `supabase/functions/.env`

```env
GENERATION_PROVIDER=mock
# FAL_API_KEY=...        # optional
# GENERATION_WEBHOOK_SECRET=...  # production webhooks
```

Serve locally: `npm run functions:serve`

## Self-serve billing (mock checkout)

Migration `0043` gates `update_organization_plan` behind `private.platform_settings.self_serve_billing`.

Local `supabase db reset` enables it via seed. **Do not enable on production** — use verified billing webhooks instead. See [Custom billing provider](/billing/custom-provider).

## Common issues

| Symptom | Fix |
|---------|-----|
| HTTP 402 on generate | Top up credits (mock billing or plan change) |
| fal 422 on image URL | Use data URI rewrite for localhost references |
| Jobs stuck queued | Check `GENERATION_PROVIDER`, Edge logs |
| Video won't play | Add host to CSP `media-src` in `apps/web/src/index.html` |

---

## AI Starter documentation

URL: https://docs.oequ.io

# AI Starter documentation

**AI Starter** is a production-grade Angular + Supabase platform for building AI SaaS products: credits, async generation, multi-tenant billing, and a Luma-style creative UI.

## What you get

- **Money-safe credit ledger** — reserve, finalize, idempotent retries, refunds, monthly reset
- **Security by default** — Postgres RLS, service-role Edge writes, gated plan upgrades
- **Async generation pipeline** — provider-agnostic jobs, webhooks, batch variants
- **Stripe-optional billing** — custom provider webhooks (YooKassa, invoice, etc.)
- **Hexagonal architecture** — swap mock vs Supabase adapters; demo runs with zero backend

## Quick links

| I want to… | Start here |
|------------|------------|
| Evaluate before purchase | [Product overview](/product) |
| See what ships in the box | [Capabilities](/product/capabilities) |
| Run locally in 15 minutes | [Getting started](/getting-started) |
| Understand ports & adapters | [Architecture](/concepts/architecture) |
| Wire fal.ai / providers | [Generation domain](/generation) |
| Connect billing | [Custom billing provider](/billing/custom-provider) |
| Ship to production safely | [Security hardening](/security/production-hardening) |

## For AI assistants

- Index: [/llms.txt](/llms.txt)
- Full corpus: [/llms-full.txt](/llms-full.txt)

Licensed customers also receive an engineering handoff pack in the monorepo under `docs/` (ADRs, backlog).

---

## Internationalization

URL: https://docs.oequ.io/operations/i18n

# Internationalization

Translations live in `libs/i18n/src/assets/i18n/en/`.

## Usage in features

```ts
import { TranslocoPipe } from '@jsverse/transloco';

// template
{{ 'org.generation.creditsShort' | transloco }}
```

## Adding keys

1. Add JSON under `libs/i18n/src/assets/i18n/en/<scope>.json`
2. Register scope in loader if new file
3. **English only** in the repository (project rule)

## Shell / paywall

Key scopes: `paywall.json`, `credits-upsell.json`, `org-generation.json`, `shell.json`.

Docs site content is English-only in `apps/docs/content/`.

See `docs/I18N.md` in the monorepo for loader and locale service details.

---

## Stack

URL: https://docs.oequ.io/operations/stack

# Stack

| Layer | Technology |
|-------|------------|
| Frontend | Angular 21, standalone components, signals, `resource()` |
| UI | Spartan-ng (helm), Tailwind CSS 4 |
| i18n | Transloco |
| Monorepo | Nx 22 |
| Backend | Supabase (Postgres, Auth, Storage, Realtime, Edge Functions) |
| AI providers | fal.ai (wired), mock for dev |
| Billing | Stripe optional; custom webhook path |
| E2E | Playwright |
| Docs | Nextra 4 + Next.js 15 |

## Key libraries

- `@supabase/supabase-js` — production adapters
- `libs/generation-core` — shared model catalog (synced to Edge)
- `libs/ports` — framework-free contracts

## Apps

| App | Port (typical) |
|-----|----------------|
| demo | 4200 |
| web | 4201 |
| api-console | 4202 |
| docs | 3001 (dev); 3000 in Docker |

---

## Starter workflow

URL: https://docs.oequ.io/operations/workflow

# Starter workflow

## Syncing with SaaS Starter

**SaaS Starter** (`github.com/oequ/saas-starter`) is the free public foundation. **AI Starter** (this licensed repo) merges `starter/main` for auth, org, shell, and base billing, then adds credits, generation, and AI platform code.

**Rule:** SaaS core changes go upstream first, then merge here. AI platform changes stay in this repo.

## Where to put changes

| Change | Repo |
|--------|------|
| Auth, org, generic shell | saas-starter → merge |
| Credits, generation, boards | ai-saas-starter |
| fal GTM, video-only UX | product fork |

## Quality gates

```bash
npx nx run-many -t lint
npm run e2e                    # demo
npm run e2e:web:release        # web + Supabase
```

See `docs/WORKFLOW.md` and `docs/QUALITY.md` in the monorepo.

---

## From purchase to production

URL: https://docs.oequ.io/product/adoption-path

# From purchase to production

A typical path for teams buying AI Starter. Adjust timelines to your team size and compliance needs.

## Phase 0 — Evaluate (before purchase)

| Step | Action |
|------|--------|
| 1 | Browse [Capabilities](/product/capabilities) and [Architecture](/product/architecture) (this site) |
| 2 | Open **[demo.oequ.io](https://demo.oequ.io)** — click through boards, credits, billing UI |
| 3 | Confirm stack fit: Angular + Supabase + Edge Functions |
| 4 | Request access via the marketing site if you need the full repo |

No Supabase project required for Phase 0.

## Phase 1 — First run (day 1)

**Goal:** Clone and run something on a laptop.

```bash
git clone <your-licensed-repo>
cd ai-saas-starter
npm install
npx nx serve demo          # fastest: mock backend
# or
npm run db:start && npm run db:reset && npm run start:web
```

Follow [Quick start](/getting-started) and [Local setup](/getting-started/local-setup).

**Exit criteria:** You can sign in, open a board, and trigger a generation (mock or local fal).

## Phase 2 — Your Supabase project (week 1)

**Goal:** Own data in a cloud or staging project.

1. Create a Supabase project (or use local Docker for longer)
2. `npm run db:push` — apply migrations
3. Deploy Edge Functions and set secrets (`RESEND`, `FAL`, `STRIPE`, …)
4. Point `apps/web` at your project URL and publishable key

See `docs/DEPLOY_SUPABASE_CLOUD.md` in your licensed clone (not on public GitHub).

**Exit criteria:** `apps/web` talks to your project; RLS enforced; one real generation end-to-end.

## Phase 3 — Billing & branding (week 2–3)

**Goal:** Money path matches your market.

| Task | Notes |
|------|-------|
| Stripe or custom PSP | [Custom billing provider](/billing/custom-provider) |
| Plan prices | Stripe prices + env mapping |
| Email | Resend + `BRAND_*` for transactional mail |
| Legal | Your privacy/terms on marketing site |

**Exit criteria:** Test checkout upgrades plan; credits allowance updates; webhook idempotency verified.

## Phase 4 — Production hardening (week 3–4)

**Goal:** Safe to expose paying customers.

- Work through [Production hardening](/security/production-hardening)
- Configure CORS, secrets rotation, cron jobs (credit reset, stale job reaper)
- E2E smoke on staging: `npm run e2e:web` (from monorepo)

**Exit criteria:** Staging matches prod config; monitoring on Edge logs and Postgres.

## Phase 5 — Your product layer (ongoing)

AI Starter is the **platform**, not the GTM product.

| You own | Examples |
|---------|----------|
| Model positioning | Which fal models, pricing per credit |
| Vertical UX | Extra features on top of boards |
| Marketing | Landing copy, SEO, sales |
| Compliance | DPA, data residency choices |

Keep platform merges from upstream `ai-saas-starter` separate from your product fork strategy — see [Philosophy & layers](/concepts/philosophy).

## Where to get help

| Channel | Use |
|---------|-----|
| This docs site | Concepts, billing, generation, security |
| Monorepo `docs/` + ADRs | Engineering decisions (post-purchase) |
| Marketing contact form | License, access, commercial questions |

## Next

- [Quick start](/getting-started) — hands-on tutorial
- [Commands](/getting-started/commands) — full CLI reference

---

## Architecture

URL: https://docs.oequ.io/product/architecture

# Architecture

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

## High-level picture

```mermaid
flowchart TB
  users["Your users (browser)<br/>Angular apps: demo (mock) · web (Supabase)"]
  supabase["Supabase (your project)<br/>Postgres + RLS · Auth · Storage · Realtime<br/>Edge Functions: generate, billing, webhooks, landing-contact"]
  fal["fal.ai (or mock)"]
  psp["Stripe / your PSP"]

  users -->|HTTPS| supabase
  supabase --> fal
  supabase --> psp
```

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

## Hexagonal design (why it matters to you)

```mermaid
flowchart LR
  features["features-*"] --> ports["inject PORT tokens"] --> adapters["adapters (mock | Supabase)"]
```

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

## Trust boundaries

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

See [Security model](/concepts/security).

## Main domain modules

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

## Apps in the monorepo

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

## Extending without forking blindly

| 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](/concepts/philosophy).

## Next

- [Adoption path](/product/adoption-path) — how teams roll this out
- [Quick start](/getting-started) — clone and run (after license)

---

## Capabilities

URL: https://docs.oequ.io/product/capabilities

# Capabilities

Everything below ships in the codebase today. It is what you extend — not a slide-deck roadmap.

## Product surface (what your users see)

| Area | What works |
|------|------------|
| **Auth** | Email sign-up / sign-in, session handling, email confirmation (configurable) |
| **Workspaces** | Single account; Team plan unlocks org members and invites (no workspace switcher) |
| **Boards** | Creative boards: prompt composer, batch variants (e.g. 4 images), studio gallery |
| **Generation** | Async jobs: submit → queue → provider → storage → finalize credits |
| **Credits** | Balance in the UI, insufficient-credit upsell, usage tied to successful jobs |
| **Billing** | Plans (free / pro / team), checkout flows, portal, plan-gated features |
| **Settings** | Account, org members, billing, integrations catalog |
| **API console** | Separate app (`apps/api-console`): API keys, usage, billing, playground |
| **Help** | In-app help panel and contact support form (app context, not the marketing form) |

Try the UX without a backend: **[demo.oequ.io](https://demo.oequ.io)** (`apps/demo` with mock adapters).

## Platform (what you do not have to write)

### Credit ledger

- **Reserve → finalize** with idempotent request IDs
- **Refund** on failed or cancelled jobs (credits are not burned on provider errors)
- **Monthly allowance** reset per plan (free / pro / team)
- Auditable **transaction log**, not a single balance column

Details: [Credits & billing](/billing).

### Async generation pipeline

- Provider-agnostic job model ( **fal.ai** wired; mock for local dev)
- Signed webhooks, storage upload, batch rows, partial failure handling
- Model catalog in `libs/generation-core`, synced to Edge Functions

Details: [Generation domain](/generation).

### Security

- **Postgres RLS** as the authority — not route guards alone
- Privileged writes through **Edge Functions** with service role
- Plan upgrades and billing events via **verified webhooks**

Details: [Security model](/concepts/security), [Production hardening](/security/production-hardening).

### Billing adapters

| Mode | Use case |
|------|----------|
| `mock` | Local demo and E2E without Stripe |
| `stripe` | Checkout + subscription webhooks |
| `custom` | Regional PSP, invoice, YooKassa-style webhooks |

The Angular UI talks to a **BillingPort** — no Stripe SDK inside feature libraries.

Details: [Custom billing provider](/billing/custom-provider).

### Public API

- Versioned REST API via Edge Function `public-v1` (keys, rate limits, idempotency)
- Developer console on port **4202**: `npm run start:api-console`
- Studio (`apps/web`) and API console are separate deployables

Engineering detail: `docs/PUBLIC_API_CONSOLE_START_HERE.md` in the monorepo.

## Engineering quality

| Practice | In the repo |
|----------|-------------|
| **Hexagonal ports** | Swap mock vs Supabase in `app.config.ts` only |
| **Nx monorepo** | Shared libs: `ports`, `features-*`, `shell`, `ui` |
| **i18n** | Transloco; English in the app shell (locale infrastructure ready for more) |
| **E2E** | Playwright suites for demo and web |
| **Docs** | This site (Nextra), `llms.txt` for AI assistants |

## Stack

| Layer | Technology |
|-------|------------|
| Frontend | Angular 21+, standalone components, signals |
| UI | Spartan-ng, Tailwind CSS 4 |
| Backend | Supabase — Postgres, Auth, Storage, Edge Functions |
| AI | fal.ai (production path), mock provider (dev) |
| Docs site | Nextra 4 + Next.js (this site) |

Full table: [Stack](/operations/stack).

## What is intentionally out of scope

- We do not run your production Supabase or bill your end-users
- No single vertical “AI wrapper” GTM — you bring the model and positioning
- Marketing site and this docs app are **separate deployables** (Vite landing + Nextra docs)

## Next

- [Architecture](/product/architecture) — how the pieces connect
- [Adoption path](/product/adoption-path) — week-by-week rollout

---

## What you get

URL: https://docs.oequ.io/product

# What you get

**AI Starter** is a licensed, production-grade codebase — not a hosted SaaS from us. You receive the full Angular + Supabase stack, deploy it on your infrastructure, and own the product you build on top.

This section is for **evaluating before purchase**: what is actually shipped, how it is structured, and how teams typically adopt it.

## Who this is for

- You are building an **AI product** (image, video, or other async generation) with **credits** and **team workspaces**
- You want **billing, auth, RLS, and async jobs** solved once — not rebuilt for every launch
- You are comfortable with **Angular**, **Postgres**, and **Supabase** (or willing to hire for them)

## What you receive

| Deliverable | Description |
|-------------|-------------|
| **Source code** | Monorepo: `apps/web` (Studio), `apps/api-console`, `apps/demo` (mock), Edge Functions, migrations |
| **Documentation** | This site + engineering ADRs and runbooks in the repo under `docs/` |
| **Updates** | Per your license (see pricing on the marketing site) |

You do **not** get a managed multi-tenant cloud from us. You clone, configure env vars, and deploy to your Supabase project and static host.

## Two ways to explore before you buy

1. **[Live demo](https://demo.oequ.io)** — product UI with mock adapters (no Supabase required)
2. **This documentation** — read [Capabilities](/product/capabilities) and [Architecture](/product/architecture), then follow [Quick start](/getting-started) after purchase

## Recommended reading order

1. [Capabilities](/product/capabilities) — what is implemented today (not a wishlist)
2. [Architecture](/product/architecture) — ports, adapters, trust boundaries
3. [Adoption path](/product/adoption-path) — typical timeline from clone to production
4. [Quick start](/getting-started) — hands-on once you have the repo

Ready to request access? Use **Get AI Starter** in the navbar — it opens the contact form on the marketing site.

---

## Security

URL: https://docs.oequ.io/security

# Security

Start with [Production hardening](/security/production-hardening) for the launch checklist.

For the security model (RLS, Edge, trust boundaries), see [Security model](/concepts/security).

---

## Production hardening

URL: https://docs.oequ.io/security/production-hardening

# Production hardening

Checklist before public launch with real payments and fal.ai.

## P0 — ship blockers

| Item | Status |
|------|--------|
| Generation webhook auth + `external_job_id` binding | Done |
| SSRF allow-list on provider output URLs | Done |
| `sync_org_generation_credits_for_plan` not callable by users | Done |
| `update_organization_plan` gated (`self_serve_billing`) | Done |
| `finalize_generation_job` idempotent on credits | Done |

## P1 — reliability

| Item | Status |
|------|--------|
| Submit failure → finalize failed + refund | Done |
| `generation-process` requires project editor | Done |
| `credits-monthly-reset` / `generation-reap-stale` cron auth | Done |
| Idempotent `reserve_generation_credits` by `job_id` | Done |
| Batch partial 402 surfaced in UI | Done |
| Stale job reaper + monthly reset preserves balance | Done |

## P2 — product polish

- Metrics from `generation_jobs` (replace email metrics)
- Hide legacy `/workspace/emails` nav
- E2E: board → generate → gallery
- Failed job UX (`errorMessage`, refund hint)

## Environment checklist

```env
GENERATION_WEBHOOK_SECRET=...
GENERATION_PROVIDER=fal
FAL_API_KEY=...
CREDITS_CRON_SECRET=...
# private.platform_settings.self_serve_billing = false
```

## Full backlog

Canonical list: `docs/SECURITY_AND_RELIABILITY_BACKLOG.md` in the monorepo.