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 through the shared LlmClient with text-embedding-3-small (default) or text-embedding-3-large; AI_LLM_TRANSPORT selects direct OpenAI or OpenRouter. Chunks are stored in document_chunks with pgvector + HNSW and retrieved via cosine distance (<=>) against ragMatchThreshold. Credits are deducted 1:1 with provider-reported embedding tokens. |
| Referral vs Affiliate | Referral = end-user program paying in-app credits. Affiliate = partner program paying cash commission through manual per-currency settlement. Separate cookies, salts, tables. |
| RLS | Postgres Row Level Security — domain rows are filtered through Account membership and the transaction-local application actor. Dedicated runtime, worker, maintenance and platform-admin credentials receive only their explicit capabilities. |
| Service client | A provider-native administrative client used only inside the matching Auth or Storage adapter. Business data uses the shared Prisma runtime; provider-native clients never become a database portability escape hatch. |
| Subscription vs License | Subscription = recurring billing through the configured provider. License = one-shot payment (lifetime/yearly/…). checkAccountAccess() unifies them; in hybrid mode subscription wins. |
| Trial | Provider-tracked period at the start of a subscription (status='trialing', trial_end mirrored by signed webhooks). The sidebar surfaces the end date. An early-conversion request creates a durable end_trial command before one provider mutation, waits synchronously for the provider acknowledgement, and returns 202 pending only when an ambiguous result needs reconciliation. Completion still requires provider state, signed local state, and normalized paid proof to converge. The paid webhook grants the conversion top-up with the normal provider-period ledger key. |
| User | An application identity in private.app_users, mapped to one provider and subject in private.auth_identities and represented by profiles. A user owns no business resource directly; resources attach to Accounts. |
| 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