denya-onecare/PRD.md

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