docs: Add comprehensive TODO.md for lease approval workflow (#130)

* Apply patch [skip ci]

* Apply patch [skip ci]

* Empty commit to trigger CI

---------

Co-authored-by: open-swe-dev-andrinoid[bot] <open-swe-dev-andrinoid@users.noreply.github.com>

TODO.md

@@ -1,99 +1,233 @@
-# Lease Approval Implementation Plan
+# TODO - Lease Approval Workflow
 
-## Overview
+## Completed Components
-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 ✅
 
-### 1. Database Schema Changes (HIGH PRIORITY)
+- [x] Added approval workflow fields to `leases` table:
-- [ ] 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
+- [x] Created migration SQL file: `drizzle/0008_add_lease_approval_fields.sql`
-- [ ] Update database interfaces
+- [x] Updated database interfaces in `db/schema.ts`
 
-### 2. API Endpoints (HIGH PRIORITY)
+### 2. API Endpoints ✅
-- [ ] Create `POST /api/lease/request-approval` - Tenant initiates lease
+
-- [ ] Create `POST /api/lease/approve` - Landlord approval
+- [x] Created `POST /api/lease/request-approval` - Tenant initiates lease
-- [ ] Create `POST /api/lease/reject` - Landlord rejection
+- [x] Created `POST /api/lease/approve` - Landlord approval
-- [ ] Create `GET /api/lease/pending-approvals` - Landlord dashboard
+- [x] Created `POST /api/lease/reject` - Landlord rejection
-- [ ] Extend `leaseService.ts` with approval functions:
+- [x] Created `GET /api/lease/pending-approvals` - Landlord dashboard
+- [x] Extended `leaseService.ts` with approval functions:
   - `requestLeaseApproval()`
   - `approveLease()`
   - `rejectLease()`
   - `getPendingApprovals()`
 
-### 3. Lease Finalization Mechanism (HIGH PRIORITY)
+### 3. Tenant Invitation Page ✅
-- [ ] 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)
+- [x] Updated `/tenant/invite/[invite_id].tsx` to check lease status
-- [ ] Update `/tenant/invite/[invite_id].tsx` to check lease status
+- [x] Added status-based UI states:
-- [ ] 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
+- [x] Added progress indicator showing approval steps
-- [ ] Update POST handler to call approval API
+- [x] Updated POST handler to call approval API
 
