honeyDueWeb/docs/00-overview.md

# honeyDue Web App — Build Plan Overview

## What We're Building

Full parity web app for honeyDue: **46 screens**, **104 API operations**, **4 domains** (Residences, Tasks, Contractors, Documents), plus auth, onboarding, subscriptions, settings, and a **sandboxed demo mode** with mock data.

## Tech Stack

| Layer | Choice |
|---|---|
| Framework | Next.js 15 (App Router) |
| Language | TypeScript |
| Styling | Tailwind CSS 4 |
| Components | shadcn/ui + Radix primitives |
| State (server) | TanStack Query v5 |
| State (client) | Zustand |
| Forms | React Hook Form + Zod validation |
| Auth | httpOnly cookie storing API token, Next.js middleware for route protection |
| Kanban | dnd-kit (drag-and-drop) for task board |
| Charts/metrics | Recharts (for summary dashboard) |
| Icons | Lucide (matches shadcn/ui) |
| Testing | Vitest + Playwright |
| Deployment | Docker → Dokku (separate app) |

## Why Next.js + shadcn/ui

- SSR for the marketing landing + demo preview (SEO, social sharing)
- shadcn/ui gives the exact component primitives this app needs (kanban boards, forms, dialogs, data tables)
- TanStack Query maps perfectly to the existing `APILayer` → `DataManager` cache pattern
- Separate Dokku app keeps deployment independent
- Biggest ecosystem for finding solutions

## Project Structure

```
honeyDueAPI-Web/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (marketing)/        # Public pages (landing, pricing)
│   │   ├── (auth)/             # Login, Register, Forgot Password, Reset
│   │   ├── (onboarding)/       # Multi-step onboarding flow
│   │   ├── (demo)/             # Demo mode (sandboxed)
│   │   │   └── layout.tsx      # Wraps demo in DemoProvider context
│   │   ├── (app)/              # Authenticated app
│   │   │   ├── residences/     # List, [id] detail, new, [id]/edit
│   │   │   ├── tasks/          # Kanban board, new, [id]/edit, [id]/complete
│   │   │   ├── contractors/    # List, [id] detail, new, [id]/edit
│   │   │   ├── documents/      # Tabs (warranties/documents), [id] detail
│   │   │   └── settings/       # Profile, notifications, themes, subscription
│   │   └── layout.tsx          # Root layout
│   ├── components/
│   │   ├── ui/                 # shadcn/ui primitives
│   │   ├── forms/              # Reusable form components
│   │   ├── cards/              # ResidenceCard, TaskCard, ContractorCard, etc.
│   │   ├── kanban/             # KanbanBoard, KanbanColumn, TaskActions
│   │   └── shared/             # EmptyState, LoadingOverlay, ErrorBanner, etc.
│   ├── lib/
│   │   ├── api/                # API client (typed fetch wrappers per domain)
│   │   ├── demo/               # DemoDataProvider + mock data seeds
│   │   ├── auth/               # Token management, middleware helpers
│   │   ├── hooks/              # useResidences, useTasks, etc. (TanStack Query)
│   │   └── types/              # TypeScript types matching API DTOs
│   ├── stores/                 # Zustand stores (auth, theme, demo state)
│   └── styles/                 # Tailwind theme config, design tokens
├── public/                     # Static assets
├── Dockerfile
├── next.config.ts
├── tailwind.config.ts
├── package.json
└── CLAUDE.md
```

## Build Phases

| Phase | Focus | Details |
|-------|-------|---------|
| [Phase 1](./01-foundation.md) | Foundation | Scaffold, auth, layout, design system |
| [Phase 2](./02-core-crud.md) | Core CRUD | 4 domains: residences, tasks, contractors, documents |
| [Phase 3](./03-advanced-features.md) | Advanced Features | Sharing, subscription, notifications, onboarding |
| [Phase 4](./04-demo-mode.md) | Demo Mode | Mock data, in-memory store, session isolation |
| [Phase 5](./05-polish-deploy.md) | Polish & Deploy | Responsive, error handling, Dockerfile, tests |

## Web-Only Adaptations

| Mobile Feature | Web Equivalent |
|---|---|
| Push notifications | Not needed (no push API for web in scope) |
| Widgets | Not applicable |
| .honeydue file import/export | File download (export) + drag-and-drop or file picker (import) |
| Apple/Google Sign In | OAuth redirect flow (same backend endpoints) |
| StoreKit subscription | Stripe Checkout or link to App Store (TBD) |
| Camera capture | File upload input (no camera API needed) |
| Haptics | N/A |
| Background refresh | TanStack Query `refetchInterval` + window focus refetch |

## Risks & Mitigations

| Risk | Mitigation |
|---|---|
| Kanban board performance with many tasks | Virtualize columns with `react-window`, limit initial render to 50 tasks per column |
| Demo mode state leaking between sessions | Session ID in httpOnly cookie, Zustand store scoped to session, auto-clear on expiry |
| File upload size limits | Match backend 10MB limit, client-side validation before upload |
| OAuth redirect for Apple/Google | Use backend's existing social auth endpoints, redirect flow instead of native SDK |
| Subscription without StoreKit | Phase 1: link to App Store. Phase 2: add Stripe for web-only purchases (requires backend work) |
| 46 screens is a lot of UI | shadcn/ui + consistent patterns reduce per-screen effort to ~1-2 hours each after foundation is built |

## Security Considerations

| Concern | Approach |
|---|---|
| Auth token in browser | httpOnly cookie, not accessible to JS, CSRF protection via SameSite=Strict |
| Demo mode data isolation | No backend calls, purely client-side, session-scoped store, no persistence |
| API compatibility | 100% same endpoints, same token format (`Token <hex>`), same request/response shapes |
| Mobile feature gaps | Push notifications and widgets explicitly excluded. Everything else covered. |
| Deployment independence | Separate Dokku app, own domain (e.g., `app.honeydue.treytartt.com`), no coupling to Go API deployment |