Flowplanner — Shift Management System Internal Docs

Shift management system for Sense Garn AS (Sandnes, Norway). Replaces Google Sheets with a simple web app for shift planning, swap requests, and payroll calculation.

Project

• Weekly shift planning (admin creates/edits)
• Swap requests and direct shift transfers
• Payroll calculation (Norwegian supplements + overtime rules)
• Email notifications (Resend)

Non-Negotiable Rules

Documentation Updates (Required After Every Change)

Language Rules

Context	Language
Code (variables, functions, comments)	English
Documentation (CLAUDE.md, SPEC.md, README.md)	English
Git commits	English
UI text (buttons, labels, messages)	Norwegian

Commit Message Format

Type: Short description in English

- Detail 1
- Detail 2

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Allowed types: Add, Fix, Update, Refactor, Docs, DB

Deployment Rule (Critical)

Tech Stack

• Frontend: Next.js 14 (App Router), Tailwind CSS, shadcn/ui
• Backend: Supabase (PostgreSQL, RLS)
• Auth: Custom phone + PIN on top of Supabase Auth
• Email: Resend
• Hosting: Vercel

Core Concepts

Roles

• admin — full access (employees, payroll, requests, settings)
• employee — own payroll and shift actions

RLS Principles

• Everyone can see all shifts (to see colleagues).
• Employees can only see their own payroll.
• Admin sees everything.

UI Language

All user-facing text must be Norwegian.

Current Implementation Status

Completed

• Auth: phone + 4-digit PIN login (PIN stored as bcrypt hash)
• Login security: failed attempt tracking + lockout
• Week calendar with drag-and-drop shift management
• Employee management (CRUD + hourly rates)
• Payroll calculation with Norwegian pay supplements
• Payroll report with CSV export
• Employee “My Pay” page (currently hidden in navigation)
• Swap requests: request → approve/reject (email notifications)
• Direct shift transfer between employees (admin email notification)
• Company settings: name + logo (login + emails)
• Settings page displays overtime rules
• Sunday shifts allowed (100% overtime)
• “Flow Planner Pro” branding in employee menus
• Admin requests page auto-refresh (30s polling)
• Visual separator between morning and afternoon shifts in calendar views
• Admin can unlock locked employee accounts

Email System (Resend)

• Rate limit: ~1.6 emails/sec (600ms delay between sends)
• Table-based HTML templates for broad email client compatibility
• Company name prefixed to email subjects when available

API routes:

• POST /api/email/notify — swap notifications
  • swap_request_created → admins
  • swap_request_approved → employee
  • swap_request_rejected → employee
  • direct_swap → admins
• POST /api/email/schedule — bulk schedule overview (period)

Overtime Rules (displayed in Settings UI)

• Weekdays after 20:00: +50%
• Saturday after 18:00: +100%
• Sunday (all day): +100%
• Holidays (all day): +100%

Pay Supplements (Norwegian rules used by payroll calculator)

• Weekdays 18:00–20:00: +22 NOK/hour
• Saturday 13:00–15:00: +45 NOK/hour
• Saturday 15:00–18:00: +55 NOK/hour

Not Yet Implemented

• Weekly schedule email (automatic cron job)
• Supabase Edge Functions (optional future)
• Change PIN functionality
• Push notifications

Key Files & Responsibilities

• SPEC.md — source of truth for data model, business rules, UI spec, RLS
• supabase/migrations/ — database migrations (versioned)
• src/lib/pay-calculator.ts — payroll calculation logic
• src/lib/email.ts — Resend email templates and sending
• src/lib/supabase.ts — Supabase client helpers

App Structure

src/
  app/
    (auth)/
      login/page.tsx
    (dashboard)/
      page.tsx              # My shifts (employee) / Schedule (admin)
      calendar/page.tsx     # All shifts
      payroll/page.tsx      # Payroll report (admin)
      my-pay/page.tsx       # My pay (employee)
      employees/page.tsx    # Employees (admin)
      requests/page.tsx     # Swap requests (admin) - auto refresh
      settings/page.tsx     # Settings
    api/
      auth/login/           # custom auth (phone + PIN)
      email/notify/         # swap notifications
      email/schedule/       # bulk schedule emails
      employees/            # employee CRUD + unlock
      shifts/transfer/      # direct shift transfer (service role, bypasses RLS)
  components/
    ui/                     # shadcn/ui
    shift-card.tsx
    week-calendar.tsx
    swap-modal.tsx
    pay-summary.tsx
  lib/
    supabase.ts
    auth.ts
    pay-calculator.ts
    email.ts
    utils.ts

supabase/
  migrations/
    001_initial_schema.sql
  functions/
    send-swap-notification/   # placeholder / optional future
    weekly-schedule-email/    # placeholder / optional future

Database Tables (Overview)

1. employees — phone, bcrypt PIN hash, hourly rate, role, color, real email for notifications
2. shifts — date, time, assigned employee, notes, approval_status
3. swap_requests — swap workflow, including auto_approved for direct swaps
4. supplement_rules — pre-populated supplement rules
5. hourly_rate_history — historical changes (“from now”, no future planning)
6. payroll_entries — tracks which months have been paid per employee
7. company_settings — singleton settings row (name/logo)
8. failed_login_attempts — lockout tracking

Authentication Design (Custom Phone + PIN)

• Supabase Auth email: {phone}@flowplanner.local (internal only)
• Supabase Auth password: SG{pin} (e.g., SG1234)
• Employee email field: real email for notifications (separate from auth)

Creating a user

1. Create Supabase Auth user: {phone}@flowplanner.local + password SG{pin}
2. Insert into employees with phone, pin_hash (bcrypt), real email, role, hourly_rate, etc.

Shift Transfer API (Direct Swap)

• POST /api/shifts/transfer
• Uses service role to bypass RLS for admin-level operations
• Triggered from UI action “Gi bort vakt”

Email Domain Setup (Resend)

• Use a dedicated subdomain for Resend (e.g. resend.yourdomain.com)
• Avoid subdomains with NS records from other services (Klaviyo/Mailchimp)
• Resend test domain (onboarding@resend.dev) only sends to account owner

Environment variables:

RESEND_API_KEY
RESEND_FROM_EMAIL

Local Development

npm run dev

# Supabase local (optional)
supabase start
supabase db reset
supabase stop

Deployment (Vercel)

Environment Variables

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
RESEND_API_KEY
RESEND_FROM_EMAIL

Multi-Instance Setup

1. Create a new Vercel project from the repo
2. Set env vars for the new Supabase instance
3. Run migrations on the target Supabase instance

Database Migrations

Migrations live in supabase/migrations/ and must be numbered:

001_initial_schema.sql
002_some_change.sql
003_another_change.sql
...

Creating a migration

1. Create the next file number
2. Write SQL (prefer idempotent patterns: IF NOT EXISTS, etc.)
3. Test locally: supabase db reset
4. Commit

Production migrations

Run manually in Supabase Dashboard SQL editor before deploying code that depends on them.

Test Users (Seed Data)

Name	Phone	PIN	Role	Hourly Rate
Kristine	90000001	1234	admin	195
Emma	90000002	1234	employee	175
Jonas	90000003	1234	employee	175
Sofie	90000004	1234	employee	175

Git Workflow

Branching Strategy

main              # Production - auto deploy on push
feature/xyz       # New feature branches
fix/xyz           # Bug fix branches

Standard Flow

git checkout main
git pull origin main
git checkout -b feature/my-feature
# develop
git add .
git commit -m "Add: short description"
git push -u origin feature/my-feature
# Open PR - merge only after explicit approval