diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..132ffa0 --- /dev/null +++ b/PRD.md @@ -0,0 +1,590 @@ +# Denya OneCare — Integrated Build Specification + +> **Merged Design:** Denya Rentals original proposal + Wahab's Product Specification Document +> **Version:** 1.0 | **Date:** July 16, 2026 +> **Status:** Awaiting CEO/team review before build + +--- + +## 1. Product Identity + +| Attribute | Value | +|-----------|-------| +| **Product Name** | **Denya OneCare** (formerly "Issue Tracking System") | +| **Tagline** | Integrated Customer Complaint, Facilities Management & Executive Reporting Platform | +| **Owner** | Denya Developers | +| **Site** | Pavilion, Accra — East & West buildings | +| **Scale** | Est. $609K/yr revenue, 83% margin | + +--- + +## 2. The Problem (Still True) + +Maintenance issues and tenant requests at Pavilion are managed across three WhatsApp groups. Key issues: + +- ❌ No formal tracking — issues buried in chat scroll +- ❌ No ownership assignment — @mentions rely on people seeing them +- ❌ No status visibility — impossible to tell open vs resolved +- ❌ No priority system — urgent electrical vs routine cleaning treated the same +- ❌ No SLA monitoring — response time targets unenforceable +- ❌ No reporting — can't spot recurring issues or technician workload +- ❌ Media/photos critical to diagnosis but get lost +- ❌ Accountability gap — no escalation if no one responds +- ❌ No audit trail — who did what, when, and how + +--- + +## 3. Business Objectives + +The system will: + +- Centralize all maintenance requests and customer complaints +- Improve customer satisfaction through structured follow-up +- Reduce response and resolution times via clear assignments +- Increase technician accountability through tracked workflows +- Automate escalation when SLAs are missed +- Produce real-time management and executive dashboards +- Provide CEO-level analytics for strategic decisions +- Maintain a complete audit history of every issue + +--- + +## 4. User Roles & Team Structure + +### Org Chart + +``` + Scott Murray (CEO) + | + Jerome Tabiri + (Service Provider / Operations Lead) + | + Akua / Mercy Duah + (Head of Customer Service) + / \ + Nicholas (FM) Bella (CS) + FM Dispatcher & QC Sup. CS Representative + + Collins (Cleaning Ops) + Ama (Escalation Support) + | | + ┌────────┼────────┐ ┌──────┴──────┐ + Prosper Sam Steven Agents Tenants + | | | (report) (report) + Junior Francis Desmond + (Samuel) Afful +``` + +### Role Types in the System + +| Role | Type | People | Responsibilities | +|------|------|--------|------------------| +| **Tenant/Guest** | External | End customer | Report issues via agent or self-service QR | +| **Homeowner** | External | Property owner | View property maintenance history | +| **Property Agent** | External | Agencies group | Front-line issue reporting, check-in/out notices | +| **CS Representative** | Internal | Bella | Receive complaints, verify info, create tickets, close verified issues | +| **CS Manager** | Internal | Akua/Mercy | Oversee CS team, manage escalations (manager-level, not admin) | +| **FM Dispatcher** | Internal | Nicholas | Triage, assign technicians, order parts, QC, verifications | +| **Project Lead / Admin** | Internal | Jerome | Full system admin — all actions, user management, delete tickets, SLA oversight | +| **Project Lead / Admin** | Internal | Wahab | Full system admin — all actions, close/reopen tickets, user management, final QA oversight | +| **Technician** | Internal | Prosper, Sam, Steven, Junior, Francis, Desmond, Afful | Execute repairs, update via WhatsApp | +| **Contractor** | External | Occasional external hires | Limited-duration assignments | +| **CEO** | Executive | Scott | Read-only analytics, strategic KPIs | +| **Directors** | Executive | Operations, Finance, Property | Tailored dashboards per domain | + +--- + +## 5. End-to-End Workflow + +### High-Level Flow + +``` +Customer Complaint +↓ +Ticket Created (auto-numbered: PAV-YYYY-MM-NNN) +↓ +CS Review (Bella validates info) +↓ +Triage & Categorization (Nicholas sets category + priority | Wahab oversees) +↓ +Technician Assigned +↓ +Execution (with optional escalation branch) +↓ +On-Field Verification (Nicholas or Bella checks fix on site) +↓ +Wahab Review (final QA oversight) +↓ +Close Ticket +↓ +48-Hour Internal Follow-up (flagged to Wahab/Nicholas) +↓ +Archive → Executive Reporting +``` + +### Detailed Ticket Lifecycle (15 Statuses) + +| # | Status | Description | Who Sets | +|---|--------|-------------|----------| +| 1 | **New** | Complaint received (pre-log) | System | +| 2 | **Logged** | Ticket created with auto-number | Bella / Agent | +| 3 | **Triage** | Awaiting categorization and priority | Nicholas | +| 4 | **Assigned** | Assigned to a specific technician | Nicholas | +| 5 | **Accepted** | Technician acknowledged via `#ack` | Technician | +| 6 | **Travelling** | Technician en route to site | Technician via WhatsApp | +| 7 | **On Site** | Technician arrived at unit | Technician via WhatsApp | +| 8 | **In Progress** | Repair actively ongoing | Technician via `#update` | +| 9 | **Waiting Parts** | Awaiting materials or spare parts | Technician via `#part` | +| 10 | **Escalated** | Raised for management review (override, structural, prolonged) | Nicholas / Technician | +| 11 | **Completed** | Technician finished the repair | Technician via `#done` | +| 12 | **On-Field Verification** | Nicholas or Bella physically/virtually checks the fix on site | Nicholas/Bella | +| 13 | **Wahab Review** | Final QA oversight and closure approval | Wahab | +| 14 | **Closed** | Ticket officially closed | Wahab / Nicholas | +| 15 | **Reopened** | Issue resurfaces within 7 days | Agent / System | + + +### Step-by-Step Detail + +1. **Reporting** — Guest/tenant has an issue → tells their Agent OR calls CS → Agent posts in AGENCIES WhatsApp group OR Bella enters via web dashboard. **Source of complaint is tracked** (WhatsApp, Phone, Agent, Walk-in, QR Code — added when ticket is created). +2. **Triage** — **Nicholas** triages FM issues (categories, priority, technician assignment). **Bella** triages CS issues. **Wahab** oversees follow-ups and verification. Each ticket is categorized and assigned to the right person. +3. **Assignment** — System sends WhatsApp message to the technician: `🔧 New Issue PAV-001 | Unit 505E | Plumbing: WC not flushing | Priority: 🟠 High | Reply or send #ack to confirm` +4. **Acknowledgment** — Technician replies `#ack` or just responds → status moves to Accepted +5. **Execution** — Technician works on issue. Sends `#update` or voice note with progress update. +6. **Parts Needed** (if applicable) — Technician sends `#part 505E need flush valve model X` → status → Waiting Parts. Nicholas sees and orders/checks stock. +7. **Completion** — Technician sends `#done 505E WC fixed` → status → Completed +8. **On-Field Verification** — Nicholas or Bella physically/virtually checks the fix on site → status → On-Field Verification +9. **Wahab Review** — Wahab does final QA oversight in dashboard → status → Wahab Review → approves or sends back +10. **Auto Follow-up** (48 hours later — internal only) — System flags ticket for Wahab/Nicholas: `Issue PAV-001 (505E WC) — resolved 48h ago. Any follow-up needed?` → If issue resurfaces → auto-reopens, escalates to Ama + +### Reopening & Reassignment + +- **Reopening:** If a verified-closed issue resurfaces within 7 days, the gatekeeper can Reopen it. A reopened issue auto-escalates to Ama. +- **Reassignment:** A technician who cannot complete a job can request: `#reassign PAV-001 [technician name]` → Nicholas receives notification and approves/reassigns in dashboard. + +--- + +## 6. Issue Ticket Data Model + +Each ticket stores the following 24+ fields: + +| # | Field | Type | Required | Notes | +|---|-------|------|----------|-------| +| 1 | Ticket Number | Auto | ✓ | Format: `PAV-YYYY-NNNNN` | +| 2 | Date | Auto | ✓ | Creation date | +| 3 | Time | Auto | ✓ | Creation time | +| 4 | Customer Name | Text | ✓ | Guest/tenant name | +| 5 | Property | Select | ✓ | Pavilion East / Pavilion West | +| 6 | Apartment | Select | ✓ | e.g., 102E, 505W (from apartment_mapping.json) | +| 7 | Reporter | Text | ✓ | Who reported it (agent, CS, tech) | +| 8 | Phone | Text | | Contact number | +| 9 | Email | Text | | Contact email | +| 10 | Issue Category | Select | ✓ | See complaint categories below | +| 11 | Priority | Select | ✓ | 🔴 Urgent / 🟠 High / 🟡 Medium / 🟢 Low | +| 12 | Description | Text | ✓ | What's wrong | +| 13 | Photos (Before) | Image[] | | Up to 5 images | +| 14 | Voice Notes | Audio | | Technician voice updates | +| 15 | Assigned Technician | Select | ✓ | Prosper, Sam, Steven, Junior, Francis, Desmond, Afful, or contractor | +| 16 | ETA | DateTime | | Expected resolution time | +| 17 | SLA | Text | | SLA tier + deadline (auto-calculated) | +| 18 | Resolution Notes | Text | | How it was fixed | +| 19 | Cost | Decimal | | Parts + labor cost | +| 20 | Spare Parts Used | Text | | e.g., "flush valve X1, seal X1" | +| 21 | Photos (After) | Image[] | | Proof of completion | +| 22 | Customer Rating | 1-5 | | From 48-hour follow-up | +| 23 | Close Date | Auto | | Timestamp of final closure | +| 24 | Reopen Count | Integer | Auto | Tracks chronic issues at same unit | +| 25 | Related Issues | Link[] | | Cross-reference to linked tickets | +| 26 | Escalated To | Text | | Who was it escalated to | + +--- + +## 7. Complaint Categories + +### Maintenance + +| Category | Sub-categories | +|----------|----------------| +| 🔧 **Plumbing** | WC not flushing, leaky tap, pipe burst, blocked drain, water heater | +| ⚡ **Electrical** | No power, tripped breaker, light fitting, socket repair, voltage issues | +| ❄️ **HVAC** | AC not cooling, AC leaking, thermostat, fan not working | +| 🛋️ **Furniture** | Broken bed, chair, table, wardrobe | +| 🔌 **Appliances** | Fridge, washing machine, microwave, TV, kettle | +| 🧹 **Cleaning** | Deep clean requested, post-checkout turnover, common area | +| 🐜 **Pest Control** | Insects, rodents, fumigation | +| 🔒 **Security** | Lock broken, door not closing, window latch, CCTV | +| 🌐 **Internet** | WiFi down, slow speed, router reset | +| 🏗️ **Structural** | Wall crack, ceiling leak, floor tile, paint touch-up | + +### Customer Service + +| Category | Description | +|----------|-------------| +| 🔑 **Check-in** | Early check-in, key handover, welcome instructions | +| 🔑 **Check-out** | Late checkout, key return, inspection | +| 🧹 **Housekeeping** | Mid-stay cleaning, linen change, restocking | +| 🎒 **Lost Property** | Guest left items behind | +| 💳 **Billing** | Invoice, payment issue, deposit query | +| 👤 **Staff Behaviour** | Staff conduct feedback | + +### Emergency (Auto-Alert to ALL gatekeepers + Jerome) + +| Category | Examples | +|----------|----------| +| 🔥 **Fire** | Smoke, fire, sprinklers | +| 🌊 **Flood** | Major water leak, burst pipe, overflowing | +| ⛽ **Gas Leak** | Gas smell, suspected leak | +| ⚡ **Electrical Hazard** | Sparking, exposed wires, power outage affecting multiple units | + +--- + +## 8. WhatsApp Interface (Field Team) + +Technicians use simple text commands **or reply directly to notification messages**: + +| Action | Command | Voice Note? | Status Change | +|--------|---------|-------------|---------------| +| Acknowledge | `#ack` or just reply | ✓ Yes | → Accepted | +| On the way | `#enroute` | ✓ Yes | → Travelling | +| Arrived | `#onsite` | ✓ Yes | → On Site | +| Update progress | `#update [note]` | ✓ Yes | → In Progress | +| Request part | `#part [what's needed]` | ✓ Yes | → Waiting Parts | +| Mark complete | `#done [note]` or reply "Done" | ✓ Yes | → Completed | +| Request reassignment | `#reassign [tech name]` | ✓ Yes | → Triage (notify Nicholas) | +| List my issues | `#myissues` | — | Returns active list | +| Check status | `#status [unit]` | — | Returns current status | +| Help | `#help` | — | Returns command cheat sheet | + +> **Key design choice:** The technician can simply **reply to the WhatsApp notification message** and the bot infers the issue context. No need to remember issue IDs for most actions. +> +> **Decision (July 19):** Text-only for POC (`#ack`, `#done`, `#update`, `#part`, etc.). Voice note support planned for Phase 2 (long-term). + +--- + +## 9. Dashboard Modules + +### 9.1 Customer Service Dashboard (Bella, Akua/Mercy) + +| Card | Metric | +|------|--------| +| 🆕 New complaints today | Count | +| 📋 Open tickets | Count by priority | +| ⏳ Waiting customers | Oldest unassigned | +| 🔝 Escalated tickets | Count + list | +| ⚡ Average response time | Hours:Minutes | +| ✅ SLA compliance | % met today | +| 📊 Recent tickets | Sortable table (Newest first) | + +### 9.2 Facilities Dashboard (Nicholas, Jerome) + +| Card | Metric | +|------|--------| +| 👥 Technician workload | Jobs per tech (active) | +| 📍 Jobs by building | East vs West distribution | +| 📅 Jobs due today | Count + list | +| ⌛ Waiting parts | Tickets stuck at parts | +| 🚨 Emergency jobs | Count + red alert | +| 🗺️ GPS technician location | Map view (Phase 2) | +| 📊 Aging analysis | <24h, 2d, 5d, Overdue | + +### 9.3 Procurement Dashboard (Nicholas, Jerome) + +| Card | Metric | +|------|--------| +| 📦 Parts requested | Open requests | +| 💰 Outstanding purchases | Value + count | +| 🏪 Vendor performance | Avg delivery time, reliability | +| ⚠️ Stock shortages | Items below threshold | +| 📋 Pending approvals | Awaiting sign-off | + +### 9.4 CEO Dashboard (Scott — Read-Only Executive View) + +**Executive KPI Cards:** + +| KPI | Type | +|-----|------| +| Total Open Tickets | Number | +| Critical Tickets | Number (Red) | +| SLA Compliance % | % with color threshold | +| Customer Satisfaction Score | Average 1-5 | +| Average Response Time | Hours:Minutes | +| Average Resolution Time | Hours:Minutes | +| First-Time Fix Rate | % (closed without revisit) | +| Cost of Maintenance | $ this month | +| Repeat Issues | % of tickets that are reopens | +| Revenue Impact | Est. lost revenue from complaints | +| Technician Productivity | Jobs per tech this period | +| Preventive vs Reactive | % split | + +**Interactive Charts:** + +- Complaints by Property — Pavilion East vs West +- Complaints by Category — Plumbing, Electrical, Cleaning, HVAC, etc. +- Complaints by Apartment — Top 20 recurring units +- Technician Performance — Jobs completed, avg repair time, customer rating +- Monthly Trends — 12-month complaint trend line +- Heat Map — Buildings with highest incident density +- Root Cause Analysis — Top recurring failure modes +- Cost Analysis — Maintenance expenditure by property, month-over-month + +**Executive Risk Indicators (Red/Yellow/Green):** + +- 🚨 Open emergencies +- 🔄 Reopened tickets this week +- ⏰ Overdue jobs (beyond SLA) +- ⚠️ Critical equipment failures (AC, generator, water pump) +- 📋 Pending approvals older than 48h + +### 9.5 Director Dashboards (Tailored Views) + +**Operations Director:** SLA compliance, open jobs, staff utilization, delayed work orders + +**Finance Director:** Cost per property, total maintenance spend, vendor invoices pending, budget variance + +**Property Director:** Tenant satisfaction scores, complaint frequency per building, occupancy impact, property performance trends + +--- + +## 10. QR Code Integration + +Every apartment receives QR codes at the entrance or near the main appliance area. + +**Scanning opens a mobile-optimized page with:** + +- 🏠 Apartment profile (unit, building, floor plan) +- 📖 Appliance manuals (PDF links for fridge, AC, washer, TV, etc.) +- 🔧 Troubleshooting guides (common fixes for known issues) +- 📋 Maintenance history (past issues reported at this unit) +- 🚨 Report Issue (opens quick complaint form) + +**Benefits:** +- Guests can self-serve for minor troubleshooting → fewer calls to agents +- Maintenance history visible at the unit — no need to search chats +- Easy reporting: scan → tap "Report Issue" → done +- Agents can scan during check-in to verify unit status + +--- + +## 11. Priority System & Service Level Agreements + +> ✅ **Defined by Wahab (July 16, 2026)** — Pending review/confirmation by Scott + +| Priority | Response Target | Resolution Target | Escalation Trigger | Examples | +|----------|----------------|-------------------|--------------------|----------| +| 🔴 **Urgent** | **10–15 minutes** | **2–4 hours** | No ack in 15min → alert all gatekeepers + Jerome + Scott | No water, no power, gas leak, sewage, fire, flooding | +| 🟠 **High** | **30 minutes** | **8–24 hours** | No ack in 30min → alert gatekeeper | AC broken in occupied unit, toilet blocked, no hot water | +| 🟡 **Medium** | **4 hours** | **2–3 days** | No ack in 4h → alert gatekeeper | Leaky tap, light bulb, cleaning, loose fixture | +| 🟢 **Low** | **1 day** | **5–7 days** | No ack in 24h → alert gatekeeper | Paint touch-up, cosmetic, furniture replacement | + +**Holiday Calendar — Ghana 2026:** + +| Date | Day | Holiday | SLA Adjustment | +|------|-----|---------|----------------| +| 1 January | Thu | New Year's Day | Skeleton crew | +| 7 January | Wed | Constitution Day | Skeleton crew | +| 9 January | Fri | Substitute for Constitution Day | Skeleton crew | +| 6 March | Fri | Independence Day | Skeleton crew | +| 20 March* | Fri | Eid-ul-Fitr | Skeleton crew | +| 23 March | Mon | Shaqq Day (day after Eid) | Skeleton crew | +| 3 April | Fri | Good Friday | Skeleton crew | +| 6 April | Mon | Easter Monday | Skeleton crew | +| 1 May | Fri | Workers' Day (Labour Day) | Skeleton crew | +| 27 May* | Wed | Eid-ul-Adha | Skeleton crew | +| 3 July | Fri | Republic Day | Skeleton crew | +| 21 September | Mon | Founder's Day / Kwame Nkrumah Memorial Day | Skeleton crew | +| 4 December | Fri | Farmer's Day | Skeleton crew | +| 25 December | Fri | Christmas Day | Skeleton crew | +| 28 December | Mon | Boxing Day holiday | Skeleton crew | + +> *Islamic holidays (*) depend on moon sighting — dates are provisional per 2026 declarations. + +--- + +## 12. Permissions Matrix + +| Action | Bella (CS) | Nicholas (FM) | Ama (Esc) | Akua/Mercy | Jerome | Scott (CEO) | Directors | +|--------|-----------|--------------|-----------|------------|--------|-------------|-----------| +| View Dashboard | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| View CEO Dashboard | — | — | — | — | ✓ | ✓ | ✓ (own) | +| View Reports | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create Issue | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | +| Assign Technician | ✓ | ✓ | ✓ | — | — | — | — | +| Reassign Issue | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | +| Close/Verify Issue | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | +| Reopen Issue | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | +| Manage Parts/Procurement | — | ✓ | — | — | ✓ | — | — | +| Manage Users | — | — | — | ✓ | ✓ | — | — | +| Override All | ✓ | ✓ | — | ✓ | ✓ | — | — | +| Delete Ticket | — | — | — | — | ✓ | — | — | +| Export Reports | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + +--- + +## 13. Technical Architecture + +### Preferred Stack (from PSD) + +| Component | Technology | Rationale | +|-----------|-----------|-----------| +| **Frontend** | React or Next.js + Tailwind CSS | Responsive, works on phone/laptop, great for dashboards | +| **Backend** | Node.js (Fastify/Express) **or** Python FastAPI | Lightweight MVP — FastAPI recommended for faster initial build; migrate to Node.js if scale demands | +| **Database** | PostgreSQL | Proper relational model for 15-status lifecycle, multi-role permissions, complex queries for analytics | +| **File Storage** | Local filesystem (MVP) → S3-compatible (Azure Blob / MinIO) | Photos, voice notes, documents | +| **Authentication** | Email + Password (bcrypt) + JWT tokens → Microsoft Entra ID (future) | Simple but secure for team size | +| **WhatsApp** | Twilio API for WhatsApp | Reliable 2-way messaging, voice note transcription, media support | +| **Voice Notes** | Twilio Media Streams + ASR (Google/Azure Speech-to-Text) | Transcribe technician voice updates to text | +| **Reporting** | Metabase (self-hosted) or embedded chart library (Chart.js / Recharts) | Interactive dashboards without building from scratch | +| **Notifications** | Email + SMS (Twilio) + WhatsApp in-app | Multi-channel alerts | +| **Deployment** | Docker Compose on Linux server | Easy setup, automated backups | +| **Secure Access** | Netbird VPN tunnel (server-side only) | No client on user devices — browser access via HTTPS | + +### Architecture Diagram + +``` +┌──────────────────────────────────────────────────────────────┐ +│ SERVER (Homelab / Cloud) │ +│ │ +│ ┌─────────────────┐ ┌──────────────┐ ┌────────────────┐ │ +│ │ FastAPI / │ │ PostgreSQL │ │ Netbird Proxy │ │ +│ │ Node.js Backend │──│ (Database) │──│ (Auth Gateway) │ │ +│ │ │ │ │ │ → HTTPS │ │ +│ └────────┬────────┘ └──────────────┘ │ → JWT Auth │ │ +│ │ └───────┬────────┘ │ +│ ┌────────▼────────┐ │ │ +│ │ React / │ │ │ +│ │ Next.js │ │ │ +│ │ Frontend │ │ │ +│ └─────────────────┘ │ │ +│ │ │ +│ ┌────────────────────────────────────────────────┘ │ +│ │ File Storage (uploads/) │ +│ └─────────────────────────────────────────────────────────── │ +└────────────────────────────────────────────────────────────────┘ + │ + ┌──────────────┼──────────────────┐ + │ │ │ + ┌──────────▼──────┐ ┌─────▼────────┐ ┌─────▼──────┐ + │ Users │ │ Twilio │ │ QR Codes │ + │ (Web Browser) │ │ WhatsApp API │ │ (Mobile │ + │ No VPN needed │ │ ↔ Bot │ │ Phone) │ + └─────────────────┘ └──────────────┘ └─────────────┘ +``` + +--- + +## 14. Reporting Module + +### Export Formats + +| Format | Use Case | +|--------|----------| +| 📄 PDF | Executive summaries, formal reports | +| 📊 Excel | Data analysis, filtering, pivot tables | +| 📋 CSV | Raw data for external systems | + +### Scheduled Delivery + +| Frequency | Reports | Recipients | +|-----------|---------|------------| +| Daily | Daily Operations Report | Jerome, Akua/Mercy | +| Weekly | Technician Productivity, SLA Compliance, Executive Summary | Scott, Jerome | +| Monthly | Cost Analysis, Customer Satisfaction, Preventive Maintenance | All Directors | +| Quarterly | Repeat Fault Report, Contractor Performance, Asset History | Scott | + +### Standard Reports + +1. Daily Operations Report — new, open, closed tickets today +2. Technician Productivity — jobs completed, avg time, top performer +3. SLA Compliance — % met per priority, worst offenders +4. Executive Summary — KPIs, trends, risks +5. Customer Satisfaction — average rating, low-score tickets +6. Cost Analysis — maintenance spend per building, per category +7. Repeat Fault Report — units with most recurring issues +8. Contractor Performance — if external hires used +9. Asset Maintenance History — per building, per system (AC, water pump, generator) +10. Preventive Maintenance Report — scheduled vs completed PM tasks + +--- + +## 15. AI Features (Phase 2 — Post-MVP Stabilization) + +| Feature | Description | Value | +|---------|-------------|-------| +| 🤖 **AI Ticket Classification** | Auto-categorize issue from description text | Saves Bella 30s per ticket | +| 🔮 **AI Priority Prediction** | Suggest priority based on category + description + unit history | Consistent prioritization | +| 👤 **AI Technician Assignment** | Recommend best tech based on skill + location + workload | Optimal dispatch | +| 🔧 **AI Maintenance Recommendations** | Suggest related maintenance based on patterns | Preventive insights | +| 🖼️ **AI Image Analysis** | Detect defect type from technician photos | Faster triage, auto-categorize | +| 💬 **AI Tenant Chatbot** | Self-service FAQ and troubleshooting for guests | Reduce agent calls | +| 📝 **AI Executive Summaries** | Auto-generate weekly/daily narrative from raw data | Saves Scott time | +| 🔮 **Predictive Maintenance** | Predict failures from usage + history patterns | Reduce downtime | +| ⚙️ **Asset Failure Forecasting** | When does the AC at 102E likely fail next? | Proactive replacement | + +> **AI Readiness Requirement:** The MVP must capture clean, structured historical data for at least 3 months before AI features can be trained on Denya-specific patterns. + +--- + +## 16. Implementation Roadmap + +### Phase 1: MVP (3 Weeks — Weeks 1-3) + +| Week | Deliverables | +|------|-------------| +| **1** | Server setup (Linux + Docker), PostgreSQL, domain/Netbird, auth system | +| **2** | Backend API core: CRUD for tickets, users, units; WhatsApp bot (Twilio + commands) | +| **3** | Dashboard + Create Issue + All Issues table + Issue Detail + QA with Nicholas & Bella + go-live | + +> **Note:** POC starts with a **manual spreadsheet** built from existing QR request logs (what Wahab is already collecting). QR code scanning deferred to Phase 2. + +### Phase 2: Enhancement (Weeks 7-12) + +- QR code system for apartments +- CEO dashboard with KPI cards +- Reporting module with scheduled exports +- Full 15-status lifecycle (if not already in MVP) +- Procurement workflow +- Director dashboards + +### Phase 3: Intelligence (Months 4-6) + +- AI ticket classification +- AI priority prediction +- Technician performance analytics with trends +- 48-hour follow-up survey automation + +### Phase 4: Advanced AI (Months 7-12) + +- Image analysis for defect detection +- Tenant chatbot +- Predictive maintenance +- GPS technician tracking +- Asset failure forecasting + +--- + +## 17. What's Needed from the Team to Proceed + +Please discuss and decide: + +1. ✅ **Workflow approval** — Does the merged end-to-end flow match how you work? +2. 🎯 **SLA targets** — What response/resolution times are realistic for each priority? +3. 📅 **Holiday calendar** — Which Ghanaian public holidays should the system know about? +4. 👥 **Permissions** — Is the permissions matrix about right? +5. 📱 **WhatsApp number** — Dedicated business number for the bot +6. 💻 **Server** — Homelab machine available, or prefer cloud hosting? +7. 🎤 **Voice notes** — Will techs actually use voice notes over typing? +8. 🚀 **MVP scope** — Is the Phase 1 scope (Weeks 1-6) sufficient to start, or do we need more/less? + +--- + +## 18. Supporting Documents + +| Document | Path | Description | +|----------|------|-------------| +| Product Specification (PSD) | `denya_onecare_psd.docx` | Wahab's full enterprise PSD | +| Original Proposal | `issue_tracking_system_proposal.md` | Initial design with team details | +| Wahab's Briefing | `wahab_briefing_and_task_list.md` | Full project brief for Wahab | +| Apartment Mapping | `apartment_mapping.json` | Unit aliases, building groupings | +| Financial Report | `denya_summary_report.txt` | Revenue $609K, 83% profit | + +--- + +*Prepared by Agent Zero for Denya Developers — July 16, 2026* +*This is a living document — updated as field data comes in from Wahab.*