Product Requirements Document: QuietNeighbor Mediator

1. Executive Summary

QuietNeighbor Mediator is a high-performance, multi-tenant web platform designed for apartment buildings and HOAs to manage noise disputes. By providing an anonymous, evidence-based reporting structure and automated mediation workflows, the platform reduces direct resident confrontation and administrative burden on property managers. The app leverages IoT noise sensors and real-time communication to resolve issues before they escalate to legal or formal eviction proceedings.

2. Problem Statement

In multi-unit housing, noise disputes are a primary cause of resident dissatisfaction and turnover. Traditional resolution methods—such as direct confrontation—often lead to harassment or retaliation. Property managers are frequently overwhelmed by subjective "he-said, she-said" complaints that lack data. Existing solutions are either purely manual or lack the technical integration to provide objective decibel-level evidence and anonymous mediation.

3. Goals & Success Metrics

• Goal: Reduce property manager time spent on noise disputes by 50%.
• Goal: Increase successful "First-Nudge" resolutions (offender quiets down after first notification) to 70%.
• Metric: Average time from complaint submission to "Resolved" status.
• Metric: Percentage of complaints backed by IoT or audio evidence.
• Metric: User retention/satisfaction for residents in "high-noise" buildings.

4. User Personas

| Persona | Role | Pain Points | | :--- | :--- | :--- | | Sarah (The Reporter) | Resident | Afraid of retaliation; loses sleep; feels ignored by management. | | Mark (The Offender) | Resident | Often unaware they are being loud; feels harassed by management "threats." | | Elena (The Manager) | Admin | Spent hours in mediation; lacks proof to issue fines; hates being a "noise cop." | | Legal/HOA Board | Oversight | Needs audit trails and data patterns for official enforcement. |

5. User Stories

• As a Resident, I want to report a noise incident anonymously so that I don't face retaliation from my neighbor.
• As a Resident, I want to attach audio recordings or decibel readings to my complaint so that my report is taken seriously.
• As an Offender, I want to receive a "Gentle Nudge" notification so that I can correct my behavior before it becomes a formal lease violation.
• As a Property Manager, I want to see a heatmap of noise complaints across the building so that I can identify chronic offenders and patterns.
• As a Mediator, I want a private chat room with both parties to facilitate a resolution agreement.

6. Functional Requirements

6.1 Complaint Management

• Anonymous Submission: Users submit complaints via a property-specific code.
• Evidence Vault: Support for .mp3, .wav, and decibel-level screenshots.
• Automated Nudges: Triggered SMS/Email notifications to the accused unit (unit-level addressing only).

6.2 Mediation System

• Three-Party Chat: WebSocket-based chat between Reporter, Offender, and Manager.
• Caucusing: Mediator can switch to private sub-channels with either party.
• Resolution Agreements: Digital sign-off on "Quiet Hours" commitments.

6.3 Building Oversight

• Heatmaps: Spatio-temporal visualization of noise spikes using TimescaleDB.
• Threshold Alerts: Auto-escalation to management when a unit exceeds X complaints/month.
• IoT Sync: Real-time ingestion of decibel data from Minut/NoiseAware.

7. Technical Requirements

7.1 Frontend

• Framework: Next.js v16.1.x (LTS) using Turbopack and React Compiler.
• Styling: Tailwind CSS v4.0 (CSS-native configuration).
• Rendering: Partial Pre-Rendering (PPR) for dashboard shells.

7.2 Backend

• Framework: NestJS (Node.js) with AsyncLocalStorage (ALS) for tenant isolation.
• Real-time: Socket.io (WebSockets) for mediation chat.
• Task Scheduling: BullMQ for "Temporal Jittering" of notifications.

7.3 Data & Infrastructure

• Primary Database: PostgreSQL with Row Level Security (RLS).
• Time-Series: TimescaleDB with Hypercore engine and Chunk-Skipping.
• Auth: Auth.js (v5/v6 era) with Property-Code validation and Server Actions.
• Hosting: AWS ECS Fargate (Graviton4) for backend, Aurora Serverless v2 for DB, and RDS Proxy.

7.4 Integrations