-### 5. Landlord Notifications (MEDIUM PRIORITY)
+### 4. Landlord Service ✅
-- [ ] 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)
+- [x] Added `getPendingLeaseApprovals()` function in `landlordService.ts`
-- [ ] 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
+## Incomplete / Needs Work
-- [ ] E2E tests for complete approval workflow
+
-- [ ] UI tests for dashboard and invite page
+### 1. Notification Service ❌ (HIGH PRIORITY)
+
+**Status:** File does not exist
+
+**Tasks:**
+
+- [ ] Create `services/notificationService.ts` for centralized notifications
+- [ ] Implement `sendLeaseApprovalRequest()` function
+- [ ] Implement `sendLeaseApproved()` function
+- [ ] Implement `sendLeaseRejected()` function
+- [ ] Integrate with user `notification_preferences_json` system
+- [ ] Follow `messageService.ts` pattern for E2E fixture support
+- [ ] Add E2E fixture functions in `services/e2eFixtures.ts`
+
+**Integration Points:**
+
+- Call `sendLeaseApprovalRequest()` in `routes/api/lease/request-approval.ts`
+- Call `sendLeaseApproved()` in `routes/api/lease/approve.ts`
+- Call `sendLeaseRejected()` in `routes/api/lease/reject.ts`
+
+### 2. Landlord Dashboard Updates ⚠️ (HIGH PRIORITY)
+
+**Status:** Dashboard exists but missing "Pending Lease Approvals" section
+
+**Current State:**
+
+- Dashboard has "Pending Applications" section (for tenant applications)
+- Dashboard does NOT have "Pending Lease Approvals" section
+- `getPendingLeaseApprovals()` function exists in `landlordService.ts` but is
+  not used
+
+**Tasks:**
+
+- [ ] Add "Pending Lease Approvals" section to
+      `routes/landlord/dashboard/index.tsx`
+- [ ] Call `getPendingLeaseApprovals()` from `landlordService.ts`
+- [ ] Display approval cards with property/tenant details
+- [ ] Include approve/reject buttons calling `/api/lease/approve` and
+      `/api/lease/reject`
+- [ ] Use existing card styling pattern from dashboard
+- [ ] Add navigation badge for pending approvals count
+
+### 3. Dedicated Approvals Page ❌ (MEDIUM PRIORITY)
+
+**Status:** Page does not exist
+
+**Tasks:**
+
+- [ ] Create `routes/landlord/approvals/index.tsx`
+- [ ] Fetch pending approvals via `/api/lease/pending-approvals`
+- [ ] Display detailed property and tenant information
+- [ ] Provide approve/reject forms with optional rejection reason
+- [ ] Follow Fresh page pattern from `routes/landlord/dashboard/index.tsx`
+- [ ] Add navigation link in landlord menu
+
+### 4. E2E Tests ❌ (MEDIUM PRIORITY)
+
+**Status:** Test file exists but doesn't test approval workflow
+
+**Current State:**
+
+- `tests/e2e/lease-creation.spec.ts` exists
+- Tests lease acceptance workflow but NOT approval workflow
+
+**Tasks:**
+
+- [ ] Create or update `tests/e2e/lease-approval.spec.ts`
+- [ ] Test complete workflow: tenant requests, landlord views/approves, tenant
+      sees status
+- [ ] Use patterns from `tests/e2e/invite-tenant.spec.ts` and `helpers.ts`
+- [ ] Test approval status transitions (pending → approved/rejected)
+- [ ] Test notification triggers (when notification service is implemented)
+- [ ] Test error cases (unauthorized, invalid lease_id, etc.)
+
+### 5. API Endpoint Validation ⚠️ (LOW PRIORITY)
+
+**Status:** Endpoints exist but may need improvements
+
+**Tasks:**
+
+- [ ] Verify `routes/api/lease/request-approval.ts` has proper error handling
+- [ ] Verify `routes/api/lease/approve.ts` has proper error handling
+- [ ] Verify `routes/api/lease/reject.ts` has proper error handling
+- [ ] Check `routes/api/lease/pending-approvals.ts` returns correct data
+      structure
+- [ ] Add input validation and error messages
+- [ ] Add notification calls when notification service is ready
+
+### 6. Lease Finalization Verification ⚠️ (LOW PRIORITY)
+
+**Status:** Basic implementation exists, needs verification
+
+**Tasks:**
+
+- [ ] Verify `inviteLease()` in `leaseService.ts` properly links to approved
+      lease
+- [ ] Ensure tenant access rights are set up after approval
+- [ ] Validate payment schedules are created on approval
+- [ ] Test data integrity after approval workflow
+- [ ] Verify lease status transitions correctly (draft → active)
+
+---
+
+## Issues Discovered During Development
+
+### 1. Missing Notification Integration
+
+**Issue:** API endpoints for approve/reject don't send notifications **Impact:**
+Landlords and tenants won't receive email/dashboard notifications **Fix
+Required:** Implement notification service and integrate with endpoints
+
+### 2. Dashboard Missing Pending Approvals Section
+
+**Issue:** Landlord dashboard doesn't show pending lease approvals **Impact:**
+Landlords must navigate to a separate page to see approvals **Fix Required:**
+Add pending approvals section to dashboard
+
+### 3. No Dedicated Approvals Page
+
+**Issue:** `/landlord/approvals` route doesn't exist **Impact:** No centralized
+location for landlords to manage approvals **Fix Required:** Create dedicated
+approvals page
+
+### 4. Incomplete E2E Test Coverage
+
+**Issue:** No E2E tests for the complete approval workflow **Impact:** Difficult
+to verify end-to-end functionality **Fix Required:** Add comprehensive E2E tests
+
+### 5. Variable Naming Consistency
+
+**Issue:** Potential naming inconsistencies between services **Impact:** May
+cause confusion during maintenance **Fix Required:** Review and standardize
+variable names across files
+
+---
 
 ## Verification Steps
-After each major component, run:
+
+After completing each 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).
+**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'`
+
+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
+## Files to Create
-- `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
+- `routes/landlord/approvals/index.tsx` - Dedicated approvals page
+- `tests/e2e/lease-approval.spec.ts` - E2E tests for approval workflow
+
+## Files to Modify
+
+- `routes/landlord/dashboard/index.tsx` - Add pending approvals section
+- `routes/api/lease/approve.ts` - Add notification call
+- `routes/api/lease/reject.ts` - Add notification call
+- `routes/api/lease/request-approval.ts` - Add notification call
+- `services/e2eFixtures.ts` - Add notification E2E fixtures
+
+---
 
 ## 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
+- [ ] Dashboard shows pending approvals
+- [ ] Dedicated approvals page exists