NeighborHarmony

Consumer

Original Idea

Neighbor Noise Agreement A web app for apartment dwellers to set quiet hours, share schedules, and coordinate ahead of parties or construction.

Product Requirements Document (PRD): NeighborHarmony

1. Executive Summary

NeighborHarmony is a community-driven web application designed to mitigate the friction of multi-unit living by synchronizing noise expectations and schedules. Unlike generic messaging apps, NeighborHarmony uses building-specific 3D spatial mapping and privacy-first "Quiet Hour" profiles to help neighbors coordinate loud activities (parties, renovations) and sensitive times (infant naps, remote work focus). By facilitating anonymous "Gentle Nudges" and gamifying positive neighborly behavior, the platform transforms apartment living from a source of conflict into a collaborative environment.

2. Problem Statement

Living in multi-unit dwellings often leads to interpersonal friction caused by:

  • Misaligned Schedules: Remote workers and parents with infants are disproportionately affected by neighbors’ "normal" daytime noise.
  • Lack of Communication Channels: Residents often feel uncomfortable knocking on a neighbor's door to complain, leading to bottled-up resentment or formal complaints to management.
  • Lack of Foresight: Major noise events (renovations/parties) occur without warning, preventing neighbors from planning their own schedules accordingly.

3. Goals & Success Metrics

  • Goal 1: Reduce formal noise complaints to property managers.
    • Metric: 40% reduction in reported noise incidents within 6 months of building adoption.
  • Goal 2: Build a high-trust community.
    • Metric: "Nudge Resolution Rate" (percentage of anonymous nudges that result in a user lowering their volume) > 75%.
  • Goal 3: High Resident Engagement.
    • Metric: 60% of units in a building actively logging at least one "Quiet Preference" or "Event."

4. User Personas

  • The Focused Professional (Alex): Remote software engineer who needs deep focus from 9 AM – 12 PM. Vulnerable to neighbor renovations.
  • The New Parent (Sarah): Has an infant on a strict nap schedule (1 PM – 3 PM). Needs quiet to ensure the baby (and she) can sleep.
  • The Social Host (Leo): College student who occasionally hosts weekend gatherings. Wants to be a "good neighbor" without sacrificing his social life.
  • The Property Manager (Marcus): Overwhelmed by "he-said-she-said" noise complaints. Wants a self-policing tool for residents.

5. User Stories

  • As a remote worker, I want to set a "Deep Work" preference so my neighbors see that I need quiet on Tuesday mornings before they start drilling.
  • As a parent, I want to receive a notification if a neighbor logs a renovation event during my baby's nap time so I can ask them to coordinate the loudest part for later.
  • As a resident, I want to send an anonymous nudge to a neighbor whose music is too loud so I can resolve the issue without a direct confrontation.
  • As a host, I want to log a party on the building calendar so my neighbors feel respected and informed ahead of time.

6. Functional Requirements

6.1 Building & User Management

  • Verified Onboarding: Users must enter a building-specific invite code.
  • Unit Mapping: Users are assigned a unit number and floor.
  • 3D Proximity: The system automatically calculates "Nearby Neighbors" (units directly above, below, or adjacent) using PostGIS 3D logic.

6.2 Noise Coordination

  • Quiet Hour Profiles: Residents set recurring sensitive times (e.g., "Nap Time," "Focus Time").
  • Noise Event Logging: Residents schedule "Noisy Events" (Parties, Construction, Music Practice) with category and intensity levels.
  • Conflict Detection: When an event overlaps with a neighbor's "Quiet Preference," both parties receive a "Coordination Prompt" to find a compromise.

6.3 Real-Time Feedback

  • Gentle Nudges: Anonymous, pre-written messages (e.g., "Hey neighbor, it's getting a bit loud!") sent via WebSockets.
  • Anonymous Rate Limiting: Prevent nudge-spamming using Blind Signatures/ACT tokens.
  • AI Moderation: Real-time scanning of any custom text to prevent harassment.

6.4 Community & Rewards

  • Good Neighbor Points: Points earned for logging events early, responding to nudges, and honoring neighbor requests.
  • Building Calendar: A high-performance canvas-based view of all scheduled noise and quiet needs.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

  • Frontend: React 19.2.3 (utilizing React Compiler 1.0) with Tailwind CSS 4.1.x (CSS-first engine).
  • Backend: Node.js 24.x (LTS) with Express 5.2.1 (native Promise support).
  • Database: PostgreSQL 18.1 with PostGIS 3.6.1 for 3D geospatial proximity mapping.
  • Authentication: Firebase Auth (GCIP) with multi-tenant building silos.
  • Real-time: Socket.io 4.8+ with Redis 7.0 adapter for alerts.
  • Hosting: AWS (ALB with Sticky Sessions, Global Accelerator).

