Skip to content

Your favorite shift management application!

chore: Update Copilot instructions for clarity and structure

panteLxca1a4f42c9fb
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 1672b68..968c839 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,463 +1,158 @@
-# BetterShift AI Coding Instructions
+# BetterShift - Copilot Instructions
-## Project Overview
+## Architecture Overview
-**BetterShift** is a modern shift management web application for variable work schedules. Users manage unlimited calendars with one-click shift toggles, external calendar sync (iCal/Google/Outlook), calendar sharing with granular permissions, reusable presets, and multi-language support. Built with **Next.js 16 (App Router)**, **React 19**, **SQLite + Drizzle ORM**, and **Better Auth**.
+BetterShift is a **Next.js 16** self-hosted shift management app using:
-## Tech Stack Quick Reference
+- **Database**: SQLite with Drizzle ORM (`lib/db/schema.ts`)
+- **Auth**: better-auth with multi-provider support (`lib/auth.ts`, `lib/auth/`)
+- **State**: TanStack Query for server state (`hooks/use*.ts`)
+- **UI**: Radix primitives + shadcn/ui (`components/ui/`)
+- **i18n**: next-intl with `de.json` as source of truth (`messages/`)
-- **Frontend**: Next.js 16 (App Router), React 19, TypeScript 5 (strict mode)
-- **UI**: Tailwind CSS 4, shadcn/ui (Radix UI primitives), Lucide icons, Motion animations
-- **Database**: SQLite (via better-sqlite3) + Drizzle ORM 0.44
-- **Auth**: Better Auth 1.4 (enabled by default) - email/password + OAuth (Google/GitHub/Discord) + custom OIDC
-- **i18n**: next-intl 4.5 - Supported locales: `en`, `de`, `it`
-- **Data Fetching**: @tanstack/react-query 5 - Polling, caching, optimistic updates
-- **Key Libraries**: date-fns, ical.js, jsPDF, @dnd-kit, recharts, sonner (toasts)
+### Key Data Flow
-## Architecture Patterns
-
-### 1. Server Components First
-
-- **Default**: All components under `app/` are Server Components unless marked with `"use client"`
-- **Client boundaries**: Components in `/components` are `"use client"` by default (interactive UI)
-- API routes are in `app/api/**` with `GET/POST/PUT/PATCH/DELETE` exports
-
-### 2. Database Layer
-
-**Location**: [`lib/db/schema.ts`](lib/db/schema.ts)
-
-**Key tables**:
-
-- `user`, `session`, `account`, `verification` (Better Auth tables)
-- `calendars` - has `ownerId` (nullable), `guestPermission` (`none`/`read`/`write`)
-- `calendarShares` - many-to-many with permissions (`owner`/`admin`/`write`/`read`)
-- `shifts`, `presets`, `notes`, `externalSyncs`, `syncLogs`
-
-**Migrations**: Use Drizzle Kit commands:
-
-```bash
-npm run db:generate # Generate SQL from schema changes
-npm run db:migrate # Apply migrations to database
+```
+API Route → getSessionUser() → getUserCalendarPermission() → db query → Response
+Component → useQuery hook → fetch('/api/...') → TanStack Query cache
```
-### 3. Authentication & Permissions
-
-**Feature flag**: Auth is **enabled by default** (`AUTH_ENABLED=true`) for better security. Can be disabled by setting `AUTH_ENABLED=false`.
-
-**Configuration**: [`lib/auth.ts`](lib/auth.ts), [`lib/auth/env.ts`](lib/auth/env.ts), [`lib/public-config.ts`](lib/public-config.ts)
-
-#### Hybrid Approach: When to Use Better Auth vs. Custom Code
-
-**✅ Use Better Auth for:**
-
-- **Authentication**: Login, logout, session management, token handling
-- **OAuth**: Google, GitHub, Discord, custom OIDC integration
-- **Admin Operations**: `auth.api.banUser()`, `auth.api.setUserPassword()`, `auth.api.removeUser()`
-- **Access Control Config**: Role registration (`lib/auth/access-control.ts`) - only for Better Auth internal use
-
-**✅ Use Custom Code for:**
-
-- **Permission Checks**: All `canEditUser()`, `canDeleteUser()`, `canBanUser()` functions in `lib/auth/admin.ts`
-- **Calendar Permissions**: `owner > admin > write > read` hierarchy in `lib/auth/permissions.ts`
-- **Admin UI Logic**: User management, filtering, sorting (direct DB queries)
-- **Audit Logging**: App-specific event tracking in `lib/audit-log.ts`
-
-**Why**: Better Auth handles auth operations (with automatic session revocation, BCrypt hashing, etc.), while custom code provides synchronous, simple permission checks without async overhead. See [`MIGRATION_PLAN.md`](MIGRATION_PLAN.md) for full details.
-
-#### Calendar Permission Hierarchy
-
-**Permission hierarchy** (highest to lowest):
-
-1. `owner` - Created the calendar, full control
-2. `admin` - Can manage shares and settings
-3. `write` - Can edit shifts/notes/presets
-4. `read` - View only
-
-**Critical functions** in [`lib/auth/permissions.ts`](lib/auth/permissions.ts):
-
-- `getUserCalendarPermission(userId, calendarId)` - Returns permission level or `null`
-- `checkPermission(userId, calendarId, required)` - Boolean check with hierarchy
-- `getUserAccessibleCalendars(userId)` - Returns all calendars user can access
-- `canViewCalendar(userId, calendarId)` - Shorthand for read permission check
+## Critical Patterns
-**Guest access**: When auth is enabled, unauthenticated users (`userId = null`) can access calendars with `guestPermission != "none"`. Use `allowGuestAccess()` to check if feature is enabled.
+### Permission System (`lib/auth/permissions.ts`)
-#### Session Management
+Every calendar operation must check permissions. Priority order:
-**Session utilities** in [`lib/auth/sessions.ts`](lib/auth/sessions.ts):
+1. Owner (`calendar.ownerId === userId`)
+2. Share permission (`calendarShares` table)
+3. Access token (cookie-based)
+4. Guest permission (`calendar.guestPermission`)
```typescript
+// Always use these helpers in API routes
+import { getSessionUser } from "@/lib/auth/sessions";
import {
- getSessionUser,
- getUserSessions,
- revokeAllSessions,
-} from "@/lib/auth/sessions";
+ canEditCalendar,
+ getUserCalendarPermission,
+} from "@/lib/auth/permissions";
-// Get current user from request (API routes)
const user = await getSessionUser(request.headers);
-
-// Session management (API routes only - for bulk operations)
-const sessions = await getUserSessions(userId, currentSessionId);
-await revokeAllSessions(userId, exceptCurrentId); // Bulk revoke all except current
-```
-
-**Client-side session management**: Use Better Auth's built-in client functions:
-
-```typescript
-import { authClient } from "@/lib/auth/client";
-
-// List all active sessions for current user
-const sessions = await authClient.listSessions();
-
-// Revoke all other sessions (except current)
-await authClient.revokeOtherSessions();
-```
-
-**Session management hook** in [`hooks/useSessions.ts`](hooks/useSessions.ts):
-
-```typescript
-const { sessions, isLoading, revokeAllSessions } = useSessions();
-
-// Revoke all other sessions
-await revokeAllSessions(); // Uses authClient.revokeOtherSessions() internally
-```
-
-**Note**: Individual session revocation is not supported to prevent users from accidentally revoking their own active session. Only "revoke all other sessions" is available.
-
-**UI permission checks**: Use `useCalendarPermission(calendarId)` hook:
-
-```typescript
-const { canEdit, canDelete, canShare, permission } =
- useCalendarPermission(calendarId);
-```
-
-### 4. Public Configuration (Environment Variables)
-
-**NO MORE `NEXT_PUBLIC_` prefixes!** Server-only variables are exposed to the client safely via SSR injection.
-
-**Architecture**:
-
-- **Server-side**: [`lib/public-config.ts`](lib/public-config.ts) - `getPublicConfig()` function defines what's exposed
-- **Client-side**: [`hooks/usePublicConfig.ts`](hooks/usePublicConfig.ts) - `usePublicConfig()` hook for React components
-- **SSR Injection**: Config injected as `window.__PUBLIC_CONFIG__` in root layout (zero latency)
-
-**Usage patterns**:
-
-```typescript
-// Server Components (direct access)
-import { getPublicConfig } from "@/lib/public-config";
-const config = getPublicConfig();
-if (config.auth.enabled) {
- /* ... */
-}
-
-// Client Components (use hook)
-import { usePublicConfig } from "@/hooks/usePublicConfig";
-const { auth, oauth, oidc } = usePublicConfig();
-if (auth.enabled) {
- /* ... */
-}
-
-// Auth-specific helper hook
-import { useAuthFeatures } from "@/hooks/useAuthFeatures";
-const { isAuthEnabled, allowRegistration, allowGuest, providers } =
- useAuthFeatures();
-```
-
-**Environment variables** (no duplicates needed):
-
-```bash
-# Auth config (automatically exposed to client)
-AUTH_ENABLED=true
-BETTER_AUTH_URL=http://localhost:3000
-ALLOW_USER_REGISTRATION=true
-ALLOW_GUEST_ACCESS=false
-```
-
-**Key functions**:
-
-- `getPublicConfig()` - Server: Returns config object with all public values
-- `usePublicConfig()` - Client: Hook to access config in React components
-- `useAuthFeatures()` - Client: Convenience hook for auth-related flags
-- Feature flags in [`lib/auth/feature-flags.ts`](lib/auth/feature-flags.ts) are SERVER-ONLY now
-
-### 5. Real-Time Updates (React Query Polling)
-
-**Architecture**: All data fetching uses `@tanstack/react-query` with automatic polling for live updates across all pages and components.
-
-**Configuration**: [`lib/query-client.ts`](lib/query-client.ts) - Global query client settings
-
-```typescript
-// Centralized refetch interval constant
-export const REFETCH_INTERVAL = 5000; // 5s polling for live updates
-
-// Default settings
-{
- staleTime: 3000, // Data fresh for 3s
- gcTime: 300000, // Cache for 5min
- refetchInterval: REFETCH_INTERVAL,
- refetchOnWindowFocus: true,
- refetchOnReconnect: true,
+if (!(await canEditCalendar(user?.id, calendarId))) {
+ return NextResponse.json({ error: "Forbidden" }, { status: 403 });
}
```
-**Using custom polling intervals**: Import and use `REFETCH_INTERVAL` from [`lib/query-client.ts`](lib/query-client.ts) in all queries that need polling:
+### Query Keys (`lib/query-keys.ts`)
-**Query Keys**: [`lib/query-keys.ts`](lib/query-keys.ts) - Consistent key management
+All queries must use centralized query keys for proper cache invalidation:
```typescript
import { queryKeys } from "@/lib/query-keys";
-// Examples
-queryKeys.shifts.byCalendar(calendarId); // ['shifts', calendarId]
-queryKeys.admin.users({ filters, sort }); // ['admin', 'users', { filters, sort }]
+// Use factory functions
+useQuery({ queryKey: queryKeys.calendars.all, ... });
+useQuery({ queryKey: queryKeys.shifts.byCalendar(calendarId), ... });
```
-**Data fetching with useQuery**:
+### API Route Pattern
```typescript
-import { useQuery } from "@tanstack/react-query";
-import { queryKeys } from "@/lib/query-keys";
-import { REFETCH_INTERVAL } from "@/lib/query-client";
-
-const { data: shifts = [], isLoading } = useQuery({
- queryKey: queryKeys.shifts.byCalendar(calendarId!),
- queryFn: () => fetchShiftsApi(calendarId!),
- enabled: !!calendarId,
- refetchInterval: REFETCH_INTERVAL, // Use centralized constant
-});
-```
-
-**Mutations with optimistic updates**:
-
-```typescript
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-
-const queryClient = useQueryClient();
-
-const createMutation = useMutation({
- mutationFn: createShiftApi,
- onMutate: async (newShift) => {
- await queryClient.cancelQueries({
- queryKey: queryKeys.shifts.byCalendar(calendarId!),
- });
- const previous = queryClient.getQueryData(
- queryKeys.shifts.byCalendar(calendarId!)
- );
- queryClient.setQueryData(
- queryKeys.shifts.byCalendar(calendarId!),
- (old: Shift[] = []) => [...old, optimisticShift]
- );
- return { previous };
- },
- onError: (err, variables, context) => {
- queryClient.setQueryData(
- queryKeys.shifts.byCalendar(calendarId!),
- context?.previous
- );
- toast.error(t("common.createError", { item: t("shift.shift_one") }));
- },
- onSuccess: () => {
- toast.success(t("common.created", { item: t("shift.shift_one") }));
- },
- onSettled: () => {
- queryClient.invalidateQueries({
- queryKey: queryKeys.shifts.byCalendar(calendarId!),
- });
- },
-});
+// app/api/[resource]/route.ts
+export async function GET(request: Request) {
+ const user = await getSessionUser(request.headers);
+ // Check auth if enabled: isAuthEnabled() from lib/auth/feature-flags
+ // Check permissions with getUserCalendarPermission() or similar
+ // Rate limit sensitive operations: await rateLimit('type', identifier)
+ // Audit log actions: await logUserAction('ACTION', userId, metadata, request)
+}
```
-**Cache invalidation**: After mutations, use `queryClient.invalidateQueries()` to refetch related data.
-
-### 6. Component Architecture
-
-**Sheet pattern** (side panel): All forms use [`components/ui/base-sheet.tsx`](components/ui/base-sheet.tsx):
-
-- Unsaved changes confirmation via `useDirtyState` hook
-- Consistent header/footer styling with gradient backgrounds
-- Example: [`components/shift-sheet.tsx`](components/shift-sheet.tsx)
-
-**Dialog pattern**: Use [`components/ui/dialog.tsx`](components/ui/dialog.tsx) from shadcn/ui
-
-- List views, confirmations, and read-only displays
-- Example: [`components/shifts-overview-dialog.tsx`](components/shifts-overview-dialog.tsx)
-
-**Custom hooks pattern**:
-
-- Data fetching: `useShifts`, `usePresets`, `useNotes`, `useCalendars` (in `/hooks`)
-- Actions: `useShiftActions`, `useNoteActions` (handle CRUD + optimistic updates)
-- Forms: `useShiftForm` (form state + validation)
-
-### 7. Internationalization
+### Component Structure
-**Config**: [`lib/i18n.ts`](lib/i18n.ts) - Detects locale from cookie (`NEXT_LOCALE`) or `Accept-Language` header
+- Mark client components with `"use client"` at top
+- Use `@/components/ui/` primitives (shadcn pattern)
+- Sheets/dialogs use `BaseSheet` for consistent behavior
+- Forms extract logic to custom hooks (`useShiftForm`, etc.)
-**Usage**:
+## Development Commands
-```typescript
-import { useTranslations } from "next-intl";
-
-const t = useTranslations();
-t("shift.title"); // Returns translated string
-t("common.createError", { item: t("shift.title") }); // With interpolation
+```bash
+npm run dev # Start dev server
+npm run db:migrate # Apply migrations
+npm run i18n # Validate translations (de.json is source)
+npm run lint # ESLint check
+tsc --noEmit # TypeScript check without emitting
+npm run test # Full validation: lint + build + i18n
```
-**Message files**: [`messages/en.json`](messages/en.json), `de.json`, `it.json` - Nested JSON structure
+## Common Tasks
-### 8. External Calendar Sync
+### Adding a Translation
-**iCal parsing**: Uses `ical.js` library to parse `.ics` feeds
+1. Add key to `messages/de.json` (primary source)
+2. Run `npm run i18n` - it reports missing keys in en.json/it.json
+3. Add translations to other locales
-**Sync flow**:
+### Creating an API Endpoint
-1. User adds external sync URL + calendar mapping
-2. Manual/auto sync triggers [`app/api/external-syncs/[id]/sync/route.ts`](app/api/external-syncs/[id]/sync/route.ts)
-3. Shifts created with `syncedFromExternal: true`, `externalSyncId` set
-4. Sync logs stored in `syncLogs` table for error tracking
+1. Create route in `app/api/[resource]/route.ts`
+2. Use `getSessionUser()` for auth, `rateLimit()` for protection
+3. Log actions with `logUserAction()` or `logSystemEvent()`
+4. Return proper HTTP status codes with NextResponse.json()
-**Read-only enforcement**: Synced shifts cannot be edited/deleted by users. Check `shift.syncedFromExternal` before allowing mutations.
+### Adding Database Fields
-## Development Workflow
+1. Modify `lib/db/schema.ts`
+2. Run `npm run db:generate` to create migration
+3. Run `npm run db:migrate` to apply
-### Environment Setup
+### Creating a Hook
-**Required files**:
+Follow existing patterns in `hooks/`:
-- `.env` - Copy from `.env.example` and configure
-- `sqlite.db` - Auto-created on first run
+- Prefix with `use`
+- Use `queryKeys` for query keys
+- Handle rate limit errors with `isRateLimitError()` / `handleRateLimitError()`
+- Show feedback with `toast` from sonner
-**Critical env vars**:
+## File Conventions
-- `DATABASE_URL` - Default: `file:./sqlite.db`
-- `AUTH_ENABLED` - Enable/disable auth system (default: `true`)
-- `BETTER_AUTH_SECRET` - Required if auth enabled (generate with `npx @better-auth/cli secret`)
-- `BETTER_AUTH_URL` - Auth callback URL (e.g., `http://localhost:3000`)
+| Path | Purpose |
+| --------------------- | ---------------------------------------------- |
+| `lib/auth/*.ts` | Auth utilities (sessions, permissions, tokens) |
+| `lib/db/schema.ts` | All Drizzle table definitions |
+| `hooks/use*.ts` | TanStack Query hooks with mutations |
+| `components/ui/*.tsx` | Radix-based primitives (don't modify directly) |
+| `app/api/` | Route handlers (GET/POST/PATCH/DELETE) |
+| `messages/*.json` | i18n strings (de.json is authoritative) |
-**Note**: No `NEXT_PUBLIC_` prefixes needed - client values are automatically exposed via [`lib/public-config.ts`](lib/public-config.ts)
+## Auth Modes
-### Running the App
+- `AUTH_ENABLED=true`: Full multi-user with roles (user/admin/superadmin)
+- `AUTH_ENABLED=false`: Single-user mode, all operations bypass auth checks
+- Check with `isAuthEnabled()` from `lib/auth/feature-flags`
-```bash
-npm install # Install dependencies
-npm run dev # Start dev server (localhost:3000)
-npm run build # Production build
-npm run lint # ESLint check
-npm run test # Run lint + build (CI check)
-```
-
-### Docker Deployment
+## Important Rules
-```bash
-docker-compose up -d --build # Build and start container
-```
-
-Pre-built images: `ghcr.io/pantelx/bettershift:latest` (stable), `:dev` (bleeding edge)
-
-### Database Changes
+### Date Handling
-1. Modify [`lib/db/schema.ts`](lib/db/schema.ts)
-2. Generate migration: `npm run db:generate`
-3. Review SQL in `drizzle/` folder
-4. Apply migration: `npm run db:migrate`
+Always use **local dates** without timezone conversion:
-## Common Patterns
+- Store as `YYYY-MM-DD` strings in SQLite
+- Use `formatDateToLocal(date)` from `lib/date-utils.ts` before saving
+- Display with `date-fns` + locale from `getDateLocale(locale)`
-### API Route Structure
+### External Sync (Read-Only)
-```typescript
-import { NextRequest, NextResponse } from "next/server";
-import { db } from "@/lib/db";
-import { getSessionUser } from "@/lib/auth/sessions";
-import { checkPermission } from "@/lib/auth/permissions";
+Shifts synced from external calendars cannot be edited/deleted:
-export async function POST(request: NextRequest) {
- const user = await getSessionUser(request.headers);
- const { calendarId, ...data } = await request.json();
-
- // Check permissions
- const canEdit = await checkPermission(user?.id, calendarId, "write");
- if (!canEdit) {
- return NextResponse.json(
- { error: "Insufficient permissions" },
- { status: 403 }
- );
- }
-
- // Perform database operation
- const [result] = await db
- .insert(table)
- .values({ ...data, calendarId })
- .returning();
-
- // No event emission needed - React Query polling handles sync
- return NextResponse.json(result, { status: 201 });
-}
-```
+- Check `shift.syncedFromExternal` before allowing mutations
+- These shifts have `externalSyncId` set
### Optimistic Updates
-All mutations use React Query's optimistic update pattern. See [`hooks/useShifts.ts`](hooks/useShifts.ts):
-
-1. **onMutate**: Cancel queries, save previous state, apply optimistic update
-2. **onError**: Rollback to previous state, show error toast
-3. **onSuccess**: Show success toast
-4. **onSettled**: Invalidate queries to refetch real data
-
-```typescript
-const mutation = useMutation({
- mutationFn: createShiftApi,
- onMutate: async (newData) => {
- await queryClient.cancelQueries({ queryKey });
- const previous = queryClient.getQueryData(queryKey);
- queryClient.setQueryData(queryKey, (old) => [...old, optimisticItem]);
- return { previous };
- },
- onError: (err, vars, context) => {
- queryClient.setQueryData(queryKey, context?.previous);
- },
- onSettled: () => queryClient.invalidateQueries({ queryKey }),
-});
-```
-
-### Date Handling
-
-**Always use local dates** (no timezone conversions):
-
-- Store dates as `YYYY-MM-DD` strings in SQLite
-- Use `formatDateToLocal(date)` from [`lib/date-utils.ts`](lib/date-utils.ts) before saving
-- Display with `date-fns` + locale from `getDateLocale(locale)`
+All mutations use TanStack Query optimistic updates (`hooks/useShifts.ts` as reference):
-## Migration Context
-
-**Status**: Auth system migration is **in progress**. See [`MIGRATION_PLAN.md`](MIGRATION_PLAN.md) for full details.
-
-**Backward compatibility**: All features work without auth enabled. Auth can be disabled by setting `AUTH_ENABLED=false`. When auth is off, all users have `owner` permission to all calendars.
-
-## Key Files Reference
-
-- [`app/page.tsx`](app/page.tsx) - Main calendar view (1300+ lines, complex state management)
-- [`lib/db/schema.ts`](lib/db/schema.ts) - Complete database schema (Better Auth + app tables)
-- [`lib/auth/permissions.ts`](lib/auth/permissions.ts) - Permission checks and calendar access logic
-- [`lib/auth/sessions.ts`](lib/auth/sessions.ts) - Session management & current user utilities (request context + Better Auth integration)
-- [`hooks/useSessions.ts`](hooks/useSessions.ts) - Client-side session management hook (uses Better Auth client)
-- [`lib/public-config.ts`](lib/public-config.ts) - Server-side public config definition (no NEXT*PUBLIC*\*)
-- [`hooks/usePublicConfig.ts`](hooks/usePublicConfig.ts) - Client-side config access hook
-- [`hooks/useAuthFeatures.ts`](hooks/useAuthFeatures.ts) - Auth-specific feature flags hook
-- [`components/calendar-grid.tsx`](components/calendar-grid.tsx) - Core calendar rendering with shift display
-- [`lib/query-client.ts`](lib/query-client.ts) - React Query client configuration
-- [`lib/query-keys.ts`](lib/query-keys.ts) - Query key factory for consistent cache management
-- [`components/query-provider.tsx`](components/query-provider.tsx) - React Query provider
-- [`MIGRATION_PLAN.md`](MIGRATION_PLAN.md) - Detailed auth migration plan with phases and todos
-
-## Important Notes
-
-- **No NEXT*PUBLIC***: Use `getPublicConfig()` on server, `usePublicConfig()` hook on client - never `process.env.NEXT_PUBLIC_*`
-- **Better Auth first**: Always check [Better Auth docs](https://www.better-auth.com/docs) before implementing auth features - use built-in methods, don't reinvent
-- **React Query for data**: All data fetching uses `useQuery`/`useMutation` with polling - no manual fetch/refetch logic
-- **Query keys from factory**: Always use `queryKeys` from `lib/query-keys.ts` for cache consistency
-- **Optimistic updates**: All mutations should implement optimistic updates for instant UI feedback
-- **Permission checks everywhere**: Check permissions in both API routes (server) and UI (client) for security + UX
-- **Strict TypeScript**: No `any` types, use Drizzle-inferred types from schema
-- **Translations required**: All user-facing strings must use `t()` function
-- **Guest mode**: When auth enabled, respect `guestPermission` on calendars for unauthenticated access
+1. `onMutate`: Cancel queries, save previous state, apply optimistic update
+2. `onError`: Rollback to previous state, show error toast
+3. `onSettled`: Invalidate queries to refetch real data