Extending the codebase

You bought a foundation. This document is how you build on it.

ARCHITECTURE.md gives the rules and CODE_STANDARDS.md the conventions. Neither walks you through one feature end to end, and that is what this does: one small feature, from an empty schema line to a working control, naming the real file at every step so you can diff your work against something that already exists and passes CI.

Read it once with the repository open. After that, the eight-step list at the bottom is the whole thing.

The bar this document is held to: somebody who has never seen this codebase follows it and adds a field, a service method, its authorization test, and a control — without asking a question. If you had to ask, that is a bug in this file. Please say so.

The feature we are going to build

Pin a project. An owner or admin marks a project as pinned; pinned projects sort to the top of the sidebar and the project list.

It is deliberately small, and deliberately touches every layer: a column, a migration, a permission, a service method, an authorization test, a router procedure, a page, and a component with its states. Everything larger is this, more times.

Before you write anything: the three rules that are not negotiable

They are enforced by ESLint, so you will find out at pnpm lint rather than in review — but knowing them first saves an hour.

1. The tenant comes from the session, never from the URL. ctx.orgId is resolved once, in src/trpc/init.ts. A projectId in an input is a filter; it is never proof of anything.
2. findUnique is banned inside src/server/services/. Use findFirst with organizationId in the where. A lookup by id alone returns another organization's row, and that was the single largest defect class in v1.
3. Every file under src/server/ starts with import "server-only";. It throws at build time if the module is ever pulled into a client bundle, so a leaked database call becomes a build failure instead of a shipped credential.

There is a fourth that no lint rule catches and that gates merge: every service ships an .authz.test.ts proving a member of organization B gets NOT_FOUND for an organization A resource — on read and on write. Step 4 writes one.

Step 1 — Schema

Open prisma/schema.prisma and find model Project. Add the column:

model Project {
  // …existing fields…
  pinnedAt DateTime? @map("pinned_at") @db.Timestamptz(3)

  @@index([organizationId, pinnedAt])
  @@map("project")
}

Four conventions are in play, and all four are decided in ARCHITECTURE.md rather than per model:

For a new model rather than a new column, @default(uuid(7)) on the id — v7 is time-ordered and preserves insert locality; v4 fragments the B-tree. Better Auth's own models keep their own generator; leave those alone.

Then regenerate the client:

pnpm db:generate

Reference: model Label is the smallest complete tenant-owned model in the schema — id, organizationId with its cascade, a @@unique scoped to the tenant, both timestamps, @@map. Copy its shape.

Step 2 — Migration

pnpm exec prisma migrate dev --name project_pinning

Then read the SQL it wrote, in prisma/migrations/<timestamp>_project_pinning/migration.sql. This is not ceremony:

• db push cannot create partial indexes or CHECK constraints, so several already in this schema exist only inside migration files. Never use db push against a database that matters — it is for local iteration and nothing else.
• Prisma's generator has a known habit in this repository of emitting statements nobody asked for. It cannot express the GENERATED ALWAYS tsvector columns that power search, so it reads them as ordinary and un-indexed and tries to make the database agree — emitting DROP INDEX on both search GIN indexes and ALTER COLUMN search_vector DROP DEFAULT. Delete those lines. Running them reduces every search to a sequential scan, and the DROP DEFAULT errors outright against a generated column, half-applying the migration. prisma/migrations/20260828015023_attachments_and_billing/migration.sql carries a note at the top saying exactly this. Expect it every time.

If your change needs something Prisma cannot express — a partial index, a CHECK — hand-write it into the migration file:

-- Pinned projects only. The board query filters on `pinned_at IS NOT NULL`,
-- and a partial index over the handful of pinned rows is a fraction of the
-- size of one over every project.
CREATE INDEX "project_pinned_idx" ON "project" ("organization_id", "pinned_at" DESC)
  WHERE "pinned_at" IS NOT NULL;

Commit the migration file. Buyers run migrations against real data.

Step 3 — Permission

Only if the feature needs a new one. Pinning does: it is not "update the project", because we want a member to be able to edit a project without rearranging everyone's sidebar.

Open src/lib/permissions.ts. Add the statement, then add it to each role that should hold it:

// in the statements object
project: ["create", "update", "delete", "archive", "pin"],

// owner and admin hold it; member and viewer do not.
// A pin is organization-wide furniture — one person's pin is on everyone's
// sidebar — which is the same argument that gives `member` label:create but
// not label:update.

