Initial commit: Denya OneCare PRD and build spec

2026-07-19 15:51:32 -04:00
parent 36a18e205f
commit 8c755f3db7
1 changed files with 590 additions and 0 deletions
@@ -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.*