Add Backend

Add a backend (resources, data sources & presets)

The app is backend-agnostic by design: it reaches data and auth only through

two seams, so adding a resource, swapping one resource's data source, or

re-pointing the whole app at a different backend are all localized operations.

Routing rule: use add-backend whenever a screen needs its own data (a new

entity/table, or a different backend); use add-component when composing UI on top

of data that already exists.

| Concern | Seam | Default preset | Swap point |

| --- | --- | --- | --- |

| Business data (resources) | Repository<T, TInput> (@/infra/data/repository) | Postgres via drizzleRepository; in-memory when no DB | each resource's server.ts binding |

| Auth (server) | AuthProvider (@/lib/auth-provider) | better-auth (betterAuthProvider) | the authProvider binding |

| Auth (browser) | @/lib/auth-client | better-auth React client | reimplement that one file |

Zero-config (bun dev, no DATABASE_URL) already runs on in-memory presets, so you

can build UI before wiring a real backend. Full guides: docs/data-adapters.md,

docs/backends.md.

Backend presets — ready-to-run templates

Six runnable backend templates ship in this skill's templates/<preset>/ (generated

from the repo's backends/ source and contract-tested — templates/<preset>/README.md

+ a shared CONTRACT.md). Pick one as the project's backend; each connects to the

dashboard frontend through the two seams above — **no page, query, table, or form

changes** — and each is independently verified.

| Preset | Stack | Frontend wiring | Reference |

| --- | --- | --- | --- |

| tanstack-drizzle-betterauth | TanStack Start server fns + Drizzle + better-auth (in-process — the default) | none — it *is* the scaffold | references/tanstack-drizzle-betterauth.md |

| hono-drizzle-betterauth | Hono + Drizzle + better-auth (standalone TS service) | restRepository + remoteBetterAuthProvider | references/hono-drizzle-betterauth.md |

| hono-prisma-betterauth | Hono + Prisma + better-auth (standalone TS service) | restRepository + remoteBetterAuthProvider (same as Drizzle) | references/hono-prisma-betterauth.md |

| hono-drizzle-authjs | Hono + Drizzle + Auth.js / NextAuth v5 (standalone TS service) | restRepository + remoteAuthjsProvider + authjs client | references/hono-drizzle-authjs.md |

| fastapi-sqlalchemy-jwt | FastAPI + SQLAlchemy + JWT (standalone Python service) | restRepository + externalJwtAuthProvider | references/fastapi-sqlalchemy-jwt.md |

| supabase | Supabase Postgres + Auth (BaaS — SQL + config) | supabaseRepository + Supabase AuthProvider (copy-ready) | references/supabase.md |

The HTTP-API presets (the hono-* services + fastapi) all speak one shared wire

contract, so their frontend auth providers ship pre-wired and typechecked in the base

under src/lib/auth-providers/ (externalJwtAuthProvider, remoteBetterAuthProvider,

remoteAuthjsProvider) — activating is a one-line swap. Supabase needs the Supabase SDKs,

so its wiring ships as copy-ready files in templates/supabase/frontend-wiring/.

> Stack matrix: framework (TanStack / Hono / FastAPI / Supabase) × ORM (Drizzle / Prisma /

> SQLAlchemy) × auth (better-auth / Auth.js / custom-JWT / Supabase). The presets are the

> idiomatic, verified combinations — not a blind cartesian product.

To stand up a preset:

• Read references/<preset>.md (Add it / Foundation / Invariants / Verify).
• Copy the template out as the service (cp -R templates/<preset> <dest>); follow its

README to run it (zero-config: SQLite + a dev secret, one install + one run command).

• Wire the frontend: bind the resource's server.ts to the preset's Repository

adapter (§2) and point authProvider at the preset's AuthProvider (§3).

