feat: complete Phase 3 — advanced features for Casera web app

Adds sharing (residence share codes, join, user management, .casera file export/import), subscription status with feature comparison, notification preferences with bell icon, profile settings (edit info, change password, theme picker, delete account), onboarding wizard with create/join paths, enhanced dashboard with stats cards, Recharts completion chart, recent activity feed, and task report PDF download. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-03 09:31:29 -06:00
commit 5a50d77515
183 changed files with 34450 additions and 0 deletions
@@ -0,0 +1,115 @@
+# 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](./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 |
+| .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 |