The Blueprint
That Builds
History

You are building PropertyOS — a production-grade, AI-native property management operating system built with Next.js 14 (App Router), TypeScript, Supabase, and Tailwind CSS. Deploy target is Vercel. ## PROJECT OVERVIEW PropertyOS replaces 6-9 fragmented SaaS tools used by property managers with a single unified platform. It serves: renters, property managers, property owners, maintenance vendors, leasing agents, and executives. ## TECH STACK (non-negotiable) - Framework: Next.js 14 with App Router + TypeScript - Database: Supabase (PostgreSQL + Row Level Security + Realtime) - Auth: Supabase Auth + FIDO2/WebAuthn passkeys - Styling: Tailwind CSS 3 + shadcn/ui components - State: Zustand + Tanstack Query - Charts: Recharts - AI: Vercel AI SDK + Anthropic Claude API (claude-3-5-sonnet-20241022) - Payments: Stripe (card fallback) + Plaid (bank link/ACH) - Biometrics: Jumio Web SDK (ID verification) + WebAuthn (passkeys) - Email: Resend - File storage: Supabase Storage - Deployment: Vercel (Edge Runtime for auth middleware) ## ARCHITECTURE REQUIREMENTS ### Multi-tenancy - Every database table MUST have: id (uuid), org_id (uuid), created_at, updated_at - Enable Row Level Security on ALL tables - RLS policy on every table: USING (org_id = (SELECT org_id FROM profiles WHERE id = auth.uid())) - Never bypass RLS — no service role calls from client components ### Folder structure src/ app/ (auth)/login/page.tsx — Supabase auth UI (gate)/page.tsx — Invite-code gate (email + 6-char code) (dashboard)/ layout.tsx — Authenticated shell with sidebar dashboard/page.tsx — Role-adaptive home properties/page.tsx — Property list + add properties/[id]/page.tsx — Property detail units/page.tsx — Unit management leases/page.tsx — Lease lifecycle payments/page.tsx — PayOS — rent, disbursements maintenance/page.tsx — Work orders + VendorNet screening/page.tsx — VerifyOS — applications + fraud compliance/page.tsx — ComplianceOS finance/page.tsx — FinanceOS — GL, reports people/page.tsx — PeopleOS — staff network/page.tsx — NetworkOS — referrals insights/page.tsx — InsightOS — AI dashboards market/page.tsx — MarketOS — listings + pricing settings/page.tsx api/ genie/route.ts — PropGenie streaming AI chat endpoint payments/webhook/route.ts — Stripe webhook handler verify/initiate/route.ts — Start biometric verification session migrate/route.ts — MigrateOS orchestration endpoint admin/stats/route.ts — Admin analytics dashboard track/route.ts — Custom event tracking admin/page.tsx — Analytics dashboard (password-protected) components/ ui/ — shadcn/ui components layout/ Sidebar.tsx — Role-aware navigation sidebar TopBar.tsx — User info + notifications + PropGenie trigger modules/ PropGenie.tsx — AI assistant chat panel (slide-in) PaymentForm.tsx — Rent payment with Plaid bank link LeaseBuilder.tsx — AI-assisted lease drafting MaintenanceBoard.tsx — Kanban work orders ScreeningFlow.tsx — Application + verification steps OwnerDashboard.tsx — Real-time NOI + portfolio view ComplianceChecker.tsx — Live lease compliance scan charts/ — Recharts wrappers for all data visualizations shared/ TrackedSection.tsx — IntersectionObserver section tracker lib/ supabase/ client.ts — Browser Supabase client server.ts — Server Supabase client (service role) middleware.ts — Auth middleware for App Router ai/ genie.ts — PropGenie AI agent config (Vercel AI SDK) prompts.ts — System prompts per agent type payments/ stripe.ts — Stripe server helpers plaid.ts — Plaid bank link helpers tracker.ts — Deep behavioral tracking posthog.tsx — PostHog provider + helpers types/ database.types.ts — Generated Supabase types (supabase gen types) index.ts — App-level TypeScript types ## DATABASE SCHEMA (create all in Supabase SQL editor) ### Core tables to scaffold: 1. organizations — id, slug, name, plan_tier, created_at 2. profiles — id (FK auth.users), org_id, email, full_name, role (enum: renter|owner|manager|agent|vendor|admin), avatar_url 3. properties — id, org_id, name, type (enum: sfr|duplex|multifamily|high_rise|mixed_use|hoa), address_line1, address_line2, city, state, zip, lat, lng, unit_count 4. units — id, org_id, property_id, unit_number, bedrooms, bathrooms, sqft, monthly_rent_cents, status (enum: vacant|occupied|maintenance|pending) 5. persons — id, org_id, email, full_name, phone, identity_verified_at, fraud_risk_score, roles (text[]) 6. leases — id, org_id, unit_id, person_id, start_date, end_date, monthly_rent_cents, status (enum: draft|active|expired|terminated), pdf_url 7. payments — id, org_id, lease_id, person_id, amount_cents, fee_cents, status (enum: initiated|pending|settled|failed), rail (enum: ach|fednow|card), idempotency_key, settled_at 8. maintenance_requests — id, org_id, unit_id, person_id, category, priority (enum: emergency|high|normal|low), description, status (enum: open|assigned|in_progress|completed), assigned_vendor_id, photos (text[]) 9. vendors — id, org_id, name, email, phone, specialties (text[]), rating, license_verified, insurance_verified, active 10. invite_codes — id, org_id, code, label, max_uses, uses_count, is_active, expires_at 11. visitors — id, org_id, email, invite_code, browser, os, device_type, ip_address, fingerprint_id, first_seen_at 12. sessions — id, visitor_id, started_at, ended_at, duration_seconds, max_scroll_depth, sections_viewed (text[]) 13. events — id, session_id, visitor_id, event_type, event_data (jsonb), scroll_depth, created_at Enable RLS on ALL tables. Write policies for each. ## KEY FEATURES TO BUILD (priority order) ### 1. Invite-Code Gate (/gate) - Two-step flow: email input → 6-character code input (animated boxes, auto-advance) - Server-side verification via /api/verify-code (code never in client JS) - On success: store session in sessionStorage, call /api/track for visitor record - Biometric fingerprint collection (canvas + navigator properties) - Shake animation on wrong code, loading spinner on submit ### 2. PropGenie AI Assistant - Floating button bottom-right → slides open a full chat panel - Uses Vercel AI SDK streaming with claude-3-5-sonnet-20241022 - System prompt adapts based on user role (renter/PM/owner) - Supports: maintenance requests, payment questions, lease queries, compliance checks - Stores conversation in Supabase for context across sessions - Voice input via browser Web Speech API ### 3. PayOS Payment Flow - Plaid Link for bank account connection - Display: amount due, fee breakdown (FTC-compliant, shown before submit) - ACH payment initiation with idempotency key - Real-time status updates via Supabase Realtime - Stripe card fallback with fee disclosure ### 4. VerifyOS Screening - Application form → Jumio ID scan → Plaid income verification - Fraud risk score display (traffic light UI) - Decision recommendation (approve/review/deny) with reasoning - Adverse action notice generator (FCRA compliant) ### 5. InsightOS Dashboard - Role-adaptive: different KPIs for each user type - Recharts: NOI trend, occupancy rate, payment collection rate, maintenance cost - AI-generated insights panel (PropGenie analyzes the data and writes a summary) - Real-time updates via Supabase Realtime subscriptions ### 6. MigrateOS Basic Flow - File upload (CSV/Excel from legacy system) - Column mapping UI (drag-and-drop field mapping) - Preview + validation (highlight issues before import) - Import with progress bar and per-table confidence scores ## ENVIRONMENT VARIABLES NEEDED NEXT_PUBLIC_SUPABASE_URL= NEXT_PUBLIC_SUPABASE_ANON_KEY= SUPABASE_SERVICE_ROLE_KEY= NEXT_PUBLIC_POSTHOG_KEY= NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com ANTHROPIC_API_KEY= STRIPE_SECRET_KEY= STRIPE_PUBLISHABLE_KEY= STRIPE_WEBHOOK_SECRET= PLAID_CLIENT_ID= PLAID_SECRET= PLAID_ENV=sandbox JUMIO_API_TOKEN= JUMIO_API_SECRET= RESEND_API_KEY= ADMIN_SECRET= NEXT_PUBLIC_APP_URL=http://localhost:3000 ## CODE STANDARDS - TypeScript strict mode — no `any` types - Every API route validates input with Zod - All monetary values stored as integers (cents) — never floats - All timestamps UTC with timezone - Soft deletes everywhere (deleted_at nullable column) - Error boundaries on all client components - Loading and error states on every async operation - Mobile-first responsive design - Dark mode support via CSS variables ## WHAT TO BUILD FIRST (Sprint 1) 1. Initialize Next.js 14 project with TypeScript + Tailwind + shadcn/ui 2. Set up Supabase project + run schema SQL 3. Configure Supabase Auth with email/password 4. Build the /gate page (invite code flow) — this is the first thing users see 5. Build the authenticated layout (sidebar + topbar) 6. Build the dashboard home page (role-adaptive, shows different content per user type) 7. Connect PropGenie AI endpoint (streaming chat with Claude) 8. Deploy to Vercel with all environment variables Start with Sprint 1. Generate all files with full implementation, not stubs. Every component should be production-ready, not a placeholder. Include error handling, loading states, and TypeScript types throughout.