Pattern

Consistency is the foundation. Every feature follows the same shape; every file has a canonical role. New code that matches these patterns is reviewable in minutes; new code that doesn't is friction.

Naming

Files and folders

• Components, files — kebab-case (button.tsx, user-profile.tsx).
• Routes — kebab-case segments (/user-profile, /sign-in).
• Hooks — use- prefix (use-leads.ts).
• Types — PascalCase identifiers (interfaces, type aliases, enums).
• Constants — UPPER_SNAKE_CASE for primitives, camelCase for object literals.

Identifiers in code

• Components — PascalCase (export function UserCard()).
• Functions — camelCase (formatCurrency).
• Variables — camelCase (const userData = ...).
• Constants — UPPER_SNAKE_CASE (const API_BASE_URL = "...").
• Types and interfaces — PascalCase (interface UserData, type ApiResponse).

Database and API

• Tables — snake_case (user_profiles).
• API routes — kebab-case (/api/user-profile).
• Environment variables — SCREAMING_SNAKE_CASE (DATABASE_URL).

Function patterns

Use function declarations for components, API route handlers, and exported functions — they hoist and produce better stack traces. Use arrow functions for short utility callbacks.

Copy// utility — arrow is fine
const formatPrice = (amount: number) =>
  new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(amount)
 
// component — function declaration
export function UserProfile({ userId }: Props) {
  const { user, loading } = useUser(userId)
  if (loading) return <Skeleton />
  return <Card>{user.name}</Card>
}

Server actions and data fetching

• Mutations live in actions.ts with "use server" at the top.
• Reads live in queries.ts. Pure server functions, no "use server" needed unless called from client.
• Every server action runs the 5-step flow: auth → tenant → permission → validate → execute + revalidate.
• Server actions return ActionResponse<T> from @/lib/action-response.
• Server components fetch via queries.ts and pass data to client components as props.

Component hierarchy

Mirror pattern

Every URL produces two directories — one in app/ (routing, layouts, page.tsx), one in components/<feature>/ (everything else). Read the architecture doc for the full mapping.

src/app/[lang]/s/[subdomain]/(school-dashboard)/students/page.tsx
  → imports from src/components/school-dashboard/listings/students/content.tsx

Standard file patterns per feature

The full canonical content per file lives in the linked doc — this page is the index.

Multi-tenant rules

• Every business model carries schoolId.
• Every database query is scoped by schoolId. Missing schoolId = data leak.
• getTenantContext() is the source of truth for the current schoolId.
• Subdomain detection happens in middleware; tenant context resolves it.

See Multi-Tenancy for the full architecture.

TypeScript

• Strict mode on. No any, no as any.
• import type for type-only imports.
• Derive types from Zod via z.infer. Derive Prisma row types via Prisma.XxxGetPayload.
• Discriminated unions for state machines (ActionResponse<T>, wizard step state).
• enum only when the values cross runtime boundaries; otherwise prefer string literal unions.

Styling

• Tailwind 4 with OKLCH tokens.
• Semantic HTML — no hardcoded text-* / font-* in feature code; trust the renderer.
• Theme-aware tokens only — text-foreground, bg-card, border-border. No hex.
• Logical properties for RTL — ms-, me-, ps-, pe-, start-, end-. Never ml-, pl-, left-, right-.

Error handling

• Server actions return errorCode, never English strings. The dictionary maps them on the client.
• Never throw to the client. Catch in the action and return a structured response.
• error.tsx boundaries handle component-tree exceptions.
• console.error for server-side diagnostics; never console.log in shipped code.

Performance

• Server components by default; "use client" only when needed.
• Parallelise independent awaits with Promise.all.
• revalidatePath after mutations.
• Wrap expensive computations in useMemo; wrap stable callbacks in useCallback only when measured.
• Lumos where possible — Suspense boundaries inside server components.

Adoption

When adding new code:

1. Pick the closest existing feature directory and copy its shape.
2. Match the naming and file set exactly.
3. Resist the urge to invent a new file (utils.ts, helpers.ts); use the canonical names.
4. If something genuinely doesn't fit, add a note in README.md so the next person knows why.