integratedhub/TODO.md

TODO - Lease Approval Workflow

Completed Components

1. Database Schema ✅

• Added 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
• Created migration SQL file: drizzle/0008_add_lease_approval_fields.sql
• Updated database interfaces in db/schema.ts

2. API Endpoints ✅

• Created POST /api/lease/request-approval - Tenant initiates lease
• Created POST /api/lease/approve - Landlord approval
• Created POST /api/lease/reject - Landlord rejection
• Created GET /api/lease/pending-approvals - Landlord dashboard
• Extended leaseService.ts with approval functions:
  • requestLeaseApproval()
  • approveLease()
  • rejectLease()
  • getPendingApprovals()

3. Tenant Invitation Page ✅

• Updated /tenant/invite/[invite_id].tsx to check lease status
• Added status-based UI states:
  • No lease: "Start Lease" button
  • Pending: "Pending Landlord Approval"
  • Approved: "Lease Approved - Continue"
  • Rejected: "Lease Rejected" with contact info
• Added progress indicator showing approval steps
• Updated POST handler to call approval API

4. Landlord Service ✅

• Added getPendingLeaseApprovals() function in landlordService.ts

---

Incomplete / Needs Work

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 completing each component, run:

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 Create

• 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