StayFix Hotel Maintenance

Operations

Original Idea

Hotel Maintenance Tickets A mobile app for staff to snap issues, assign priority, and close the loop fast.

Product Requirements Document: StayFix Hotel Maintenance (2026)

1. Executive Summary

StayFix is a next-generation mobile-first operations platform designed for the hospitality industry. It streamlines the lifecycle of hotel maintenance by allowing staff to instantly report issues via photo capture and QR scanning, providing technicians with real-time task management, and giving management data-driven insights. Built on a "Local-First" architecture, StayFix ensures 100% uptime even in zero-connectivity areas like hotel basements and service elevators, leveraging AI to automatically categorize issues and prioritize repairs to maximize guest satisfaction.

2. Problem Statement

Manual maintenance reporting (via radio, paper, or legacy desktop software) leads to a "black hole" of information. Issues are often lost, response times are slow, and managers lack visibility into technician workloads. This inefficiency results in "Out of Order" (OOO) rooms that stay offline longer than necessary, directly impacting RevPAR (Revenue Per Available Room) and guest experience.

3. Goals & Success Metrics

  • Goal 1: Reduce the time from "Issue Identified" to "Technician Assigned" by 60%.
  • Goal 2: Ensure 100% data integrity in low-connectivity areas (basements/elevators).
  • Goal 3: Increase room uptime by reducing average "Resolution Time" (MTTR) by 25%.
  • Success Metrics:
    • MTTR (Mean Time To Repair): Target < 90 minutes for "High" priority issues.
    • Sync Reliability: 0% data loss during offline-to-online transitions.
    • Staff Adoption: > 90% of housekeeping staff using the app for daily reporting within 30 days.

4. User Personas

| Persona | Goals | Pain Points | | :--- | :--- | :--- | | Housekeeping Staff | Report room issues quickly during cleaning rounds. | Language barriers, slow apps, forgetting to call in repairs. | | Maintenance Technician | Receive clear task lists and documentation for repairs. | Vague descriptions, constant radio interruptions, paper logs. | | Hotel Ops Manager | Monitor property health and staff efficiency. | Lack of data on recurring asset failures, unfair workload distribution. | | Front Desk | Know instantly if a room is ready for check-in. | Selling a room only to find out the AC is broken. |

5. User Stories

  • As a Housekeeper, I want to scan a room's QR code and snap a photo of a broken faucet so that I can report it in under 10 seconds without typing.
  • As a Technician, I want the app to work offline in the basement so that I can log my progress even without Wi-Fi.
  • As a Manager, I want the system to automatically flag "Urgent" issues like water leaks using AI so that I can prevent property damage.
  • As a Front Desk Agent, I want to see the real-time status of a maintenance ticket so I can update a waiting guest.

6. Functional Requirements

6.1 Issue Reporting & Capture

  • QR Identification: Scan room/asset QR codes using mobile_scanner (Flutter) or vision-camera (RN).
  • Multimodal Capture: Support for photo and voice-to-text descriptions.
  • AI Classification: Automatic tagging of issues (e.g., "Plumbing", "Electrical") using AWS Rekognition and Bedrock.

6.2 Ticketing & Workflow

  • Priority Engine: Automated priority assignment (Urgent/High/Medium/Low) based on room type and issue category.
  • Real-time Status: Open, In-Progress, Resolved, Re-Opened, Verified.
  • Verification: Technicians must upload an "After" photo to close "High" priority tickets.

6.3 Offline-First Sync

  • Local Source of Truth: All data is written to a local SQLite database (SQLDelight) first.
  • Background Sync: Automatic "delta" synchronization when the device detects a stable heartbeat.

6.4 Management Dashboard

  • Workload Balancing: Visual map of technician locations and current task counts.
  • Analytics: Reports on frequent asset failures (e.g., "Samsung TV in Floor 4 fails every 3 months").

7. Technical Requirements

7.1 Core Tech Stack

  • Frontend Framework: Flutter 3.38.x (Selected for Impeller rendering engine and superior UI stability across 2026 OS updates).
  • Local Storage: SQLDelight for type-safe local-first data persistence.
  • Backend: Node.js 24+ (utilizing HTTP/3 QUIC for resilient connections).
  • Database: PostgreSQL 18 (Native UUIDv7 for ordered indexing and Asynchronous I/O for reporting).
  • Identity & RBAC: Auth0 with Auth0 Actions for hierarchical role injection.

