The terms most often confused when first reading this codebase. The architecture is account-centric — internalize the first two rows and the rest follows.
| Term | Meaning |
|---|---|
| Account | The unit everything attaches to: credits, subscription/license, chat, API keys, settings. Type is personal or workspace. |
| Attribution cookie | httpOnly cookie (bsk_ref / bsk_aff) set by the tracking redirect; read server-side at onboarding to credit the referrer/affiliate. |
| Credit | Internal AI currency. 1 credit = 1 LLM token. Mutated only via the add_credits / decrement_credits RPCs; every change lands a credit_transactions row. |
| CSRF Double-Submit | Anti-CSRF pattern: a cookie/header token pair validated for equality on every state-changing request. Enforced inside apiSecurity.* / withSecurity() alongside Origin/Referer validation against appConfig.url — no separate route wrapper. Client-initiated POSTs use csrfFetch() to attach the header automatically. |
| Magic-link OTP | Dual sign-in path: one /api/auth/magic-link call produces both a clickable link (Path A — callback route) and a 6-digit code (Path B — /api/auth/verify-otp). Default length is 6, configurable 6–10 via the server-only OTP_LENGTH env. The success screen polls auth.getUser() every 4s so a click in another tab auto-redirects the original tab (cross-tab auto-redirect). |
| Membership | The link between a user and an account, carrying a role_slug. A user reaches an account's data only through a membership. |
| Onboarding state | profiles.onboarding_completed (boolean). The single onboarding gate lives in app/[locale]/(auth)/checkout/success/page.tsx — checkout runs before profile collection. Re-adding the gate in middleware or a Client Component is anti-pattern A13. |
| Plan | A pricing tier defined in config/pricing.ts (the source of truth) — never a database row. subscriptions.plan_id is a string reference into config. |
| RAG / Embedding | Retrieval-Augmented Generation via the Knowledge Base rag agent. Documents are chunked and embedded with text-embedding-3-small (default) or text-embedding-3-large from embeddingConfig in config/ai.ts; chunks are stored in document_chunks with pgvector + HNSW index, retrieved via cosine distance (<=>) against the configured ragMatchThreshold. Credits are deducted 1:1 with the embedding tokens returned by OpenAI. |
| Referral vs Affiliate | Referral = end-user program paying in-app credits. Affiliate = partner program paying cash commission (Stripe Connect payouts are Phase 3, not yet shipped — Phases 1–2 cover application, tracking, and conversions). Separate cookies, salts, tables. |
| RLS | Postgres Row Level Security — every domain table is filtered by membership on its account_id. Service-role clients bypass it for admin/cache paths. |
| Service client | createServiceClient() / supabaseAdmin — bypasses RLS. Required inside unstable_cache(); never use the cookie-bound createClient() there. |
| Subscription vs License | Subscription = recurring Stripe billing. License = one-shot payment (lifetime/yearly/…). checkAccountAccess() unifies them; in hybrid mode subscription wins. |
| Trial | Stripe-tracked period at the start of a subscription (status='trialing', trial_end mirrored from Stripe). The sidebar surfaces "ends on {date}" badge; endTrialEarly in core/billing/mutations.ts exits the trial via stripe.subscriptions.update(…, { trial_end: 'now' }) plus a synchronous credit grant (creditsIncluded - trialAmountAlreadyGranted) so the conversion top-up lands before the invoice.paid webhook arrives. Credits accounting stays 1 token = 1 credit through both the trial and the paid period. |
| User | An identity (a row in auth.users / profiles). A user owns nothing directly — resources never attach to a user. |
| Workspace (B2B) | An account of type workspace — the shared, paid container for a team. Auto-bootstrapped at signup via ensureWorkspaceForUser (idempotent) at five sites: the magic-link callback, the OAuth callback, POST /api/auth/verify-otp, the /checkout Server Component, and the free-plan path through /api/billing/subscribe-free. /onboarding/workspace is a legacy manual-creation fallback only. |
Documentation for Boilerplate Stack v0.1.0 · Last updated 2026-05-20