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.*