honeyDueWeb/docs/00-overview.md

Casera Web App — Build Plan Overview

What We're Building

Full parity web app for Casera: 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

myCribAPI-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	Foundation	Scaffold, auth, layout, design system
Phase 2	Core CRUD	4 domains: residences, tasks, contractors, documents
Phase 3	Advanced Features	Sharing, subscription, notifications, onboarding
Phase 4	Demo Mode	Mock data, in-memory store, session isolation
Phase 5	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
.casera 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.casera.treytartt.com), no coupling to Go API deployment