• Verify end-to-end (the reference's Verify block).

The numbered sections below are the building blocks these presets compose: add a resource

(§1), bind/swap a data source (§2), swap the auth preset (§3).

1. Add a CRUD resource

The CRUD table is the base archetype. products is the canonical reference;

orders is a generated example.

• Generate the vertical (table + feature + route + sidebar entry, auto-formatted):

   bun run create-resource <plural-name>   # e.g. customers

This creates src/features/<name>/{schema,server,demo-data,queries,columns,config}.ts(x)

and the route src/routes/_app/<name>.tsx, appends a Drizzle table to

src/db/schema.ts, and inserts a sidebar item. Like products, the generated

server.ts binds drizzleRepository when DATABASE_URL is set and falls back

to memoryRepository over demo-data.ts otherwise — so the new resource runs

under zero-config bun dev (no database) before you ever migrate.

• Customise the fields in src/db/schema.ts (the appended pgTable) and in

src/features/<name>/schema.ts (the zod input / form / list-params schemas).

Keep numeric form fields non-coercing in *FormSchema (input must match the

form value type); the server *InputSchema may coerce. Filter params that can

be numeric must use z.coerce.string() (the router JSON-parses search params).

• Adjust columns.tsx (cells, sortable columns), config.ts (filters,

search placeholder), the server.ts repository config (searchColumns /

sortColumns / filterColumns on the drizzle branch, and the matching

searchFields / sortFields / filterFields on the memory branch), and the

seed rows in demo-data.ts.

• Migrate (only on Postgres — zero-config dev needs no DB):

bun run db:generate && bun run db:migrate.

• Verify: bun run typecheck && bun run check && bun run test, then open

/<name> (it lists the demo-data.ts rows with no DB).

Resource invariants (must hold)

• Every server-fn handler calls requireUser() first and validates input via

.validator((data) => zodSchema.parse(data)) (an arrow wrapper, not a bare

zodSchema.parse method reference).

• List state lives in the URL (validateSearch + useTableSearch); never local

useState.

• Mutations show a toast and invalidate the resource's query keys; deletes go

through useConfirm().

• The repository binding lives in server.ts (server-only): drizzleRepository

from @/infra/data/drizzle-repository behind hasDatabase, with a

memoryRepository fallback for zero-config dev — never imported from a client

component.

• The page wraps DataTable in a full-height flex column —

<div className="flex h-full flex-col gap-6"> with the header as shrink-0 —

so the pagination bar pins to the bottom (the shell sizes each page to the

viewport). The generator emits this; keep it.

2. Bind / swap a resource's data source

Every page archetype is written against Repository<T, TInput>

(src/infra/data/repository.ts), so swapping a resource's backend touches only its

server.ts binding — queries.ts, columns.tsx, the table/detail/form, and the

route do not change.

Adapters:

• Drizzle (Postgres) — drizzleRepository(table, config) from

@/infra/data/drizzle-repository (import directly; server-only). Backs

products/orders.

• In-memory — memoryRepository(seed, config). The zero-config default; backs

every demo when DATABASE_URL is unset.

• REST — restRepository({ baseUrl, path, map, … }) from @/infra/data. Backs

posts (jsonplaceholder). Defaults target json-server

(_page/_limit/_sort/_order/q + x-total-count); override params /

totalHeader for other shapes.

• GraphQL — graphqlRepository({ endpoint, map, operations }) from

@/infra/data. Each op supplies a document + variable builder + extractor.

To back a resource with REST/GraphQL (no DB table needed):

• Define the resource's type + zod schemas.
• In server.ts, build the repository with the right adapter and a map from the

raw API record to your type; wrap each op in a createServerFn handler that

calls requireUser() (the fetch stays server-side, so API keys never reach the

client):

   export const widgetsRepository = restRepository<Widget, WidgetInput>({
     baseUrl: process.env.WIDGETS_API_URL!,
     path: "/widgets",
     map: (raw) => ({ ...raw }),
   });

• Map the resource's flat list params to the repository's filters

(toListParams). Numeric filter params → z.coerce.string().

Data-source invariants

• Adapters run only inside server fns. The @/infra/data barrel is

isomorphic-safe (no @/db); the Drizzle adapter is imported from its own path.

• Always provide a unit test mocking the transport (fetch / db) — see

rest-repository.test.ts, graphql-repository.test.ts, drizzle-repository.test.ts.

3. Swap the whole-app backend + auth preset

Two classes of data, two different rules:

• Business data (your resources) — swap per resource via the Repository

adapter in server.ts (section 2).

• Platform data (users/sessions, later RBAC) — owned by the *auth preset*; swap

it via AuthProvider (server) + @/lib/auth-client (browser).

Implement AuthProvider and point authProvider at it. The contract:

export interface AuthProvider {
  getSession(headers: Headers): Promise<AuthSession | null>; // AuthSession = { user: { id; email; name; image? } }
  handler(request: Request): Promise<Response>;              // serves /api/auth/*
}

> For the bundled presets these now ship as real files — activate, don't hand-write.

> src/lib/auth-providers/external-jwt.ts (externalJwtAuthProvider, custom-JWT like the

> FastAPI preset) and src/lib/auth-providers/remote-better-auth.ts

> (remoteBetterAuthProvider, remote better-auth like the Hono preset) are pre-wired and

> typechecked; the Supabase provider is copy-ready in

> templates/supabase/frontend-wiring/auth-provider.ts. The examples below show the shape

> behind those files.

Example: Supabase auth provider

// src/lib/auth-provider.ts (replace betterAuthProvider). bun add @supabase/ssr
import { createServerClient, parseCookieHeader } from "@supabase/ssr";

export const supabaseAuthProvider: AuthProvider = {
  async getSession(headers) {
    const cookies = parseCookieHeader(headers.get("cookie") ?? "");
    const supabase = createServerClient(
      process.env.SUPABASE_URL!,
      process.env.SUPABASE_ANON_KEY!,
      { cookies: { getAll: () => cookies } },
    );
    const { data } = await supabase.auth.getUser();
    if (!data.user) return null;
    return {
      user: {
        id: data.user.id,
        email: data.user.email ?? "",
        name: data.user.user_metadata?.name ?? data.user.email ?? "",
      },
    };
  },
  // Supabase auth runs client-side; no /api/auth/* routes to serve.
  handler: async () => new Response("Not found", { status: 404 }),
};

export const authProvider: AuthProvider = supabaseAuthProvider;

Then reimplement @/lib/auth-client with Supabase's browser client, exporting the

same signIn / signUp / signOut / useSession surface the auth pages use.

Example: external-API (JWT) auth provider

// src/lib/auth-provider.ts (replace betterAuthProvider)
export const externalApiAuthProvider: AuthProvider = {
  async getSession(headers) {
    const cookie = headers.get("cookie") ?? "";
    const token = /(?:^|;\s*)session=([^;]+)/.exec(cookie)?.[1];
    if (!token) return null;
    const res = await fetch(`${process.env.AUTH_API_URL}/me`, {
      headers: { authorization: `Bearer ${token}` },
    });
    if (!res.ok) return null;
    const u = await res.json();
    return { user: { id: String(u.id), email: u.email, name: u.name } };
  },
  // Proxy login/logout to the upstream API (set the session cookie on success).
  handler: async (request) => {
    const hasBody = request.method !== "GET" && request.method !== "HEAD";
    return fetch(
      `${process.env.AUTH_API_URL}/auth${new URL(request.url).pathname.replace("/api/auth", "")}`,
      {
        method: request.method,
        headers: request.headers,
        // Buffer the body before forwarding. Passing the raw `request.body`
        // ReadableStream to Node/undici's fetch requires `duplex: "half"` and
        // still can't be retried; reading it to a string sidesteps both.
        body: hasBody ? await request.text() : undefined,
      },
    );
  },
};

export const authProvider: AuthProvider = externalApiAuthProvider;

A different SQL engine (MySQL/SQLite/Turso) needs no preset swap — Drizzle supports

them; see docs/backends.md for the files to touch.

Preset invariants

• The app reaches auth ONLY via authProvider (server) and @/lib/auth-client

(browser). Never call a specific auth SDK from a route or component.

• getSession returns the normalized AuthSession ({ user: { id, email, name } })

so requireUser, the _app guard, and the route context are backend-neutral.

• Keep the server seam server-only: auth-provider.ts may import DB/SDK clients, so

it must only be reached from require-user, the api route, and the dynamic import

in auth-server — never statically from a client-reachable module.

Verify

bun run typecheck && bun run check && bun run test (and bun run build for an

auth-preset swap), then bun run dev: open /<name> and confirm

list/paginate/filter/search work; for an auth swap, an unauthenticated request to

/ redirects to /login, sign-in works, and a protected page loads its data.