Full-Stack Development - Intelligent Accommodation Platform

### PROJECT BRIEF: Intelligent Student Accommodation Platform

**Client:** Legacy Heights Student Accommodation Management
**Contractor Role:** Lead Full-Stack Developer / Systems Engineer
**Platform Foundation:** WordPress (Custom Application Layer / Plugin Architecture)
**Target Implementation Lifecycle:** 18 Weeks 

### 1. Project Overview & Core Philosophy

The objective is to engineer a secure, integrated accommodation platform managing the complete student tenancy lifecycle: Registration → Application → KYC Verification → Room Selection → Reservation Hold → Payment → Lease Execution → Occupancy Maintenance & Support. 

**Critical Constraint:** This is not a "plugin-heavy" brochure site. You will build a dedicated, purpose-built business logic plugin layer atop WordPress to serve as the application engine. Third-party tools or AI services must have restricted boundaries; sensitive records must be mediated securely through authenticated application permission checks. 

### 2. Core Functional Modules

### A. Authentication & Tenant Portal

* Secure registration matching student roles, email/mobile verification, and multi-factor authentication (MFA) capabilities.
* Student dashboards showing booking statuses, live financial ledger, room details, and lease tracking.
* Integrated maintenance ticket portal and native support channel.

### B. Room Inventory & Concurrency Management

* Hierarchical asset engine managing Buildings, Floors, Rooms, and Individual Beds.
* Real-time availability tracking linked to interactive SVG floor plans.
* **Concurrency Lock Engine:** Implementation of an application-level 15-minute room reservation hold during payment windows. Expired holds must safely execute auto-release logic to eliminate double-booking anomalies.

### C. Online KYC & Private Vaulting

* Upload and validation workflow for National IDs, admissions letters, proofs of residence, and sponsorship documents.
* **Security Isolation:** Sensitive documents must strictly bypass the standard WordPress Media Library. They must stream directly to private, access-controlled cloud object storage. Access must be granted solely via short-lived, authenticated temporary links.

### D. Financial Engine & Paynow Integration

* Full transaction ledger for deposits, rent, utilities, and penalties.
* Deep integration with the Paynow Zimbabwe API to track transaction callbacks, loops, and failed payment statuses.

### E. Digital Lease Engine

* Automated population of approved lease templates using tenant-validated metadata.
* E-signing integration workflow for digital validation, along with a secure administrative interface to upload manually scanned leases.

### F. Maintenance Dispatch & Operations

* Support ticket intake with automated categorization (Plumbing, Electrical, Carpentry, etc.).
* Priority matrix rules (Normal, High, Critical) with structural workflows triggering escalation alerts for life-safety or severe property hazards (e.g., flooding).

### 3. Targeted AI Augmentation Layer

The platform utilizes specialized AI endpoints functioning strictly as sandboxed advisory agents under clear security constraints: 

* **AI Student/Lease Assistant:** Natural-language interaction helping tenants parse lease dates, rules, or account balances via authenticated context boundaries.
* **AI Maintenance Assistant:** Translates raw student support requests into structured IT/property maintenance tickets with recommended prioritization.
* **AI Payment Reconciliation:** Uses OCR to parse user-submitted payment confirmations, cross-referencing references and amounts against pending invoices. *Constraint: AI cannot settle balances autonomously; it returns confidence flags for final human-finance approval.*
* **AI Management Assistant:** Allows authorized executives to use natural language to query metrics regarding occupancy trends, revenue collection, and outstanding debtors.

### 4. Administrative RBAC Layout

Implement explicit Role-Based Access Controls to secure the operational suite: 

* **Accommodation Team:** Validates registrations, manages KYC processing, manages room allocation, and executes check-in schedules.
* **Finance Team:** Controls invoices, monitors Paynow returns, inspects proof-of-payment suggestions, and runs aging debtor reports.
* **Property Management:** Tracks asset conditions, resolves maintenance tasks, and monitors recurring building issues.
* **System Administrator:** Oversees global security parameters, verifies API integrations, checks audit logs, and monitors routine backups.

### 5. Execution Timeline & Milestone Structure

The contractor must follow this rigid 18-week software delivery sprint schedule: 

* **Weeks 1–4: Discovery & Framework Foundation**
Finalize target data models, design database architecture schemas, setup RBAC structures, and instantiate the custom application plugin base.
* **Weeks 5–8: Inventory Booking & Paynow Integration**
Build asset engines, embed interactive SVG map selectors, program the 15-minute lock logic, and complete the Paynow integration loop.
* **Weeks 9–12: KYC Vaulting & Lease automation**
Deploy the private object storage bucket connector, create document review states, and integrate the dynamic lease generation engine.
* **Weeks 13–15: Sandboxed AI & Messaging Gateways**
Build out the AI assistants, tune OCR validation prompts, connect Zimbabwean SMS channels, and establish official WhatsApp Business APIs.
* **Weeks 16–18: Hardening, UAT, and Deployment**
Conduct intense code reviews, verify data security isolation barriers, simulate stress testing on payment calls, and coordinate final deployment.

### 6. Contractor Deliverables & Handover Code Requirements

* Full production-ready deployment to target cloud hosting environment.
* Exhaustive test suite verification covering: system permission boundaries, application race-conditions on bookings, data boundary sandboxing for AI, and validation of backup/disaster-recovery loops.
* Handover of clean, well-commented source code with full repository ownership transferred to the client.
* Structured architectural documentation including API mapping, database schemas, and administrative deployment manuals.