7.2 Integrations

  • PMS: Two-way sync with Oracle OPERA Cloud (via OHIP) and Mews Connector API for room status.
  • AI Service: AWS Rekognition for asset feature extraction and Amazon Bedrock (Claude 4) for reasoning.
  • Communications: Firebase Cloud Messaging (FCM) for push notifications.

8. Data Model

8.1 Ticket Entity

  • id: UUIDv7 (Primary Key, timestamp-ordered)
  • room_id: UUIDv7 (FK to LocationAsset)
  • category: String (Enum: Plumbing, Electrical, HVAC, etc.)
  • priority: Integer (1-4)
  • status: String (Enum: Open, Pending, Resolved)
  • before_photo_url: String (S3 Signed URL)
  • after_photo_url: String (Optional)
  • ai_metadata: JSONB (Store labels from Rekognition)
  • created_at: Timestamp (Partition Key)

8.2 User Entity

  • id: String (Auth0 UID)
  • role: Enum (Manager, Technician, Housekeeper)
  • department_id: UUIDv7
  • current_shift_id: UUIDv7 (Optional)

9. API Specification (Sample)

POST /v1/tickets

Creates a new maintenance ticket with optimistic UI support.

  • Request: 
    {
  "id": "018d3b2a-...", 
  "room_qr_hash": "A1-404-XYZ",
  "category_guess": "HVAC",
  "description": "AC blowing hot air",
  "photo_data": "base64...",
  "idempotency_key": "user123-ts-998"
}
  • Response: 202 Accepted (Indicates processing via background worker).

10. UI/UX Requirements

  • Optimistic UI: When a housekeeper clicks "Submit," the ticket appears in their "Sent" list immediately with a "Syncing..." icon.
  • Skeleton Screens: Used for all list views to minimize perceived latency.
  • High Contrast Mode: Optimized for technicians working in low-light environments (mechanical rooms).
  • QR Scanner UI: Centralized viewfinder with pretty_qr_code branding and haptic feedback on successful scan.

11. Non-Functional Requirements

  • Performance: UI interactions must respond in < 100ms. Database queries for active tickets must return in < 50ms using Partial Indexes.
  • Reliability: 99.99% uptime. The app must remain functional without an internet connection for up to 12 hours.
  • Security: PII (Guest Names) must never be stored in the maintenance DB. All photos stored in S3 must be encrypted at rest and accessed via time-limited signed URLs.

12. Out of Scope

  • Guest-to-staff direct messaging.
  • Inventory purchasing/e-commerce for spare parts.
  • External contractor payroll management.

13. Risks & Mitigations

| Risk | Impact | Mitigation | | :--- | :--- | :--- | | "Lie-Fi" in Basements | High | Use HTTP/3 and exponential backoff with jitter to prevent sync loops. | | Low Staff Tech Literacy | High | Multi-language UI and 100% icon-driven reporting flow. | | PMS API Downtime | Medium | Implement a local buffer that queues status updates until PMS is reachable. |

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize Flutter project (Version 3.38.x) with Impeller enabled
  • [ ] Configure PostgreSQL 18 instance with UUIDv7 support
  • [ ] Set up Auth0 Tenant with Roles: Manager, Technician, Housekeeper
  • [ ] Configure GitHub Actions for CI/CD with automated testing

Phase 2: Offline-First Core

  • [ ] Implement SQLDelight schema for local-first storage
  • [ ] Build SyncEngine using WorkManager (Android) and BGProcessingTask (iOS)
  • [ ] Create useOptimistic hook equivalents in Flutter for ticket submission
  • [ ] Implement Delta-Sync logic on Node.js backend

Phase 3: Hardware & AI Integration

  • [ ] Integrate mobile_scanner (v7.x) for high-speed QR identification
  • [ ] Configure AWS S3 bucket with event triggers for Lambda
  • [ ] Develop Lambda function to call AWS Rekognition Custom Labels
  • [ ] Integrate Amazon Bedrock for automated priority reasoning

Phase 4: PMS & Advanced Features

  • [ ] Build Oracle OHIP WebSocket connector for real-time room status
  • [ ] Implement Mews Connector API for task synchronization
  • [ ] Create Management Dashboard with PostgreSQL Partitioning (Quarterly)
  • [ ] Add pretty_qr_code generation for in-room asset tagging

Phase 5: Security & Optimization

  • [ ] Implement Auth0 Actions for token-based RBAC
  • [ ] Configure PostgreSQL bi-directional indexes for sorting
  • [ ] Perform "Basement Stress Test" (simulate 0% connectivity for 4 hours)
  • [ ] Conduct accessibility audit for WCAG 2.1 compliance