honeyDueWeb/CLAUDE.md

honeyDue Web (honeyDueAPI-Web)

Next.js web client for the honeyDue property management platform. Talks to the Go REST API backend.

Build & Run

npm run dev          # Dev server (localhost:3000)
npm run build        # Production build (catches type errors)
npm run lint         # ESLint
npm run test:e2e     # Playwright end-to-end tests
npm run test:e2e:ui  # Playwright with UI
npm run analyze      # Bundle analysis

Stack

• Framework: Next.js 16 (App Router, React 19)
• Styling: Tailwind CSS v4 + shadcn/ui (Radix primitives)
• State: Zustand (auth, onboarding, theme), TanStack React Query (server state)
• Forms: React Hook Form + Zod validation
• Drag & Drop: @dnd-kit (kanban boards)
• Charts: Recharts
• Icons: Lucide React
• Analytics: PostHog
• Testing: Playwright (E2E), Vitest (unit)

Architecture

Request Flow

Browser → Next.js page (client component)
       → apiFetch("/tasks/") → /api/proxy/tasks (Next.js route handler)
       → Go API (reads ory_kratos_session cookie, forwards it as a Cookie header)

Identity is owned by Ory Kratos (NEXT_PUBLIC_KRATOS_URL). The browser holds an ory_kratos_session cookie set by Kratos. The Next.js /api/proxy/[...path] catch-all route forwards that cookie to the Go API, which validates the session against Kratos. The Go API no longer does auth (no Authorization: Token).

Auth (Ory Kratos)

Login / registration / recovery (forgot-password) / email verification / password changes use Kratos browser self-service flows:

• Auth pages (src/app/(auth)/...) initialize a flow by hard-navigating the browser to {kratos}/self-service/{type}/browser; Kratos sets a flow cookie and redirects back with ?flow=<id>.
• The page reads ?flow=<id>, fetches the flow definition (ui.nodes / ui.action / ui.method), and renders it generically via <KratosFlowForm>.
• Social sign-in (Apple/Google) = the oidc nodes in the flow.
• src/lib/kratos/ holds the client (getFlow, submitFlow, whoami, logout, ...) and the useKratosFlow hook.
• Route protection: <AuthGate> (in src/app/app/layout.tsx) calls {kratos}/sessions/whoami; the middleware does a cheap ory_kratos_session cookie pre-filter.

Directory Structure

src/
├── app/
│   ├── (auth)/           # Kratos self-service flow pages (login/register/recovery/verify)
│   ├── api/proxy/        # Catch-all proxy to Go API
│   ├── app/              # Authenticated app pages
│   │   ├── contractors/  # Contractor CRUD
│   │   ├── documents/    # Document management
│   │   ├── residences/   # Residence CRUD + detail with kanban
│   │   ├── settings/     # User settings, theme
│   │   └── tasks/        # Task CRUD, kanban board
│   ├── demo/             # Demo mode (fake data, no auth)
│   └── page.tsx          # Landing page
├── components/
│   ├── contractors/      # Contractor cards, forms
│   ├── dashboard/        # Stats, activity, template suggestions
│   ├── demo/             # Demo banner
│   ├── documents/        # Document cards, forms
│   ├── forms/            # Auth form wrapper
│   ├── layout/           # TopBar, MobileNav, Sidebar
│   ├── notifications/    # Notification components
│   ├── onboarding/       # Onboarding flow
│   ├── residences/       # Residence cards, forms, summary, share
│   ├── settings/         # Theme picker
│   ├── shared/           # PageHeader, EmptyState, ErrorBanner, etc.
│   ├── sharing/          # Share code UI
│   ├── tasks/            # TaskCard, TaskForm, KanbanBoard, KanbanColumn
│   └── ui/               # shadcn primitives (button, card, dialog, etc.)
├── lib/
│   ├── api/              # API client functions per domain
│   │   ├── client.ts     # apiFetch (client-side) + serverFetch (server-side)
│   │   ├── tasks.ts      # Task API (CRUD, kanban, completions)
│   │   ├── residences.ts # Residence API (CRUD, sharing, reports)
│   │   ├── contractors.ts
│   │   ├── documents.ts
│   │   └── ...
│   ├── hooks/            # React Query hooks per domain
│   │   ├── use-tasks.ts  # useTasks, useTask, useCreateTask, etc.
│   │   ├── use-residences.ts
│   │   └── ...
│   ├── demo/             # Demo mode: DataProvider abstraction
│   │   ├── data-provider-context.tsx  # React context
│   │   ├── real-provider.ts           # Real API calls
│   │   ├── demo-provider.ts           # Fake data
│   │   └── mock-data/                 # Static demo data
│   ├── themes/           # Theme system (Warm Sage palette)
│   ├── validations/      # Zod schemas
│   └── utils.ts          # cn() helper
├── stores/
│   ├── auth.ts           # Zustand: user, token, login/logout
│   ├── onboarding.ts     # Zustand: onboarding state
│   └── theme.ts          # Zustand: theme preferences
└── styles/
    └── themes.css        # CSS custom properties for theme

Key Patterns

Data fetching: All server data uses React Query hooks (use-*.ts). Hooks call API functions from lib/api/. API functions call apiFetch() which proxies through Next.js.

Demo mode: The app supports a /demo route with fake data. Components use useDataProvider() to get API functions and basePath — this returns either real or demo implementations depending on the route.

Kanban boards: Tasks display in kanban columns (overdue, due_soon, in_progress, not_started, completed). Uses @dnd-kit for drag-and-drop. Column names match Go API: overdue_tasks, due_soon_tasks, in_progress_tasks, not_started_tasks, completed_tasks.

Middleware (src/middleware.ts): Cheap pre-filter on the ory_kratos_session cookie. Redirects users without the cookie to /login for protected routes. Skips API routes, static files, and public paths. The authoritative session check is <AuthGate> (whoami).

Conventions

• All pages under /app/ are "use client" components
• Use apiFetch() for client-side API calls, serverFetch() for server components/route handlers
• React Query hooks go in src/lib/hooks/use-{domain}.ts
• API client functions go in src/lib/api/{domain}.ts
• shadcn components in src/components/ui/ — don't modify these directly
• Custom components use Tailwind classes, warm shadow CSS variables (--shadow-warm-sm, --shadow-warm-md)
• Brand colors: primary (sage green), brand-clay, brand-sage variants defined in CSS custom properties
• Font: font-heading for headings (tracking-tight), system font for body
• Toast notifications via sonner — use toast.success(), toast.error()
• Form validation with Zod schemas in src/lib/validations/
• Icons from lucide-react — keep consistent sizes (size-4 for inline, size-5 for cards)

Environment Variables

Variable	Description	Default
NEXT_PUBLIC_API_URL	Go API URL (client-side)	https://honeyDue.treytartt.com/api
API_URL	Go API URL (server-side, no proxy)	Falls back to NEXT_PUBLIC_API_URL
NEXT_PUBLIC_KRATOS_URL	Ory Kratos public API URL (identity)	https://auth.myhoneydue.com
NEXT_PUBLIC_POSTHOG_KEY	PostHog analytics key	—
NEXT_PUBLIC_POSTHOG_HOST	PostHog host	—

See .env.example for the full list.

Common Tasks

Add a new page: Create src/app/app/{route}/page.tsx (client component). Add nav item to src/components/layout/nav-items.ts.

Add a new API domain: Create src/lib/api/{domain}.ts with typed functions using apiFetch(). Create src/lib/hooks/use-{domain}.ts with React Query hooks. Add demo provider methods if needed.

Add a shadcn component: npx shadcn@latest add {component} — installs to src/components/ui/.