Product Requirements Document (PRD): TurnoverSync

1. Executive Summary

TurnoverSync is a specialized operations platform designed to bridge the high-pressure gap between a tenant moving out and a new tenant moving in. By using a Directed Acyclic Graph (DAG) task engine, the app automates the sequencing of painters, cleaners, and inspectors. It provides real-time visibility into "blockers"—unexpected maintenance issues—allowing property managers to adjust schedules dynamically, reducing vacancy loss and ensuring move-in readiness.

2. Problem Statement

Property management teams currently rely on fragmented tools (spreadsheets, SMS, and legacy PMS) to coordinate turnovers. This lack of centralization leads to:

Sequential Deadlocks: Vendors arriving before the previous task (e.g., painting) is finished.
Invisible Blockers: Maintenance issues discovered mid-turnover aren't communicated instantly, delaying move-in day.
Data Silos: Move-out inspection photos and vendor invoices are scattered, making audit trails impossible.
Vacancy Loss: Every day a unit sits idle due to poor coordination costs owners hundreds of dollars.

3. Goals & Success Metrics

Reduce Turnover Duration: Decrease the average move-out to move-in window by 15%.
Eliminate "Dry Runs": Reduce vendor arrivals to unready sites to < 2%.
High-Fidelity Documentation: 100% of turnovers must have timestamped/GPS-verified photo evidence.
User Adoption: Achieve a 90% "Dispatch Acceptance" rate from third-party vendors within the first 60 days.

4. User Personas

5. User Stories

As a PM, I want to initiate a turnover from a template so that I don't have to manually create 15 tasks for every unit.
As a Coordinator, I want the system to automatically notify the cleaner only AFTER the painter marks their task as 100% complete.
As a Vendor, I want to upload photos of a broken HVAC unit and flag it as a "Blocker" so the PM knows why I can't finish the turnover.
As a PM, I want to see a real-time dashboard of all active turnovers across 10 buildings to identify which ones are at risk of missing the move-in date.

6. Functional Requirements

6.1. DAG-Based Task Engine

The system shall support task dependencies (e.g., Task B cannot start until Task A is "Complete").
Supports parallel branching (e.g., HVAC repair and Painting can happen simultaneously).
Automatic rescheduling: If a "Root" task is delayed, all downstream tasks are automatically updated.

6.2. Smart Dispatch & Vendor Portal

Mobile-first interface for vendors (no app store download required/PWA).
"Accept/Decline" workflow for dispatched work orders.
GPS-fenced check-in/check-out for vendors to verify time-on-site.

6.3. Blocker Management

One-tap "Flag Blocker" button on any task.
Categorization (Maintenance, Access Issue, Supply Shortage).
Automatic "Pause" of all dependent downstream tasks and instant SMS/Push notification to the Coordinator.

6.4. Inspection & Photo Documentation

Move-out/Move-in photo checklists.
Support for offline photo capture with background sync.
Automatic image compression and metadata extraction (EXIF data).

7. Technical Requirements

7.1. Tech Stack (2026 Standards)

Frontend: React 19.2.3 (utilizing React Compiler for auto-memoization).
Styling: Tailwind CSS 4.1.18 (using the Oxide engine for microsecond builds).
Backend: Node.js 24.13.0 LTS ("Krypton") with NestJS 11.1.12.
Database: PostgreSQL 18 (utilizing Row-Level Security (RLS) for multi-tenant isolation).
Cache/Queue: Redis 7.4 + BullMQ for task scheduling and SMS queuing.
Auth: Auth0 with custom claims for RBAC/ABAC (CASL).

7.2. Integrations

PMS Sync: Yardi Voyager (via Polling) and AppFolio (via Stack API Webhooks).
Communication: Twilio SMS for vendor alerts.
Calendar: Syncfusion React Scheduler for vendor availability management.
Storage: AWS S3 with Transfer Acceleration and Pre-signed Resumable uploads.

