# Core Concepts

## Use The Platform

Verge Kit prefers the framework and platform tools already in the project.

Use Astro pages, API routes, Actions, middleware, and config before adding a new
local abstraction. Add helpers only when they remove repeated code or protect a
real boundary.

## D1 First

D1 is the supported runtime database.

Use the local `src/db` modules from app code. Do not import `drizzle-orm/d1`
directly in routes, pages, actions, or components.

This keeps future Hyperdrive PostgreSQL or MySQL work isolated to the database
adapter layer. The proof modules for those targets are test-only; runtime code
still rejects PostgreSQL and MySQL target names.

## Config Has A Boundary

Use `src/config` for source-level app defaults and auth policy that app code
imports directly. App identity, default authenticated navigation, protected
routes, app roles, permission values, and banned-session copy belong there.

Use `wrangler.jsonc` as the committed source of truth for non-secret Worker
runtime values. Typical values include `EMAIL_PROVIDER`, `EMAIL_FROM`,
`EMAIL_REPLY_TO`, `BETTER_AUTH_URL`, and `MAILGUN_DOMAIN`.

Use `.dev.vars` for local secret values and local-only overrides. Use Wrangler
secrets for deployed secret values. Do not commit API keys, auth secrets, or
provider credentials in `wrangler.jsonc`.

## Server First

Keep auth, database writes, email, and validation on the server.

Use client JavaScript only where it improves a specific interaction.

## Validate At The Boundary

Use Zod for request bodies, form input, and action input.

Keep validation close to the route or action that receives external data.

## Middleware Owns Auth State

Middleware creates the Better Auth instance, reads the session, and writes:

- `Astro.locals.user`
- `Astro.locals.session`
- `Astro.locals.isAuthenticated`

Pages and routes should read from locals instead of reimplementing session
lookup.

## Routes Are Public By Default

Middleware loads auth state for every request, but route protection is opt-in.
Use `src/config/auth.ts` when pages or API namespaces should be consistently
protected by middleware. Use route-local checks when a page or API handler needs
custom redirect or JSON `401` behavior.

Keep Better Auth endpoints under `/api/auth` public so sign in, sign up,
verification, reset, session, callback, and sign-out requests can reach Better
Auth before a user has a session.

## Roles Are App Policy

The Better Auth admin plugin is installed and configured with `admin`,
`moderator`, `user`, and `banned` roles. App permissions live in
`src/config/auth.ts`, and local checks should use the helpers in
`src/auth/permissions.ts`.

## Email Is A Provider

Auth email is rendered once and sent through a provider.

Local development can use `console`. Workers deployments should use Cloudflare
Email, Resend, Mailgun, or another fetch/binding-based provider.

Use `sendEmail` directly for custom transactional messages. Use
`createAuthEmailSenderFromEnv` for Better Auth verification and reset flows so
auth email templates and `EMAIL_FROM` handling stay centralized.

## Initialization Is Operational

Run migrations before seeding users. `npm run init:admin` creates a verified
Better Auth user directly in D1 through Wrangler, selecting local or remote D1
from `BETTER_AUTH_URL` unless `--local` or `--remote` is passed.

## Keep The Boilerplate Small

Verge Kit does not include uploads, media processing, full admin CRUD screens,
analytics, queues, workflows, or production PostgreSQL/MySQL runtime support yet.

Add those when an application needs them.