7.2 Integrations

  • Twilio: For SMS alerts when an "Urgent Nudge" is sent.
  • AWS IoT Core: For optional integration with IoT decibel sensors.
  • Trophy API: For the gamified "Good Neighbor" reward logic.

8. Data Model

8.1 Building

  • id: UUID
  • address: String
  • invite_code: String (Unique)
  • floor_height_m: Float (default 3.2m for 3D calculation)

8.2 User

  • id: UUID (Firebase UID)
  • tenant_id: String (Building ID)
  • unit_number: String
  • geom: POINT Z (PostGIS 3D coordinate)
  • neighbor_points: Integer

8.3 NoiseEvent

  • id: UUID
  • user_id: UUID
  • start_time: Timestamp
  • end_time: Timestamp
  • intensity: Enum (Low, Med, High)
  • category: Enum (Party, Construction, Music, Maintenance)

8.4 QuietPreference

  • id: UUID
  • user_id: UUID
  • day_of_week: Integer
  • start_time: Time
  • end_time: Time
  • type: Enum (Nap, Focus, Sleep)

9. API Specification (Sample)

  • POST /api/v1/auth/verify-invite: Validates building code and returns tenantId.
  • GET /api/v1/events/proximity: Returns events within a 10m 3D radius of the user.
  • POST /api/v1/nudges/send:
    • Body: { recipientUnit: "402", messageType: "VOLUME_ADJUST" }
    • Note: Uses Anonymous Counting Tokens to prevent user identification.

10. UI/UX Requirements

  • Abstracted Privacy: Neighbors see "Focusing" or "Busy" blocks on the calendar, never the specific reason (e.g., "Alex is writing a novel") unless shared.
  • Heatmap View: Building-wide "Noise Heatmap" using react-calendar-heatmap to show peak hours of activity.
  • High-Density Performance: Shared calendar uses @bitnoi.se/react-scheduler to handle buildings with 100+ units.
  • Mobile-First: 80% of nudges are expected to be sent/received via mobile devices.

11. Non-Functional Requirements

  • Latency: Nudges must be delivered within < 200ms via WebSockets.
  • Security: E2EE for any direct resident-to-resident communication.
  • Scalability: Support 10,000 concurrent users per building cluster.
  • Accessibility: WCAG 2.1 Level AA compliance, specifically for screen readers regarding the noise calendar.

12. Out of Scope

  • Financial Transactions: No rent payment or fine collection.
  • Audio Recording: The app will not record raw audio from user devices (privacy concern).
  • Legal Mediation: The app provides data for evidence but does not provide legal services.

13. Risks & Mitigations

  • Risk: Harassment via anonymous nudges.
    • Mitigation: AI toxicity filters (BERT-based) and rate-limiting to 3 nudges per hour per unit.
  • Risk: De-anonymization of residents in small buildings.
    • Mitigation: Use "Data Blurring"—only show that a nudge came from an "Adjacent Floor" rather than a specific unit if the building is small.
  • Risk: Incorrect 3D Mapping.
    • Mitigation: Manual floor-height calibration tool for building managers.

14. Implementation Tasks

Phase 1: Project Setup & Auth

  • [ ] Initialize React 19.2.3 project with Tailwind 4.1.x
  • [ ] Set up Express 5.2.1 server with Node.js 24 LTS
  • [ ] Configure Firebase Multi-tenancy for building-level data isolation
  • [ ] Implement Invite Code verification flow with Cloud Functions

Phase 2: Spatial Data & Profiles

  • [ ] Initialize PostgreSQL 18.1 with PostGIS 3.6.1 extension
  • [ ] Create logic to convert Floor/Unit to POINT Z coordinates
  • [ ] Build "Quiet Preference" UI with recurring time-slot selection
  • [ ] Implement 3D proximity query ST_3DDWithin for neighbor detection

Phase 3: Noise Events & Calendar

  • [ ] Integrate @bitnoi.se/react-scheduler for high-density event viewing
  • [ ] Implement NoiseEvent CRUD with conflict detection logic
  • [ ] Set up conflict notification triggers (Firebase Cloud Messaging)
  • [ ] Create Heatmap visualization for building-wide noise trends

Phase 4: Anonymous Nudges & Real-time

  • [ ] Configure AWS ALB with Sticky Sessions for Socket.io
  • [ ] Implement @socket.io/redis-adapter for multi-node message broadcasting
  • [ ] Build the "Gentle Nudge" UI with pre-defined message templates
  • [ ] Integrate AI-based toxicity filtering for custom message fields
  • [ ] Implement ACT (Anonymous Counting Tokens) for nudge rate-limiting

Phase 5: Gamification & Polish

  • [ ] Integrate Trophy API for "Good Neighbor" point tracking
  • [ ] Build "Milestone" UI for badge reveals using Motion.dev
  • [ ] Implement "Privacy Checkup" wizard for user profiles
  • [ ] Perform load testing for 3D queries using JMeter or k6