8. Data Model

8.1. `PropertyUnit`

id: UUID (Primary Key)
tenant_id: UUID (RLS Identifier)
unit_number: String
pms_id: String (External ID for Yardi/AppFolio)

8.2. `TurnoverTask` (DAG Node)

id: UUID
project_id: UUID
dependencies: UUID[] (Array of Task IDs)
status: Enum (Pending, In-Progress, Completed, Blocked)
assigned_vendor_id: UUID
sequence_order: Integer

8.3. `AuditLog`

id: UUID
entity_id: UUID
old_value: JSONB
new_value: JSONB
changed_by: UUID (Mapped via SET LOCAL app.current_user_id)

9. API Specification

9.1. Create Blocker (POST)

Endpoint: /api/v1/tasks/:taskId/blocker
Payload: { "reason": "Water Damage", "severity": "High", "photo_ids": ["uuid-1"] }
Response: 201 Created - Triggers WebSocket blocker.alert and Twilio SMS.

9.2. Task Sequence (GET)

Endpoint: /api/v1/projects/:projectId/graph
Response: Returns a topologically sorted list of tasks with dependency status.

10. UI/UX Requirements

Turnover Dashboard: A "Subway Map" visualization of the turnover progress.
Vendor Mobile View: Large touch targets, dark-mode optimized (for low-light basements), and a persistent "Connectivity Status" indicator for offline work.
Photo Capture: Custom camera interface that enforces "Vertical" orientation for standardizing inspection reports.

11. Non-Functional Requirements

Performance: Dashboard load time < 1.5s for portfolios up to 500 units (via Lazy Loading).
Security: Data isolation via PostgreSQL RLS; no vendor can query units not assigned to them in the app_metadata JWT claim.
Offline Reliability: Use of RxDB for local-first data persistence during inspections.
Auditability: Every status change must be logged with the user ID and timestamp, immutable at the DB level.

12. Out of Scope

Handling actual lease signatures (handled by Yardi/AppFolio).
Processing payments to vendors (Phase 2).
Tenant-facing communication portal (Nice-to-have, deferred).

13. Risks & Mitigations

14. Implementation Tasks

Phase 1: Foundation & DevOps

[ ] Initialize NestJS 11.1.12 & Node 24.13.0 LTS environment.
[ ] Configure PostgreSQL 18 with RLS policies and audit schema.
[ ] Set up Tailwind CSS 4.1 with Oxide engine configuration.
[ ] Initialize Auth0 tenant and define property_manager / vendor roles.

Phase 2: DAG Task Engine & Core API

[ ] Implement Kahn's Algorithm for topological task sorting.
[ ] Build TurnoverTask CRUD with dependency validation logic.
[ ] Create nestjs-cls middleware to inject tenant_id into all DB queries.
[ ] Implement the "Snapshot" audit logging trigger in PostgreSQL.

Phase 3: Vendor Interface & Real-time Alerts

[ ] Build mobile-optimized Vendor Portal using React 19.2.3.
[ ] Integrate Socket.io for real-time "Blocker" toast notifications.
[ ] Develop Twilio SMS provider for high-priority dispatch alerts.
[ ] Implement CASL rules: Vendors can only view assigned_units.

Phase 4: Inspections & Offline Sync

[ ] Integrate Uppy with @uppy/aws-s3 for resumable photo uploads.
[ ] Implement @squoosh/lib (Wasm) for client-side image compression.
[ ] Set up RxDB for local-first storage of inspection checklists.
[ ] Build "Connectivity Badge" component to reflect sync status.

Phase 5: Dashboard & Integrations

[ ] Create "Turnover Subway Map" visualization using Syncfusion Scheduler.
[ ] Build Yardi/AppFolio sync service with idempotency checks.
[ ] Implement portfolio-wide reporting (Vacancy loss calculator).
[ ] Finalize SOC2-compliant audit log export (CSV/PDF).