Two things follow automatically, and they are the reason this file exists:

• useCan() in a component and permittedProcedure on the server read the same definition, so a control the interface offers is always a control the server allows.
• src/lib/permissions.test.ts pins the whole matrix. Adding a statement fails that test until you add the expectation, which is deliberate — widening viewer by accident should break the build.

A hardcoded role === "owner" in a component bypasses all of this and is a review rejection.

Step 4 — Service, and its authorization test

Write the test first. Not for TDD points: writing it first is what stops you writing a service that reads by id and only later wondering which organization it belonged to.

The service

Create or extend src/server/services/project.service.ts. Services are pure functions of (ctx, input) — that is the whole reason authorization is unit-testable here.

import "server-only";

import { TRPCError } from "@trpc/server";

import { ActivityType, recordActivity } from "@/lib/activity";
import type { OrgContext } from "@/lib/authz";
import db from "@/lib/db";

export async function setPinned(
  ctx: OrgContext,
  input: { projectId: string; pinned: boolean },
) {
  // findFirst, with the tenant in the where. Never findUnique — a foreign id
  // must be indistinguishable from a missing one.
  const project = await db.project.findFirst({
    where: { id: input.projectId, organizationId: ctx.orgId },
    select: { id: true, name: true, pinnedAt: true },
  });

  // NOT_FOUND, not FORBIDDEN. FORBIDDEN confirms the row exists and leaks the
  // id space. See docs/ARCHITECTURE.md, "Errors".
  if (!project) {
    throw new TRPCError({ code: "NOT_FOUND", message: "Project not found" });
  }

  const updated = await db.project.update({
    where: { id: project.id },
    data: { pinnedAt: input.pinned ? new Date() : null },
    select: { id: true, name: true, pinnedAt: true },
  });

  // `recordActivity` takes one object and no transaction client, and it
  // deliberately never throws — an audit write failing must not take down the
  // action that triggered it. See the note in src/lib/activity.ts.
  //
  // `projectId` is a column, not only payload: the project feed filters on
  // the column, so a row carrying it just in the JSON is invisible there.
  await recordActivity({
    type: input.pinned
      ? ActivityType.PROJECT_PINNED
      : ActivityType.PROJECT_UNPINNED,
    organizationId: ctx.orgId,
    actorId: ctx.userId,
    projectId: project.id,
    payload: { name: project.name },
  });

  return updated;
}

PROJECT_PINNED and PROJECT_UNPINNED do not exist yet — add them to ActivityType in src/lib/activity-types.ts, beside PROJECT_ARCHIVED. Every other identifier above is real, and recordActivity's single-object signature is the one in the codebase; it does not take a transaction client.

When two writes must not come apart, use db.$transaction. Pinning does not need one — recordActivity never throws, so there is nothing to roll back. Creating a comment and its notifications does: see comment.service.ts, which returns both from one interactive transaction.

What a service may and may not do:

The rule behind the right-hand column: a service that reads the session is callable from exactly one place. This one is callable from a test, a seed script, a cron job, and a CLI.

One concept per file. Past roughly 300 lines a service is doing more than one thing; split it by the resource it owns.

The authorization test

src/server/services/project.authz.test.ts. This is the release gate. Read label.authz.test.ts as the model — it is short and it proves the right things.

import { expect, it } from "vitest";

import * as projectService from "@/server/services/project.service";
import { describeDb } from "@/test/db";
import { makeOrgWithOwner, makeProjectWithBoard } from "@/test/factories";

function expectNotFound(promise: Promise<unknown>) {
  return expect(promise).rejects.toMatchObject({ code: "NOT_FOUND" });
}

describeDb("project.service pinning authorization", () => {
  it("refuses to pin another organization's project", async () => {
    const a = await makeOrgWithOwner();
    const b = await makeOrgWithOwner();
    const { project } = await makeProjectWithBoard({
      organizationId: a.organization.id,
    });

    await expectNotFound(
      projectService.setPinned(b.ctx, { projectId: project.id, pinned: true }),
    );

    // And prove nothing happened — a NOT_FOUND thrown *after* the write is
    // still a write. This is the assertion people leave out.
    const untouched = await projectService.byId(a.ctx, {
      projectId: project.id,
    });
    expect(untouched.pinnedAt).toBeNull();
  });
});

