Pearl-Facilities System Requirements Document

Introduction

The Pearl-Facilities project aims to develop a comprehensive Facilities Management System for a commercial office tower. This system will streamline the reporting, management, and resolution of maintenance issues within the facility, catering to different user roles through distinct interfaces.

System Overview

The Pearl-Facilities system is designed to facilitate efficient communication and task management between tenants, operations staff, and technicians. The system will be hosted as a single application with different user views, ensuring seamless interaction and task resolution. The primary components include:

• Tenant Portal: Allows tenants to report maintenance issues with photo uploads.
• Operations Dashboard: Enables dispatchers to manage incoming issues, prioritize them, and assign tasks to technicians.
• Technician View: Provides technicians with a streamlined interface to manage their work orders, update task statuses, and log inventory usage.

Functional Requirements

• As a Tenant, I should be able to report maintenance issues with photo uploads.
• As a Tenant, I should be able to view the status of my reported issues.
• As an Operations Dispatcher, I should be able to view a master queue of incoming issues.
• As an Operations Dispatcher, I should be able to triage issues based on urgency.
• As an Operations Dispatcher, I should be able to assign issues to technicians.
• As a Technician, I should be able to view my assigned work orders.
• As a Technician, I should be able to update the status of tasks to 'In Progress' or 'Completed'.
• As a Technician, I should be able to log inventory parts used for each task.
• As a Technician, I should be able to collect a tenant's sign-off signature upon task completion.

User Personas

• Tenant: Individuals or companies renting space within the commercial office tower. They report issues and track their resolution.
• Operations Dispatcher: Staff responsible for managing maintenance requests, prioritizing them, and assigning tasks to technicians.
• Technician: Maintenance personnel tasked with resolving reported issues, updating task statuses, and managing inventory usage.

Core User Flows

• Tenant reports an issue -> Uploads photo -> Operations Dispatcher triages and assigns task -> Technician updates task status -> Technician logs inventory -> Tenant signs off on completion.
• Operations Dispatcher reviews incoming issues -> Prioritizes based on urgency -> Assigns to available technician -> Technician completes task -> Updates status to 'Completed'.

Visuals Colors and Theme

• primary: #2A9D8F (Emerald Green)
• primary_light: #A8DADC (Light Aqua)
• secondary: #E76F51 (Coral)
• accent: #F4A261 (Sandy Orange)
• highlight: #FFB703 (Amber)
• bg: #F1FAEE (Off White)
• surface: rgba(233, 233, 233, 0.8)
• text: #264653 (Dark Slate)
• text_muted: #6D6875 (Muted Gray)
• border: rgba(38, 70, 83, 0.2)

Signature Design Concept

The Pearl-Facilities homepage will feature an interactive 3D model of the office tower using @react-three/fiber and @react-three/drei. Users can click on different floors to zoom in and view reported issues, technician assignments, and task statuses in real-time. The model will rotate and animate as users navigate, providing an engaging and intuitive overview of the facility's maintenance activities. Hovering over sections will highlight active issues, and clicking will provide detailed information and options for interaction.

Interaction Model & Motion Direction

The landing page will utilize a "parallax" interaction model, providing a layered depth experience as users scroll. Decorative elements will move at varying speeds to create a dynamic visual effect, while core content remains easily accessible. Internal pages, such as dashboards and profiles, will adopt a "static" model to prioritize clarity and efficiency in task management.

Non-Functional Requirements

• The system must support concurrent access by multiple users without performance degradation.
• Data integrity and security must be maintained, with secure access controls in place.
• The application should be responsive and accessible on various devices and screen sizes.

Tech Stack

• Frontend: React for Web
• Backend: Python, FastAPI
• Database: MySQL or MariaDB, with Alembic for migrations
• Local Orchestration: Docker, docker-compose
• Server-side Orchestration: Kubernetes

Assumptions and Constraints

• The system will be deployed in a commercial office tower environment with reliable internet access.
• User authentication and role-based access control are assumed to be in place for secure operations.
• The application will be designed to handle a moderate volume of maintenance requests typical of a commercial office tower.

Glossary

• Tenant: An individual or company renting space within the office tower.
• Operations Dispatcher: Staff responsible for managing and assigning maintenance tasks.
• Technician: Maintenance personnel responsible for resolving reported issues.
• Work Order: A task assigned to a technician for resolution.
• Triage: The process of prioritizing issues based on urgency and impact.