From a0e38e5ae5ea2c9560f52397369a8c5784730bb3 Mon Sep 17 00:00:00 2001
From: Trey t <treytartt@fastmail.com>
Date: Tue, 3 Mar 2026 11:47:24 -0600
Subject: [PATCH] docs: add README with project overview and architecture

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..21d53a6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+# Casera Web App
+
+Next.js web client for the Casera property management platform. Connects to the [Go REST API](https://github.com/akatreyt/casera-api) backend.
+
+## Features
+
+- **Residences** — Create and manage properties, share access with household members via invite codes
+- **Tasks** — Track maintenance tasks with kanban board, due dates, recurring schedules, and completion photos
+- **Contractors** — Manage service providers with contact info, specialties, and task associations
+- **Documents** — Store leases, warranties, manuals, and other property documents
+- **Demo Mode** — Try the full app with mock data at `/demo`, no account required
+- **Notifications** — Real-time notification bell with preference management
+- **Settings** — Profile editing, password changes, notification preferences, account deletion
+
+## Tech Stack
+
+- **Framework**: [Next.js](https://nextjs.org) 16 (App Router, Turbopack)
+- **UI**: [Tailwind CSS](https://tailwindcss.com) + [shadcn/ui](https://ui.shadcn.com)
+- **State**: [TanStack React Query](https://tanstack.com/query) for server state
+- **Forms**: [React Hook Form](https://react-hook-form.com) + [Zod](https://zod.dev) validation
+- **Drag & Drop**: [@dnd-kit](https://dndkit.com) for kanban board
+- **Analytics**: [PostHog](https://posthog.com)
+- **E2E Tests**: [Playwright](https://playwright.dev)
+- **Deployment**: Docker (Dokku-compatible)
+
+## Getting Started
+
+```bash
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start dev server with Turbopack |
+| `npm run build` | Production build |
+| `npm run start` | Start production server |
+| `npm run lint` | Run ESLint |
+| `npm run test:e2e` | Run Playwright tests |
+| `npm run test:e2e:ui` | Run Playwright tests with UI |
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `NEXT_PUBLIC_API_URL` | Go API base URL (e.g. `https://casera.treytartt.com/api`) | Yes |
+| `API_URL` | Server-side API URL (defaults to `NEXT_PUBLIC_API_URL`) | No |
+| `NEXT_PUBLIC_POSTHOG_KEY` | PostHog project API key | No |
+| `NEXT_PUBLIC_POSTHOG_HOST` | PostHog instance URL | No |
+
+## Architecture
+
+```
+src/
+├── app/                    # Next.js App Router pages
+│   ├── (auth)/             # Login, register, forgot password
+│   ├── api/                # Route handlers (auth, proxy)
+│   ├── app/                # Authenticated app pages
+│   └── demo/               # Demo mode (mirrors app/ with mock data)
+├── components/
+│   ├── contractors/        # Contractor cards, forms
+│   ├── dashboard/          # Stats cards, recent activity
+│   ├── demo/               # Demo banner
+│   ├── documents/          # Document cards, forms, image gallery
+│   ├── layout/             # Sidebar, top bar, mobile nav
+│   ├── notifications/      # Notification bell
+│   ├── onboarding/         # Onboarding steps
+│   ├── residences/         # Residence cards
+│   ├── settings/           # Profile, password, preferences
+│   ├── shared/             # Error banner, form field
+│   ├── sharing/            # Share codes, user management
+│   ├── tasks/              # Kanban board, task cards, forms
+│   └── ui/                 # shadcn/ui primitives
+├── lib/
+│   ├── analytics/          # PostHog provider
+│   ├── api/                # API client, auth, residences, tasks, etc.
+│   ├── demo/               # Demo data provider, mock data
+│   └── hooks/              # React Query hooks per domain
+└── tests/                  # Playwright E2E tests
+```
+
+All client-side API requests go through Next.js proxy route handlers (`/api/proxy/...`) which attach the auth token from an httpOnly cookie before forwarding to the Go API.
+
+## License
+
+Private