Three things about that test worth copying:

• describeDb, not describe. It truncates between tests and skips the whole suite by name when DATABASE_URL_TEST is unset, so a machine without a test database gets a clean skip rather than a red run. See src/test/db.ts.
• Factories, not fixtures. src/test/factories.ts has makeOrgWithOwner, makeMemberIn, makeProjectWithBoard, makeTask, makeLabel, and more. Each test creates what it needs; nothing is shared and mutable.
• Assert the absence of the write, not only the error. Half the value of these suites is in the second assertion.

Run it:

pnpm vitest run src/server/services/project.authz.test.ts

Step 5 — Router

src/trpc/routers/project.router.ts. A procedure does exactly four things, in this order: pick the rung, validate input, check a permission, call one service function.

export const setPinnedInput = z.object({
  projectId: z.string().min(1),
  pinned: z.boolean(),
});

// in the router object
setPinned: permittedProcedure({ project: ["pin"] })
  .input(setPinnedInput)
  .mutation(({ ctx, input }) => projectService.setPinned(ctx, input)),

Choosing the rung

Pick the highest rung that matches what you touch, and never re-derive a guarantee a lower one already gives you.

permittedProcedure({ … }) is orgProcedure with a permission check applied; permittedTaskProcedure is the same at the task rung. They are procedure factories rather than .use(requirePermission(…)) because a standalone tRPC middleware is typed against the root context and cannot see ctx.role without a cast.

Using orgProcedure and then loading the project by hand duplicates a check, and duplicated checks drift. If you find yourself doing that, you wanted projectProcedure.

Then register the router in src/trpc/routers/_app.ts if it is new.

A router may not import @/lib/db — lint-enforced. If a procedure body has an if in it, that if belongs in the service.

Reference: label.router.ts is 70 lines and shows all of it, including the one interesting case — setForTask hangs off the task rung and task:update rather than a label statement, because tagging a task is editing that task.

Step 6 — Component

Components live under src/components/<feature>/. Server Components by default; add "use client" only when the file needs state, effects, or handlers, and push the directive as far down the tree as it goes — a client boundary at the page level ships the whole page to the browser.

"use client";

import { useMutation, useQueryClient } from "@tanstack/react-query";
import { Pin, PinOff } from "lucide-react";
import { toast } from "sonner";

import { Button } from "@/components/ui/button";
import { useCan } from "@/hooks/use-can";
import { useTRPC } from "@/trpc/client";

export function PinProjectButton({
  projectId,
  pinned,
}: {
  projectId: string;
  pinned: boolean;
}) {
  const trpc = useTRPC();
  const queryClient = useQueryClient();

  // Rendering only. The server checked the same statement independently and is
  // the only thing that actually allows the action.
  const canPin = useCan({ project: ["pin"] });

  const setPinned = useMutation(
    trpc.project.setPinned.mutationOptions({
      onSuccess: () => queryClient.invalidateQueries(trpc.project.pathFilter()),
      onError: (error) => toast.error(error.message),
    }),
  );

  // The permission-denied state is absence, not a disabled button: a control
  // you can see and cannot use is a question you have to answer in support.
  if (!canPin) return null;

  return (
    <Button
      variant="ghost"
      size="icon"
      aria-label={pinned ? "Unpin project" : "Pin project"}
      disabled={setPinned.isPending}
      onClick={() => setPinned.mutate({ projectId, pinned: !pinned })}
    >
      {pinned ? <PinOff aria-hidden /> : <Pin aria-hidden />}
    </Button>
  );
}

The five states, every time

A surface is not finished until it handles empty, loading, error, success, and permission-denied. A component that only handles the happy path is not done. Counters and rollups additionally handle zero — v1 rendered NaN charts by dividing by a zero total.

Accessibility is part of the same change

Keyboard reachable, visible focus ring, labelled controls, contrast met, prefers-reduced-motion respected, and a working layout at 320px. Not a later audit. Note the aria-label on the icon-only button above, and that its icon is aria-hidden because the label already says it.

Do not hand-edit src/components/ui/

Those are generated shadcn primitives. Need a variant? Add it through the component's cva config, or wrap it in a feature component.

Step 7 — Prefetch

Data is fetched once, on the server; the client subscribes. A page that renders a spinner while the browser makes a round trip the server could have made is a defect, not a loading state.

