# HAVEN KE

## Product Requirements Document (PRD)

**Version:** 2.0
**Status:** Active — guides all design & engineering decisions
**Last updated:** July 2025
**Owners:** Product, Engineering, Design
**Predecessor:** Technical Implementation Document (now `/TECHNICAL.md`, secondary)

---

> **How to read this document**
> This PRD is the source of truth for *what* we're building and *why*. Every feature, every screen, every line of CSS starts here. The companion `/TECHNICAL.md` documents *how* the system is wired. If they ever disagree, this document wins until amended.
>
> **Status legend:** ✅ Specified · 🟡 Open question · ❌ Out of scope (v2)

---

## Table of Contents

1. [Product Vision](#1-product-vision)
2. [Product Goals](#2-product-goals)
3. [Success Metrics](#3-success-metrics)
4. [Target Personas](#4-target-personas)
5. [Design Philosophy](#5-design-philosophy)
6. [Design Language & System](#6-design-language--system)
7. [Tailwind CSS — Mandatory](#7-tailwind-css--mandatory)
8. [UI Theme Tokens](#8-ui-theme-tokens)
9. [Glassmorphism Specification](#9-glassmorphism-specification)
10. [Motion Design](#10-motion-design)
11. [Information Architecture](#11-information-architecture)
12. [User Experience Principles](#12-user-experience-principles)
13. [Responsive Requirements](#13-responsive-requirements)
14. [Accessibility](#14-accessibility)
15. [Performance Targets](#15-performance-targets)
16. [Technical Stack](#16-technical-stack)
17. [Kenya Market Specifics](#17-kenya-market-specifics)
18. [Trust & Safety](#18-trust--safety)
19. [Payments](#19-payments)
20. [Future Integrations](#20-future-integrations)
21. [Out of Scope (v2)](#21-out-of-scope-v2)
22. [Risks & Mitigations](#22-risks--mitigations)
23. [Glossary](#23-glossary)
24. [Definition of Done](#24-definition-of-done)
25. [Approval](#25-approval)

---

## 1. Product Vision

Haven KE is not a property listing website.

Haven KE is **Kenya's trusted digital real estate ecosystem** — designed to eliminate fraud, simplify property discovery, and make buying, renting, selling, and managing real estate effortless.

Every feature should reinforce one principle:

> **Trust before Transactions.**

Users should feel, on first scroll, that Haven is safer, more modern, and more intelligent than any existing real estate platform in the country.

---

## 2. Product Goals

The platform should:

1. **Help seekers** find verified properties quickly and confidently.
2. **Help providers** market properties professionally with measurable results.
3. **Reduce scams** through mandatory identity and document verification.
4. **Simplify payments** — every Kenyan already has M-Pesa, so should every transaction.
5. **Make viewings effortless** — schedule, route, complete, all in-app.
6. **Become the default property marketplace in Kenya** — measured by share of voice, NPS, and closed-deal volume.

---

## 3. Success Metrics

| Metric | Target (12 months) |
|---|---|
| Monthly active users (MAU) | 250,000 |
| Verified properties live | 50,000 |
| Verified brokers | 1,200 |
| Closed-deal volume | KSh 25B |
| Seeker → enquiry rate | ≥ 18% |
| Provider → listing rate (after KYC) | ≥ 75% |
| Time-to-first-deal for new agents | ≤ 21 days median |
| M-Pesa payment success rate | ≥ 96% |
| NPS (seeker) | ≥ 55 |
| NPS (provider) | ≥ 45 |
| Page load (LCP, 4G Kenya) | ≤ 2.0s |

---

## 4. Target Personas

### 🟢 Seeker — Wanjiru, 32, Marketing Manager, Nairobi
- Looking to rent a 2BR in Kilimani under KSh 80K/month
- Has been scammed twice by fake listings on Facebook
- Wants verified listings, video walkthroughs, and the landlord's actual number
- Willing to pay KSh 1,500/mo to contact landlords safely

### 🟢 Provider — Otieno, 41, EATB-licensed broker, Westlands
- Manages 30 rental listings + 5 active sales
- Spends 4 hours/day on lead follow-up, wants it centralised
- Cares about commission tracking, branded profile, and repeat tenants
- Willing to pay KSh 8,500/mo for verified badge + priority placement

### 🟢 Provider — Akinyi, 56, Landlady, Kisumu
- Owns 8 rental units in Mamboleo
- Not tech-savvy, uses phone for everything
- Needs simple listing flow, SMS notifications, no jargon
- Willing to pay KSh 3,500/mo to stop vacancy

### 🟢 Admin — Compliance Officer (internal)
- Reviews KYC submissions, approves listings, handles disputes
- Needs a clean dashboard with bulk actions, export, audit log

---

## 5. Design Philosophy

The UI should feel like a **premium fintech product** rather than a classifieds website.

**Inspiration:** Apple · Airbnb · Linear · Stripe Dashboard · Notion · Arc Browser

Users should feel: **luxury · confidence · simplicity · speed · trust**

Every visual decision (typography, spacing, motion, color) should be made to evoke that feeling. If a design choice would also fit a generic MLM landing page, it's wrong.

---

## 6. Design Language & System

The project MUST use:

- ✅ **Tailwind CSS** — utility-first, mandatory (see §7)
- ✅ Responsive design — mobile-first
- ✅ **Glassmorphism** — applied consistently (see §9)
- ✅ Smooth motion — see §10
- ✅ Rounded corners — `rounded-2xl` default, never sharp 90° corners
- ✅ Soft shadows — layered, never harsh
- ✅ Frosted glass panels — `backdrop-blur` + low-opacity background
- ✅ Gradient backgrounds — subtle, on hero sections and CTAs
- ✅ Large spacing — generous whitespace
- ✅ Clean typography — Inter (sans) + Fraunces (serif accents)

**Avoid:**

- ❌ Bootstrap or any other CSS framework
- ❌ Heavy 1–2px borders (use translucent dividers instead)
- ❌ Boxy / grid-cluttered layouts
- ❌ Bright primary colors as backgrounds
- ❌ Generic template aesthetics

---

## 7. Tailwind CSS — Mandatory

> **Tailwind is not optional. It is part of the architecture.**

Every component MUST use Tailwind utility classes instead of handcrafted CSS wherever practical.

**Examples of what Tailwind handles:**

- Glass cards with translucent backgrounds
- Sticky navigation (`sticky top-0 backdrop-blur`)
- Animated side panels (`translate-x` + `transition-transform`)
- Floating action buttons (`fixed bottom-6 right-6`)
- Animated search bar (focus rings, scale on focus)
- Responsive grids (`grid-cols-1 md:grid-cols-2 lg:grid-cols-3`)
- Modern modal dialogs (centered, blurred backdrop)
- Drawer navigation
- Floating filter chips
- Form inputs with focus states
- Buttons with hover/active states
- Typography scale and rhythm

**Custom CSS is permitted only for:**

- Advanced keyframe animations not expressible in Tailwind
- Reusable design tokens (CSS variables for the theme)
- Browser-specific fallbacks
- Third-party library overrides (Leaflet, MediaRecorder UI)

**Tooling:**
- Tailwind CLI (build-time) or Tailwind Play CDN (acceptable for prototype, mandatory production)
- `tailwind.config.js` must define the theme tokens (§8)
- `safelist` or content scan must include all dynamic class names
- Tree-shake unused classes in production builds

---

## 8. UI Theme Tokens

Defined in `tailwind.config.js` as `theme.extend.colors`:

| Token | Value | Usage |
|---|---|---|
| `primary` | Deep Navy `#0e1a2b` | Backgrounds, primary text |
| `accent` | Royal Gold `#c9a87c` | CTAs, highlights, brand mark |
| `background` | Soft White `#fafaf7` | Page background |
| `surface` | `#ffffff` | Cards |
| `glass` | `rgba(255,255,255,0.65)` | Glass panels |
| `success` | Emerald `#10b981` | Confirmations, paid |
| `warning` | Amber `#f59e0b` | Cautions, pending |
| `error` | Rose `#f43f5e` | Validation, rejections |
| `muted` | Slate `#64748b` | Secondary text |
| `border` | `rgba(15,26,43,0.08)` | Dividers |

**Dark mode is required** and must be defined as a separate token set. Default: light. User preference + system preference (`prefers-color-scheme`) should both be respected.

**Typography:**
- Sans: **Inter** (300, 400, 500, 600, 700)
- Serif: **Fraunces** (300, 400, 500, 600, 700) — for headlines & display
- Type scale: Tailwind defaults are fine, but reduce on mobile

---

## 9. Glassmorphism Specification

The interface should consistently use a modern glass aesthetic.

**Every major card MUST include:**

- `backdrop-blur-md` to `backdrop-blur-xl`
- Background opacity 0.6–0.85
- `border border-white/20` (light) or `border-white/10` (dark)
- Layered shadows: `shadow-lg shadow-black/5`
- Subtle gradient overlay where appropriate
- Slight elevation (translate-y) on hover

**Implementation pattern:**

```html
<div class="rounded-2xl backdrop-blur-md bg-white/70 border border-white/30 shadow-xl shadow-black/5 p-6">
  <!-- content -->
</div>
```

The UI should feel **lightweight and elegant** rather than heavy or corporate.

---

## 10. Motion Design

Every interaction should feel alive — but never at the cost of performance or accessibility.

**Required motion patterns:**

- ✅ Smooth hover transitions (200ms ease-out)
- ✅ Button ripple / press feedback
- ✅ Card elevation on hover (`hover:-translate-y-1`)
- ✅ Search bar focus expansion
- ✅ Skeleton loading states
- ✅ Animated charts (where applicable)
- ✅ Cross-page fade transitions
- ✅ Property cards lifting slightly on hover
- ✅ Animated map markers (drop-in on load)
- ✅ Modal scale-in from 0.95
- ✅ Drawer slide-in from edge
- ✅ Toast notifications slide from top-right

**Animation constraints:**

- Respect `prefers-reduced-motion` — disable non-essential motion
- Default duration: 150–300ms
- Easing: `cubic-bezier(0.16, 1, 0.3, 1)` (ease-out-expo) preferred
- Use `transform` and `opacity` only — never `width`/`height`/`top`/`left`
- GPU-accelerated; avoid layout thrash

**Tooling:** Tailwind's `transition-*` utilities + `tailwindcss-animate` plugin.

---

## 11. Information Architecture

The platform consists of **three experiences**.

### 11.1 Landing Experience
**Purpose:** Introduce Haven · Build trust · Guide users

The landing page should not overwhelm visitors with features. It should clearly direct users into one of two journeys:

- **Find Property** → opens the Seeker app
- **List Property** → opens the Provider app

Structure: Hero · Two-apps compare table · Trust signals · Testimonial · Final CTA

### 11.2 Provider Experience (`/provider.html`)
**Audience:** Property Owners · Landlords · Landladies · Brokers · Agencies · Developers

**Purpose:** Run their property business.

This experience should feel like a business dashboard. It should expose:
- Listings management (drafts, pending, live, sold)
- Leads inbox
- KYC status
- Payments & subscription
- Broker commission tracking (brokers only)
- Analytics (views, enquiries, conversion)

### 11.3 Seeker Experience (`/seeker.html`)
**Audience:** Buyers · Renters · Investors

**Purpose:** Find properties confidently.

The interface should prioritize:
- Beautiful imagery (large hero, full-bleed photos)
- Intuitive search (location, price, type, features)
- Neighborhood insights (school zones, hospitals, transit)
- Save & compare flows
- Frictionless contact (in-app, with rate limits)

---

## 12. User Experience Principles

Every screen should answer three questions:

1. **Where am I?**
2. **What can I do?**
3. **What should I do next?**

**Additional rules:**

- Never more than one primary CTA per section
- Never more than 7 items in a single nav
- Forms should never have more than 6 visible fields — use steppers
- Empty states must always suggest the next action
- Errors must be specific and actionable ("Phone number must start with 07 or 254", not "Invalid input")
- Loading states must always appear within 100ms of user action
- "Back" must always work

The interface should never feel confusing.

---

## 13. Responsive Requirements

Must work flawlessly on:

| Breakpoint | Width | Priority |
|---|---|---|
| Mobile | 320–639px | **Primary design target** |
| Tablet | 640–1023px | Full support |
| Laptop | 1024–1439px | Full support |
| Desktop | 1440px+ | Full support |
| Ultra-wide | 1920px+ | Graceful expansion (max-width 1600px container) |

**Mobile rules:**

- Bottom navigation, not top
- Touch targets ≥ 44×44px
- Forms full-width, no horizontal scroll
- Hero images served as `srcset` with mobile variants
- Map interactions work with touch (no hover-only UI)

---

## 14. Accessibility

**Minimum WCAG 2.1 AA compliance.**

Required:

- ✅ Keyboard navigation for every interaction
- ✅ Screen reader support (proper ARIA labels, roles, live regions)
- ✅ Color contrast ≥ 4.5:1 for body text, ≥ 3:1 for large text
- ✅ Focus indicators visible at all times (never `outline: none` without replacement)
- ✅ Accessible form labels (`<label for>` not placeholder-only)
- ✅ Error messages announced via `aria-live="polite"`
- ✅ `prefers-reduced-motion` respected — disable non-essential animation
- ✅ `prefers-color-scheme: dark` supported
- ✅ Skip-to-content link
- ✅ Modals trap focus and restore on close
- ✅ No keyboard traps
- ✅ Language attribute on `<html>`

**Testing:** axe-core in CI, manual NVDA / VoiceOver pass before each release.

---

## 15. Performance Targets

| Metric | Target |
|---|---|
| First Contentful Paint (4G) | ≤ 1.2s |
| Largest Contentful Paint (4G) | ≤ 2.0s |
| Time to Interactive (4G) | ≤ 2.5s |
| Total Blocking Time | ≤ 200ms |
| Cumulative Layout Shift | ≤ 0.1 |
| JS bundle (initial) | ≤ 180KB gzipped |
| CSS bundle (initial) | ≤ 40KB gzipped |
| Lighthouse Performance | ≥ 90 |
| Lighthouse Accessibility | ≥ 95 |

**Lazy-load:**

- Images (below the fold, `loading="lazy"`)
- Maps (load on section scroll)
- Video walkthroughs (poster + click-to-play)
- Analytics (deferred)
- Property galleries (virtualised for long lists)

---

## 16. Technical Stack

**Required (current build):**

- HTML5 (semantic)
- **Tailwind CSS** (mandatory — see §7)
- Vanilla JavaScript (ES2020+) — modules where appropriate
- Progressive Web App (manifest, service worker)
- Local storage for prototype data
- Backend-ready API layer (replaceable with REST/GraphQL)

**Acceptable (future):**

- React / Next.js / Vue if complexity warrants
- TypeScript
- Vite or equivalent build tool
- TanStack Query for server state
- Zustand or Jotai for client state
- shadcn/ui as Tailwind component base (if React)

**Forbidden:**

- ❌ Bootstrap or any non-Tailwind CSS framework
- ❌ jQuery
- ❌ Inline styles for anything other than dynamic values
- ❌ Heavy CSS-in-JS solutions that conflict with Tailwind

---

## 17. Kenya Market Specifics

The product is built for Kenya first. All defaults must reflect this.

| Concern | Specification |
|---|---|
| Currency | **KSh** (Kenyan Shilling), formatted `KSh 1,250,000` |
| Primary payment | **M-Pesa** (Daraja STK Push, Paybill, Till) |
| Secondary payment | Card (Visa, Mastercard) via Stripe/Flutterwave |
| Phone validation | Accept `07XX`, `01XX`, `2547XX`, `2541XX` |
| ID validation | National ID 7–8 digits, Alien ID, Passport |
| Brokerage regulator | **EATB** (Estate Agents Registration Board) |
| Tax authority | **KRA** (PIN certificate required for brokers/landlords) |
| Land registry | **Ardhisasa** (Ministry of Lands) — for title search |
| County coverage | All 47 counties (priority: Nairobi, Mombasa, Kisumu, Nakuru, Eldoret) |
| Language | English (primary), Swahili (🟡 future) |
| Time zone | Africa/Nairobi (EAT, UTC+3) |
| Date format | `DD/MM/YYYY` |
| Number format | `1,250,000.00` |

---

## 18. Trust & Safety

**Trust is the product.** Without it, nothing else matters.

**Required trust signals:**

- ✅ "Verified" badge on every verified user/listing
- ✅ KYC mandatory for all listers (no exceptions)
- ✅ Documents stay private — seekers only see a badge
- ✅ Public admin verification (admin code displayed on About page)
- ✅ Activity log of admin actions
- ✅ Dispute resolution process (basic, v2 — see §21)
- ✅ Reporting mechanism on every listing

**Prohibited:**

- ❌ Storing credit card numbers client-side
- ❌ Sharing contact info before plan upgrade
- ❌ Allowing unverified listings to appear in public search
- ❌ Trust badges that can be self-assigned

**Security architecture (see SECURITY.md for full threat model):**

- CSP, HSTS, X-Frame-Options
- Parameterised SQL queries (server-side)
- XSS escape on all user content
- bcrypt / argon2id for passwords
- JWT with refresh tokens
- Rate limiting at edge
- File upload MIME verification (server-side)
- Video re-encoding with ffmpeg
- Audit log append-only, signed

---

## 19. Payments

**M-Pesa first. Card second. Bank transfer third.**

| Flow | Method | Notes |
|---|---|---|
| Listing fee | M-Pesa STK Push | One-time, KSh 1,500 |
| Subscription | M-Pesa STK Push or Card | Recurring, 30-day cycle |
| KYC fee | M-Pesa or Card | One-time, KSh 5,000 |
| Commission payout | M-Pesa B2C | To broker's registered number |
| Seeker upgrade | M-Pesa or Card | Recurring, cancel anytime |

**Provider setup:** M-Pesa Till number for receiving payments, Paybill for B2B.

**Required UX:**

- STK push prompt must be skippable (some users have no signal at signup)
- Failed payments must retry automatically up to 3× with exponential backoff
- Receipts sent via SMS + email
- All transactions in immutable audit log

---

## 20. Future Integrations

The system should be designed to support the following **without frontend redesign**:

| Integration | Use | Status |
|---|---|---|
| M-Pesa Daraja | Live payments | 🟡 Phase 2 |
| Stripe | Card payments | 🟡 Phase 2 |
| Flutterwave | Pan-Africa payments | 🟡 Phase 3 |
| Google Maps | Map upgrade | 🟡 Phase 2 |
| AI valuation | Price suggestions | ❌ Phase 4 |
| OCR document verification | Auto-extract IDs | ❌ Phase 3 |
| Face verification (liveness) | KYC step-up | ❌ Phase 3 |
| Digital contracts (e-signature) | Lease / sale agreements | ❌ Phase 3 |
| Mortgage provider APIs | Pre-qualification | ❌ Phase 4 |
| County land registry APIs | Title verification | ❌ Phase 4 |
| NEMA | Environmental clearance check | ❌ Phase 5 |
| KRA iTax | Tax compliance verification | ❌ Phase 3 |

No major frontend redesign should be required when these integrations land.

---

## 21. Out of Scope (v2)

These are explicitly **NOT** in v2 — clear them to prevent scope creep:

- ❌ Real-time chat (use SMS/in-app notifications in v2)
- ❌ Auctions
- ❌ Vacation rentals / Airbnb-style
- ❌ Property management (rent collection, maintenance tickets)
- ❌ Insurance
- ❌ Multi-currency / international
- ❌ Native iOS / Android apps (PWA only for v2)
- ❌ Crypto payments
- ❌ White-label / agency self-serve platform
- ❌ Tenant credit scoring

---

## 22. Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Scam listings slip through KYC | Medium | Critical | Mandatory video walkthrough + admin review of every listing |
| M-Pesa outage during payment | Medium | High | Fallback to card + retry queue + clear UX |
| Slow 4G in rural Kenya | High | Medium | Aggressive lazy-loading, image compression, PWA offline shell |
| KYC document forgery | Medium | Critical | Liveness check (Phase 3), OCR cross-check with NIIMS |
| Real estate regulatory change | Low | High | Legal review quarterly, modular KYC requirements |
| Provider churn (KYC is friction) | Medium | High | 30-day free trial of Premium, clear value prop in onboarding |
| Map tile provider rate-limit | Low | Medium | Multiple tile providers with failover |
| Insider admin fraud | Low | Critical | Append-only audit log, 2FA required for admin, IP allowlist |

---

## 23. Glossary

| Term | Definition |
|---|---|
| **Haven KE** | The product — Kenya edition |
| **Provider** | A user who lists properties (owner, landlord, broker) |
| **Seeker** | A user who searches for properties (buyer, tenant) |
| **KYC** | Know Your Customer — the verification process |
| **EATB** | Estate Agents Registration Board — Kenya's broker licensing body |
| **KRA PIN** | Kenya Revenue Authority Personal Identification Number |
| **NIIMS** | National Integrated Identity Management System (Huduma Namba) |
| **Ardhisasa** | Kenya's digital land registry platform |
| **NEMA** | National Environment Management Authority |
| **STK Push** | M-Pesa prompt that appears on customer's phone to authorise payment |
| **Till / Paybill** | M-Pesa business receiving numbers |
| **B2C** | Business-to-Customer payment (e.g. commission payout) |
| **Tier (commission)** | The 2%–6% band a closed deal falls into, based on price |
| **Listing doc** | Required document (title deed, rental rules, etc.) attached to a listing |
| **Walkthrough video** | Non-paused ≥30s video of the property |
| **Verified badge** | Green checkmark shown to seekers; means KYC + admin review passed |
| **Commission** | Broker earnings on a closed deal (2%–6% + 1% for rentals) |
| **PWA** | Progressive Web App — installable from browser, works offline |

---

## 24. Definition of Done

A feature is **complete** only if it:

- [ ] Matches the approved UI design
- [ ] Works on mobile (320px) and desktop (1440px) without horizontal scroll
- [ ] Includes loading, empty, success, and error states
- [ ] Is keyboard-accessible
- [ ] Passes axe-core with zero violations
- [ ] Uses the Tailwind design system (no handcrafted CSS unless approved)
- [ ] Respects `prefers-reduced-motion` and `prefers-color-scheme`
- [ ] Preserves the Haven visual identity
- [ ] Has been tested on real Chrome, Safari, and Firefox
- [ ] Has been tested with a real M-Pesa sandbox (where applicable)
- [ ] Has been code-reviewed
- [ ] Has at least one unit test for the core logic
- [ ] Is documented in TECHNICAL.md
- [ ] Is production-ready, not a prototype

---

## 25. Approval

| Role | Name | Date | Signature |
|---|---|---|---|
| Product Lead | _________ | _________ | _________ |
| Engineering Lead | _________ | _________ | _________ |
| Design Lead | _________ | _________ | _________ |
| Compliance / Legal | _________ | _________ | _________ |

**Change log:**

- **v2.0** (Jul 2025) — Initial PRD. Consolidates vision, design language, technical stack. Establishes Tailwind as mandatory. Supersedes earlier ad-hoc implementation docs.

---

*End of PRD — see `/TECHNICAL.md` for implementation details.*