# Lease Approval Implementation Plan

## Overview
Implement landlord approval mechanism for tenant invitation workflow. Currently, tenants can click "Start Lease" without landlord oversight. This plan adds proper approval workflow.

## Implementation Tasks

### 1. Database Schema Changes (HIGH PRIORITY)
- [ ] Add approval workflow fields to `leases` table:
  - `approval_status` TEXT DEFAULT 'pending_approval'
  - `approval_requested_at` BIGINT
  - `approved_at` BIGINT  
  - `approved_by` TEXT REFERENCES users(id)
  - `rejection_reason` TEXT
- [ ] Create migration SQL file
- [ ] Update database interfaces

### 2. API Endpoints (HIGH PRIORITY)
- [ ] Create `POST /api/lease/request-approval` - Tenant initiates lease
- [ ] Create `POST /api/lease/approve` - Landlord approval
- [ ] Create `POST /api/lease/reject` - Landlord rejection
- [ ] Create `GET /api/lease/pending-approvals` - Landlord dashboard
- [ ] Extend `leaseService.ts` with approval functions:
  - `requestLeaseApproval()`
  - `approveLease()`
  - `rejectLease()`
  - `getPendingApprovals()`

### 3. Lease Finalization Mechanism (HIGH PRIORITY)
- [ ] Implement lease activation on approval
- [ ] Ensure proper record linking (tenant_id, lease_id)
- [ ] Update tenant invite to reference approved lease
- [ ] Set up access rights and permissions
- [ ] Create payment schedules and reminders
- [ ] Validate data integrity

### 4. Tenant Invitation Page Updates (MEDIUM PRIORITY)
- [ ] Update `/tenant/invite/[invite_id].tsx` to check lease status
- [ ] Add status-based UI states:
  - No lease: "Start Lease" button
  - Pending: "Pending Landlord Approval" 
  - Approved: "Lease Approved - Continue"
  - Rejected: "Lease Rejected" with contact info
- [ ] Add progress indicator showing approval steps
- [ ] Update POST handler to call approval API

### 5. Landlord Notifications (MEDIUM PRIORITY)
- [ ] Create `notificationService.ts` for centralized notifications
- [ ] Implement email templates:
  - "New Lease Approval Required"
  - "Lease Approved" confirmation
  - "Lease Rejected" confirmation
- [ ] Add dashboard notifications
- [ ] Integrate with user preference system

### 6. Landlord Dashboard View (MEDIUM PRIORITY)
- [ ] Add "Pending Lease Approvals" section to dashboard
- [ ] Create approval cards with property/tenant details
- [ ] Add approval/rejection interface
- [ ] Update navigation with approval badge
- [ ] Create dedicated `/landlord/approvals` page

### 7. Testing (LOW PRIORITY)
- [ ] Unit tests for lease service functions
- [ ] Integration tests for API endpoints
- [ ] E2E tests for complete approval workflow
- [ ] UI tests for dashboard and invite page

## Verification Steps
After each major component, run:
```bash
deno check <modified_ts_file>
deno fmt <modified_ts_file>
deno lint <modified_ts_file>
```

Note: `deno check` only works on TypeScript files (.ts), not Markdown files (.md).

## Workflow Summary
1. Tenant clicks "Start Lease" → Creates lease with `approval_status: 'pending_approval'`
2. Landlord receives notification → Dashboard shows pending approval
3. Landlord reviews and approves/rejects → Updates lease status
4. System finalizes lease → Links records, sets up payments, grants access

## Files to Modify
- `db/schema.ts` - Add approval fields
- `services/leaseService.ts` - Add approval functions
- `routes/tenant/invite/[invite_id].tsx` - Update UI and logic
- `routes/landlord/dashboard/index.tsx` - Add pending approvals
- `routes/api/lease/` - Create approval endpoints
- `services/notificationService.ts` - New notification service

## Success Criteria
- [ ] All lease activations require landlord approval
- [ ] Tenants see clear approval status
- [ ] Landlords can easily review and approve/reject
- [ ] Notifications are sent reliably
- [ ] Lease finalization works correctly
- [ ] All tests pass