// src/app/(app)/[orgSlug]/projects/page.tsx — Server Component
import { Suspense } from "react";
import { HydrateClient, prefetch, trpc } from "@/trpc/server";

// Required on every prefetching page. See below.
export const dynamic = "force-dynamic";

export default async function ProjectsPage() {
  prefetch(trpc.project.list.queryOptions({}));

  return (
    <HydrateClient>
      <Suspense fallback={<ProjectListSkeleton />}>
        <ProjectList />
      </Suspense>
    </HydrateClient>
  );
}

// the client component
const { data } = useSuspenseQuery(trpc.project.list.queryOptions({}));

The rules that bite, in the order they will bite you:

1. The prefetch input and the useQuery input must be identical. A different input is a different query key, the hydrated data is ignored, and the page silently refetches. This pattern's one failure mode, and it fails quietly.
2. Never await prefetch. It is fire-and-forget; HydrateClient dehydrates whatever resolved. Awaiting serializes your prefetches.
3. Subscribe with useSuspenseQuery, not useQuery, and give it a <Suspense> boundary. The query client dehydrates pending queries, so a plain useQuery renders its loading branch on the server while the client hydrates with data that already arrived — a hydration mismatch React only reports in development.
4. export const dynamic = "force-dynamic" is not optional on a prefetching page. createTRPCContext reads headers() inside a promise that escapes the render pass, so Next cannot attribute the dynamic access in time, the route stays a static-prerender candidate, and the build fails with a redacted Error: redacted naming no cause and no file. If a build fails that way, this is why.
5. Loading is the <Suspense fallback>; the error state is the segment's error.tsx. A component that suspends must not also carry an isPending branch — it is unreachable and it drifts.
6. Refresh RSC-prefetched data with router.refresh(), not invalidateQueries. Invalidating a useSuspenseQuery re-suspends its boundary, which unmounts the component holding the observer, which cancels the refetch the invalidation just started. invalidateQueries stays correct for queries the client owns outright.
7. Format dates through src/lib/format.ts. toLocaleDateString(undefined, …) uses the runtime's locale and timezone, which differ between server and browser; the mismatch makes React discard the tree.

Working reference: src/app/(marketing)/status/page.tsx plus src/components/system/status-card.tsx is the smallest complete example in the repository. Copy that shape.

Step 8 — Verify

pnpm lint && pnpm typecheck && pnpm test && pnpm build

All four run in CI on every push and pull request, against a Postgres service container — no account and no API key, so a fork runs green on the first try.

If you touched anything a user clicks, also run the browser suite. It is the only gate that reads the markup, and it is the only one that catches a panel that moved behind a tab:

pnpm test:e2e

That is not hypothetical. A UI pass in this repository moved the task details panel behind tabs, ran the other four gates, and shipped two broken specs to main for a day. The rule it earned: a change that moves UI is not exempt from pnpm test:e2e.

The eight steps, as a checklist

1. Schema — model or column in prisma/schema.prisma, with organizationId and an index leading on it. pnpm db:generate.
2. Migration — prisma migrate dev, then read the SQL. Hand-write anything Prisma cannot express. Commit it.
3. Permission — a statement in src/lib/permissions.ts, if the feature needs one.
4. Service + authz test — (ctx, input), every query filtered by ctx.orgId, findFirst never findUnique. Write the test first.
5. Router — the highest matching rung, Zod input, permission, one service call. Register it in _app.ts.
6. Component — under src/components/<feature>/, gated with useCan(), all five states, accessible, 320px.
7. Prefetch — the RSC calls prefetch(...) with the same input, wrapped in <HydrateClient>, dynamic = "force-dynamic".
8. Verify — four gates, plus pnpm test:e2e if you moved any UI.

Things that will trip you up

Collected because each of these cost somebody an hour in this repository.

Where to look when this document runs out

The codebase was written against a set of published agent skills — Better Auth, Postgres, and the UI system. They belong to their authors rather than to us, so they are not redistributed here; skills-lock.json is committed and names each one — its upstream repository, its path, and a hash of the pinned revision — so the exact set can be re-fetched into .agents/skills/ with the skills CLI. pnpm dlx @tanstack/intent@latest list shows the tRPC and TanStack ones. Load the relevant one before a substantial change; the table in CODE_STANDARDS.md says which.

Use pnpm dlx, never npx. npm's arborist crashes on pnpm's symlinked node_modules in this repository.