• IoT: Minut API (M3 sensor) and Seam API for NoiseAware.
• Messaging: Twilio for SMS nudges.
• Storage: Amazon S3 (AES-256 encrypted) for audio evidence.

8. Data Model

8.1 Core Entities

• User: id, email, password_hash, role (resident/manager/mediator), building_id, unit_number.
• Building: id, name, address, quiet_hours_config, escalation_threshold.
• Complaint: id, building_id, offender_unit, complainant_hash (SHA-256 + Pepper), status, timestamp.
• NoiseEvent (Time-Series): timestamp, building_id, unit_number, db_level, sensor_id.
• Message: id, chat_id, sender_id, text, visibility_type (JOINT/CAUCUS_A/CAUCUS_B).

9. API Specification (Key Endpoints)

| Method | Endpoint | Description | | :--- | :--- | :--- | | POST | /api/v1/complaints | Create anonymous complaint (Auth: Resident). | | GET | /api/v1/analytics/heatmap | Fetch building noise density (Auth: Manager). | | PATCH | /api/v1/mediation/:id/status | Update mediation state (Auth: Mediator). | | POST | /api/v1/iot/webhook/minut | Ingest real-time decibel spikes. |

10. UI/UX Requirements

• Accessibility: WCAG 2.2 compliant. Heatmaps must use Data Binning and Pattern Overlays (not just color) for colorblind users.
• Dashboards: Use high-contrast focus indicators (3:1 ratio).
• Anonymity UX: Explicit warnings to reporters if their text description includes self-identifying info.
• Mobile: 24x24px minimum touch targets for unit selection.

11. Non-Functional Requirements

• Performance: Heatmap queries must return in <200ms using Vectorized Aggregation.
• Security: Complainant IDs must be hashed using SHA-256 with a Global Pepper stored in AWS KMS.
• Isolation: Strict PostgreSQL RLS to prevent cross-tenant data leaks.
• Availability: 99.9% uptime using Multi-AZ RDS.

12. Out of Scope

• Handling of financial fines or payment processing (Phase 2).
• Direct legal representation or court filing.
• General maintenance requests (Plumbing/Electric).

13. Risks & Mitigations

| Risk | Mitigation | | :--- | :--- | | "Complaint Bombing" | Implement rate-limiting and unit-level cool-downs. | | Identity Inference | Implement Temporal Jittering (12–48 hour delay on non-urgent alerts). | | Connection Exhaustion | Use RDS Proxy to pool NestJS connections. |

14. Implementation Tasks

Phase 1: Project Setup & Foundation

• [ ] Initialize project with Next.js 16.1 and Turbopack.
• [ ] Set up Tailwind CSS 4.0 with CSS-native config.
• [ ] Configure NestJS with nestjs-cls for AsyncLocalStorage.
• [ ] Provision AWS RDS PostgreSQL with TimescaleDB extension.
• [ ] Implement Auth.js with property-code registration via Server Actions.

Phase 2: Anonymous Reporting & Security

• [ ] Create SHA-256 + Pepper hashing utility for complainant IDs.
• [ ] Implement audio evidence upload to S3 with AES-256 encryption.
• [ ] Build the "Submit Complaint" resident form with accessibility labels.
• [ ] Set up BullMQ for temporal jittering logic.

Phase 3: IoT Integration & Analytics

• [ ] Integrate Minut/Seam API webhooks for decibel ingestion.
• [ ] Create TimescaleDB Continuous Aggregates for hourly noise stats.
• [ ] Build the Property Manager Heatmap using binning and pattern overlays.
• [ ] Implement PostGIS spatial bucketing for unit-level noise mapping.

Phase 4: Mediation & Real-time Chat

• [ ] Build NestJS WebSocket Gateway using Socket.io.
• [ ] Implement Visibility Types in PostgreSQL for caucus vs. joint messages.
• [ ] Create the "Mediator Dashboard" with chat room controls.
• [ ] Add WCAG 2.2 focus appearance indicators to chat components.

Phase 5: Deployment & Optimization

• [ ] Containerize services for AWS ECS Fargate (Graviton4).
• [ ] Configure RDS Proxy for connection pooling.
• [ ] Run AWS DevOps Guru to audit query performance.
• [ ] Conduct accessibility audit using 2026 simulation tools.