Reference

Glossary

Living definitions — adhered to in every lesson. If code and this glossary disagree, code wins and we update here.

How to use

Keep this open while reading code. Each term links to where it lives.

Template: A questionnaire definition. lib/db/schema.ts → templates
Fields: title, topic, context, targetAudience, scaleLength (default 5), scaleLevels[], domains[] → questions[]. visibility: private | public, clonedFromId, researchBrief.
ScaleLevel: One rung on the maturity scale. lib/db/schema.ts
{ level: number, label: string, description: string }. Count = scaleLength.
Domain: A section inside a template. lib/db/schema.ts → Domain
{ id, name, questions: Question[] }. Reports aggregate per domain.
Question: lib/db/schema.ts → Question
{ id, text, type: 'scale' | 'text' }. Scale questions get 1..scaleLength buttons.
Assessment: An instance of a template sent to a team. assessments
status: draft | active | closed, inviteToken: nanoid(32) unique, teamName, dueDate.
Response: One respondent's submission. responses
answers: Record<questionId, number|string> in jsonb, plus respondentName/Role.
Invite Token: The shareable key in /respond/[token]. No auth required to submit. Checked for active status in submitResponse.
Server Action: Repo convention for mutations: "use server" in app/actions/*.ts, zod validation, getUserId() guard. Not API routes.
Drizzle vs dbmate: Drizzle = queries only. dbmate = migrations (SQL in db/migrations). db/run.js loads .env.development.local for dbmate.
better-auth: Auth library. lib/auth.ts, lib/auth-helpers.ts
Pool adapter, 7-day session, trustedOrigins: * in dev, getUserId() throws if unauthenticated.
BYOK: "Bring Your Own Key" — user-supplied LLM key stored encrypted in llm_keys via lib/crypto.ts AES-GCM PBKDF2.
Platform Credits: Promo-code generations. promo_codes, promo_code_redemptions, llm_usage_log
Research pipeline costs 1-3 credits: base 1 + webResearch 1 + deepReasoning 1.
Tavily: Web search provider for research pipeline. app/actions/research.ts → searchWeb (advanced, maxResults 5).
PostHog: Analytics. components/posthog-provider.tsx, posthog-identify.tsx — lazy init, $pageview + identify on auth.
shadcn / base-nova: UI system. components.json, components/ui/*, lib/utils.ts cn() — neutral, CSS vars in app/globals.css.

Where to go next

Glossary is the map legend. The territory is in the lessons — each one practices a term in context.

→ Lesson 1: The 60-Second Mental Model