Your favorite shift management application!
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project
BetterShift is a self-hosted shift-planning app: Next.js 16 (App Router) + React 19, SQLite via Drizzle, better-auth, next-intl, Tailwind v4 with shadcn/ui primitives. It builds to output: "standalone" and ships as a Docker image.
Commands
npm run dev # Dev server
npm run build # Production build — this is also the type check used in CI
npx tsc --noEmit # Type check alone, much faster than a build
npm run lint # ESLint (next core-web-vitals + typescript + @tanstack/query)
npm run i18n # Translation check (see i18n below)
npm test # lint + build + i18n — the gate before committing
npm run test:ci # adds db:generate + db:migrate, mirrors .github/workflows/pr-checks.yml
npm run db:generate # Create a migration after editing lib/db/schema.ts
npm run db:migrate # Apply migrations
npm run db:studio # Drizzle Studio
There is no unit-test framework here — "tests" means the lint/build/i18n pipeline. When something fails, run the individual script rather than all of npm test.
npm run release:patch|minor|major bumps the version and pushes the tag; the release workflow builds the image from it.
Workflow
Commits follow Conventional Commits (type(scope): summary, e.g. feat(ui):, fix(auth):, chore:, perf:; ! before the colon for breaking changes). scripts/changelog.sh, called from .github/workflows/release.yml, builds the release changelog straight from git log --pretty=%s --no-merges between tags — grouped by that prefix, with refactor|ci|style|test|build dropped as internal-only.
Architecture
Request flow
proxy.ts → app/api/**/route.ts → getSessionUser(headers) → permission check → db → NextResponse.json()
component → hooks/use*.ts (TanStack Query) → fetch("/api/…") → cache keyed via lib/query-keys.ts
proxy.ts is the middleware — Next.js 16 renamed middleware.ts to proxy.ts and the export is proxy. It runs on almost every path (see config.matcher) and executes four stages in order:
- DB health check, cached in-module for 10s (5s while unhealthy) with a 2s timeout. Unhealthy redirects everything to
/system-unavailable; only/api/health,/api/version,/api/releasesandmanifest.jsonare exempt. /share/token/[token]— rate limits, validates the token, writes the grant into a cookie, records usage and audit-logs it, then redirects to/?id=<calendarId>.- Auth guard — presence check of the better-auth session cookie only; actual session validation happens in the route handlers. Without a cookie it falls through to guest access or redirects to
/login?returnUrl=…. - Security headers + CSP on the response.
Anything added here affects every request, so weigh cost and check the exempt list.
instrumentation.ts runs once per server start (Node runtime only): it preloads the version and starts autoSyncService. That service is an in-process setTimeout scheduler holding a job per external sync — not a cron job, and not shared across replicas.
Frontend shape
The product is essentially one client page. app/page.tsx pulls data hooks (useCalendars, useShifts, usePresets, useNotes, useExternalSync), pairs them with action hooks (useShiftActions, useNoteActions) and dialog state (useDialogStates), and renders every sheet and dialog through components/dialog-manager.tsx — add new dialogs there rather than inline. Real routes exist only for /login, /register, /profile, /admin/* and /system-unavailable.
View preferences (shifts per day, sorting, note visibility, day highlighting) come from hooks/useViewSettings.ts and exist on two levels. The personal view is stored per account in userPreferences via /api/user/view-settings; guests and AUTH_ENABLED=false keep it in localStorage, and a signed-in account without a stored view gets the device's values once. A calendar can pin its own view in calendars.viewSettings (null = off), which replaces the personal view as a whole for everyone with access; the stamp-bar toggle always stays personal, and compare mode always uses the personal view. lib/view-settings.ts holds the types, defaults and the sanitiser shared by routes and client.
Calendar access model
Two independent questions, easy to conflate:
May the user do X? resolveCalendarAccess() in lib/auth/permissions.ts resolves, in priority order: owner → calendarShares row → access-token cookie → calendars.guestBundleId. There's no fixed read/write/admin ladder — every non-owner branch resolves to a permission bundle (calendarPermissionBundles, an owner-defined per-calendar set of ticked capabilities; catalog, dependencies and defaults live in lib/permission-bundles.ts, full design in docs/PERMISSIONS.md). The guest-bundle step is not unconditional for a signed-in user: it applies only when a userCalendarSubscriptions row with status: "subscribed" exists, so a public calendar someone dismissed grants them nothing until they re-subscribe. Guests reach guestBundleId without that check. Whatever the resolved bundle contains, a token or guest-bundle source additionally has manageShares/manageGuestAccess/manageCalendarSettings/manageExternalSync/deleteSyncLogs filtered out — the hard guest lockout (GUEST_INELIGIBLE/isGuestEligible() in lib/permission-bundles.ts), re-enforced here regardless of what a bundle's saved contents claim. Call getCalendarAccess(userId, calendarId) once per request for can(capability) / canOwned(own, any, createdBy); hasCapability() / hasOwnedCapability() are single-check wrappers around it. canOwned() treats a resource with no known creator (legacy data, a deleted user, an anonymous guest's entry) as owned by anyone holding the matching own-capability. In routes, canViewCalendar (any access at all) and canDeleteCalendar (owner-only) remain as wrappers — there's no canEditCalendar/canManageCalendar anymore, since a coarse level can't express a specific capability or an own/any check; call hasCapability()/hasOwnedCapability() for the capability the action actually needs.
Does the calendar show up in their list? getUserAccessibleCalendars() applies userCalendarSubscriptions across the board, not just on the guest-bundle branch above. Shared and publicly visible calendars can be dismissed by a user (status: "dismissed"), the calendar-discovery sheet lets them re-subscribe, and owned calendars can never be hidden. A capability check alone therefore does not tell you whether a calendar is visible.
AUTH_ENABLED=false short-circuits both: every calendar becomes owner for everyone. Gate on isAuthEnabled() / allowGuestAccess() from lib/auth/feature-flags.ts rather than assuming a session exists.
Access tokens (calendarAccessTokens) are shareable links, each carrying a bundleId (guest-eligible bundles only — checked at assignment time). lib/auth/token-auth.ts validates them and stores grants in a cookie that both the middleware and the API routes read back.
Admin
Two separate permission layers, deliberately:
lib/auth/access-control.tsonly exists to make better-auth's admin plugin accept theadminandsuperadminroles; both get all plugin permissions.lib/auth/admin.tsholds the actual rules (canBanUser,canChangeUserRole,canResetPassword,canDeleteAuditLogs, …) and is what routes underapp/api/admin/**must check.
The first registered user is promoted to superadmin (lib/auth/first-user.ts).
Instance announcements (announcements) are admin-authored notices shown on the auth pages and above the calendar. lib/announcement-status.ts holds the pure, database-free pieces — the tone and placement catalogs, getAnnouncementStatus() and isVisibleNow(), the named JS expression of the enabled-flag-and-window rule that getVisibleAnnouncements()'s SQL where clause separately re-implements — so client components can import them without pulling lib/db into the browser bundle; lib/announcements.ts re-exports those and adds sanitizeAnnouncementInput() and the getVisibleAnnouncements() query itself. GET /api/announcements is public (listed in proxy.ts) and returns only what is visible right now; the admin CRUD routes under app/api/admin/announcements/** gate on canManageSystemSettings. Dismissal is per browser in localStorage, never server state.
External calendar sync
syncExternalCalendar() in app/api/external-syncs/[id]/sync/route.ts is the single implementation, exported so the auto-sync service reuses it; the route handler is just the manual entry point. It normalises webcal://, fetches with a 10s abort, parses with ical.js, expands recurrences, splits multi-day events, and diffs against existing shifts using a fingerprint (createEventFingerprint / needsUpdate in lib/external-calendar-utils.ts) so unchanged events are not rewritten. Every run appends a syncLogs row with created/updated/deleted counts, which is what drives the sync notification dialog.
Shifts produced this way carry syncedFromExternal and an externalSyncId and are read-only — check that flag before permitting an edit or delete.
Data layer
lib/db/schema.ts holds all tables and relations in one file; schema changes require db:generate plus db:migrate, and migrations under drizzle/ are committed. lib/db/index.ts opens the SQLite file (DATABASE_URL, default ./data/sqlite.db) at import time and creates the directory if missing — importing db from anything Edge-runtime will fail.
Client-side, all cache keys come from lib/query-keys.ts; an ad-hoc key array silently breaks invalidation. Mutations are optimistic and follow onMutate (cancel → snapshot → patch cache) / onError (roll back → toast) / onSettled (invalidate). hooks/useShifts.ts is the reference; copy its shape for new mutations.
Custom fields. A calendar can define extra typed fields (calendarCustomFields) whose values hang off shifts and presets in two child tables mirroring the time-segment tables. lib/custom-fields.ts holds the type catalog, serialisation and validation shared by routes and client; lib/shift-custom-fields.ts holds the DB helpers. Values are not separate resources — they travel as customFields: Record<key, value> on the existing shift and preset payloads, carried by the shift PUT and preset PATCH handlers. A preset's values pre-fill a shift client-side in applyPreset() for a caller with createShift; the stampPreset-only path reads them server-side from the preset row instead, because that path never trusts the request body.
i18n
messages/de.json is the source of truth, en, es, fr, it and cs are mirrors. scripts/i18n-checks.ts flattens every locale to dot keys, greps app/, components/, hooks/, lib/ for usages, and reports keys used but missing from de.json, keys missing from other locales, and unused keys. It runs in CI, so add the German key first, then translate. Locale resolution is server-side in lib/i18n.ts: NEXT_LOCALE cookie → Accept-Language → DEFAULT_LOCALE. A new locale also needs an entry in lib/locales.ts, including its date-fns locale — an unknown DEFAULT_LOCALE throws at startup.
UI strings and log output are product text in the project's locales; code comments and doc blocks stay English.
Conventions worth knowing
- Dates are local
YYYY-MM-DDstrings and must never go through a UTC conversion. UseformatDateToLocal()/parseLocalDate()fromlib/date-utils.ts, andgetDateLocale()fromlib/locales.tsfordate-fnsoutput. - Rate limiting:
rateLimit(request, userId, "<type>")returns aNextResponsewhen the limit is hit — return it immediately, otherwise continue. The valid types and their defaults are the keys of theconfigobject inlib/rate-limiter.ts, each overridable per env var. Client-side, handle them withisRateLimitError()/handleRateLimitError(). - Audit logging goes through
logUserAction/logAdminAction/logSecurityEvent/logSystemEventinlib/audit-log.ts. Metadata is a discriminated union — add an interface for a new action instead of passing a loose object. - UI primitives in
components/ui/are generated shadcn ("new-york") components and are not hand-edited. Sheets and dialogs composecomponents/ui/base-sheet.tsx; form logic belongs in a hook (useShiftForm,useDirtyState), not the component.
Reference
docs/AUTH_SETUP.md, docs/PERMISSIONS.md, docs/ADMIN_PANEL.md, docs/ENABLING_AUTH.md, docs/UPGRADING.md, docs/PR_PREVIEWS.md; .env.example documents every environment variable with its default.
This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.
This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.