Repository navigation
High Level Context
This document outlines the product scope, target personas, and Agile requirements for the NYC Active platform.
- Recreational Participants: NYC residents, students, or visitors who want to discover parks, sports facilities, and recreational activities nearby. They need a way to filter parks by amenity and RSVP to local meetups.
- Event Organizers: Users who want to create and manage recreational events. They need tools to set capacity limits, verify park amenities, and broadcast updates to attendees.
- Administrators: Platform administrators responsible for maintaining content quality. They manually correct missing NYC Park data, handle user reports, and remove inappropriate content or abusive accounts.
The Minimum Viable Product focuses on delivering a functional end-to-end loop for finding a park and organizing a meetup.
- Park & Facility Discovery: Interactive map/list seeded with NYC Parks Open Data, filterable by borough and athletic amenity.
- Accounts & Profiles: Secure authentication with athletic tags (favorite sports, competitive/casual skill level).
- Event Management: Create, browse, update, and cancel public meetups.
- Capped RSVPs: Strict participant limits with visible attendee rosters.
- In-App Discussions: Dedicated threads on event pages for logistical coordination.
- Park Reviews: 1–5 star ratings and text reviews for facility conditions.
- Administration: Maintain park information, handle user reports, moderate content, and manage user statuses.
The following Epics define the high-level architecture of the MVP. To maintain a Single Source of Truth, all granular Success Criteria, Implementation Tasks, and progress tracking are strictly maintained on GitHub issues which are also directly linked to our ZenHub Agile Board.
-
Epic 1: Register and Manage an Account — #1
- Summary: Covers the foundational user identity and profile system. It enables users to securely register, log in, and maintain a personal profile with athletic tags to give the community context when organizing or joining meetups.
-
User Stories:
- User Registration — #8: As a recreational participant, I want to create an account using my username, email, and password so that I have a registered identity on the platform.
- Registration Validation Errors — #9: As a recreational participant, I want to see clear validation errors during sign-up so that I understand why registration failed without creating a partial account.
- User Login — #10: As a registered user, I want to log into my account using my credentials so that I can establish an authenticated session.
- Invalid Login Error Handling — #11: As an unauthenticated user, I want invalid login attempts to display a generic error so that malicious actors cannot guess if my account exists.
- User Logout — #12: As an authenticated user, I want to securely log out of my account so that my session ends on shared browsers.
- View User Profile — #13: As a recreational participant, I want to view a user's profile and athletic tags so that I can see their sports background and home borough.
- Edit User Profile — #14: As a registered user, I want to edit my bio, home borough, and athletic tags so that my profile accurately reflects my current preferences.
- Profile Edit Authorization — #15: As a registered user, I want to ensure only I can edit my profile so that other members cannot modify my personal information.
-
Epic 2: Discover Parks and Facilities — #2
- Summary: Provides the core spatial directory for the platform, seeded by NYC Parks Open Data. Allows users to browse an interactive map and list view to find parks and filter by specific athletic amenities.
-
User Stories:
- Interactive Park Map — #16: As a recreational participant, I want to view an interactive map seeded with NYC parks so that I can explore nearby recreational spaces visually.
- Map/List View Toggle — #17: As a recreational participant, I want to switch between a map and list view so that I can browse parks in my preferred format.
- Filter by Location — #18: As a recreational participant, I want to filter parks by borough or neighborhood so that I can narrow down spaces in my area.
- Filter by Amenities — #19: As a recreational participant, I want to filter parks by specific athletic amenities so that I can find parks suitable for my sport.
- Empty State Feedback — #20: As a recreational participant, I want clear feedback when no parks match my filters or data is unavailable so that I understand why the directory is empty.
- Park Detail Page — #21: As a recreational participant, I want to view a park's detail page so that I can see its verified amenities, address, and facility information.
-
Epic 3: Create and Manage Recreational Events — #3
- Summary: Enables authenticated event organizers to generate public meetups tied to specific NYC park locations. Encompasses the entire lifecycle of an event including setting details, updating times, or canceling.
-
User Stories:
- Create Event Form — #22: As an event organizer, I want to create a public meetup tied to a park so that other players can discover and join my activity.
- View Upcoming Events — #23: As a recreational participant, I want to view upcoming events on park pages and the central feed so that I can see what activities are happening.
- Set Event Capacity — #24: As an event organizer, I want to set an optional participant limit so that my meetup does not become overcrowded.
- Edit Event Details — #25: As an event organizer, I want to edit my event details and skill requirements so that attendees have up-to-date logistical information.
- Capacity Reduction Validation — #26: As an event organizer, I want the system to prevent reducing capacity below active RSVPs so that registered attendees are never automatically removed.
- Event Modification Authorization — #27: As an event organizer, I want only myself or an administrator to modify or cancel my event so that unauthorized users cannot alter my meetup.
- Cancel Event — #28: As an event organizer, I want to cancel my event and freeze new RSVPs so that participants know the meetup is called off.
-
Epic 4: Join and Manage Event Participation — #4
- Summary: Handles the attendee side of recreational events. Allows users to browse upcoming events, signal attendance via RSVPs, enforce strict capacity limits, and display attendee rosters.
-
User Stories:
- Browse Upcoming Events — #29: As an unauthenticated or authenticated user, I want to browse upcoming public events and inspect their activity, schedule, location, and availability so that I can find recreational activities that match my interests and schedule.
- RSVP and Join Event — #30: As an authenticated recreational participant, I want to join an available event with open spots so that I can secure my attendance and be added to the event roster.
- Enforce Capacity Limit and Handle Concurrent Joins — #31: As an event organizer, I want strict participant limits enforced during RSVPs so that events do not exceed capacity even when multiple authenticated recreational participants attempt to join simultaneously.
- Cancel Personal RSVP — #32: As an authenticated recreational participant, I want to cancel my own RSVP to an event so that I can signal I am no longer attending and free up a spot for others.
- View Attendee Roster and Remove Participant — #33: As an event organizer, I want to view the attendee roster and remove recreational participants if necessary so that I can monitor attendance and ensure only eligible players participate.
-
Epic 5: Coordinate Through Event Discussions — #5
- Summary: Introduces the social communication layer necessary for organizing sports. Provides a dedicated in-app discussion thread on each event page for logistical coordination.
-
User Stories:
- View Event Discussion Thread — #34: As an authenticated recreational participant or event organizer, I want to view the dedicated discussion thread on the event page so that I can read logistic updates, questions, and announcements relevant to the activity.
- Post Message to Event Discussion — #35: As an authenticated recreational participant or event organizer, I want to post a message into the event discussion thread so that I can communicate details, ask questions, or coordinate logistics with other attendees.
- Post Organizer Announcements — #36: As an event organizer, I want to post prioritized announcements within my event discussion thread so that critical logistics such as court changes or weather updates are clearly visible to attendees.
- Edit and Delete Own Discussion Message — #37: As an authenticated recreational participant or event organizer, I want to edit or delete messages that I previously posted so that I can correct errors or remove outdated information.
- Moderate Discussion Content — #38: As an administrator, I want to delete inappropriate messages posted by any user so that the recreational platform maintains a safe and respectful communication environment.
-
Epic 6: Rate and Review Parks — #6
- Summary: Builds the community feedback loop for public infrastructure. Allows users to submit and read text reviews and 1-5 star ratings regarding facility conditions (e.g., lighting, court surfaces).
-
User Stories:
- View Park Reviews and Ratings — #39: As a recreational participant, I want to read park-specific reviews and ratings so that I can assess facility conditions before visiting.
- Submit Park Review — #40: As an authenticated recreational participant, I want to submit a 1–5 star rating and text review so that I can share useful feedback about a park.
- Edit and Delete Own Park Review — #41: As an authenticated recreational participant, I want to edit or delete my own reviews so that I can correct mistakes or remove outdated feedback.
- Park Rating Summary — #42: As a recreational participant, I want a park's displayed rating to reflect its current valid reviews so that the summary stays accurate.
- Moderate Park Reviews — #43: As an administrator, I want to remove inappropriate park reviews so that feedback remains useful and respectful.
-
Epic 7: Administer Parks and Moderate the Community — #7
- Summary: Provides platform administrators with the tools necessary to maintain a safe and accurate environment, including manual data entry, content moderation, and user management.
-
User Stories:
- Admin-Only Access Controls — #44: As an administrator, I want administrative tools restricted to my role so that participants and organizers cannot change protected data.
- Maintain Park Facility Information — #45: As an administrator, I want to add missing facilities and update existing park information so that the directory stays accurate.
- Report Content or Users — #46: As an authenticated user, I want to report problematic content or accounts so that administrators can review them.
- Review and Resolve Reports — #47: As an administrator, I want to review and resolve reports so that harmful content and accounts receive a clear outcome.
- Moderate Reported Events — #48: As an administrator, I want to correct or remove reported events so that invalid or inappropriate event information does not remain visible.
- Manage User Roles and Account Access — #49: As an administrator, I want to inspect accounts and change roles or access status so that abusive accounts can be restricted.
- Publish Platform Announcements — #50: As an administrator, I want to publish announcements so that users can receive platform-wide updates.
- View Platform Metrics — #51: As an administrator, I want to view platform metrics so that I can monitor usage and moderation work.
- View Administrative Audit Trail — #52: As an administrator, I want to see who made administrative changes and when so that moderation and data edits are traceable.
To ensure timely delivery of the core platform, the following features have been slated for future development (MLP and Nice-to-Haves):
- Live Status: Expiring court check-ins and crowdsourced "busy meters."
- Event Waitlists: Ordered waitlists with automatic promotion when spots open.
- Impromptu Broadcasts: Live borough broadcasts for games looking for immediate players.
- Accountability: Attendee reliability scores and sportsmanship badges.
- Live Condition Reporting: Crowdsourced real-time updates on facility conditions (e.g., "field lights are broken").
- Matchmaking: Algorithms to suggest relevant events based on user tags and preferences.
- External Integrations: Live weather API integration and syncing events to Google/Apple calendars.