Epic Architectures - gcivil-nyu-org/team3-mon-fall26 GitHub Wiki

The following sections are preliminary, forward-looking architectural drafts for future sprints. They serve as our Design Backlog for early team review, avoiding BDUF on our main architecture page.

Epic 1: Register and Manage an Account

Purpose and scope

This epic establishes the foundational user identity and profile system for NYC Active. It allows prospective recreational participants and organizers to securely register accounts, authenticate sessions through login and logout, and maintain a profile featuring athletic context (favorite sports, competitive vs. casual skill level, and primary home borough). Any authenticated user can organize events or RSVP without a separate organizer onboarding workflow. Administrative privilege assignment and account suspension are explicitly outside the scope of this epic and belong to Epic 7 (Administer Parks and Moderate the Community).

System components

The interface will provide dedicated screens for registration, login, profile view, and profile editing, with forms protected by Django's CSRF protection. Backend Django views will coordinate form validation and session management using Django's authentication framework. A proposed UserProfile model will maintain a one-to-one relationship with the core user model, storing athletic tags, skill level, and borough location. The server will enforce that users can view and edit only their own profile details, returning permission errors on unauthorized modification attempts. Database transactions will guarantee that user credentials and corresponding profile records are created atomically.

Register an account

A prospective user navigates to the registration screen, enters required credentials (such as email, username, and password), and submits the registration form. The Django server validates the input against password security standards and checks for existing duplicate accounts. Upon successful validation, the server atomically provisions the user credentials alongside an associated profile record within a database transaction and initializes an authenticated session. If validation fails due to duplicate credentials or password policy violations, the server rejects the request, leaves the database unchanged with no partial account created, and redisplays the form with actionable validation errors.

Authenticate and end a session

A user opens the login screen and submits their credentials. The server verifies the credentials against stored secure password hashes. Upon success, the server creates a new session, sets the authentication cookie, and redirects the user to their destination. If the credentials are invalid, the server rejects access, logs no session, and displays a generic error message that avoids revealing whether the username or password was incorrect. When an authenticated user selects logout, the server terminates the session, invalidates the session cookie, and routes the user back to the public view.

View and update a profile

An authenticated user navigates to their profile screen to review their personal details and athletic preferences. The server retrieves and displays their primary home borough, skill level, and preferred sports. To update these details, the user opens the profile editing interface, modifies the athletic tags or borough, and submits the changes. The server verifies that the authenticated user owns the targeted profile and validates the submitted fields before persisting the updates. If another user attempts to update a profile they do not own via direct request, the server returns 403 Forbidden. Invalid inputs result in actionable validation feedback, preserving previously saved profile data without partial updates.

Dependencies

Epic 1 serves as the foundational authentication and identity provider for the entire platform. It supplies authenticated user identity to Epic 3 (Events) for event creation and ownership, Epic 4 (Event Participation) for RSVPs and roster management, Epic 5 (Discussions) for posting permissions, and Epic 6 (Reviews) for submitting park evaluations. It coordinates with Epic 7 (Administer Parks and Moderate the Community), which provides administrative role assignment, moderation overrides, and account suspension enforcement on Epic 1 user accounts.

Validation

Implementation will be checked against stories #8–#15: valid registrations create complete user and profile records; invalid registration attempts produce actionable errors without creating orphaned records; correct credentials log users in; invalid credentials show a generic error without granting access; logout terminates the active session; users can successfully view and update their profile preferences; and unauthorized profile modification requests return 403 Forbidden. Automated tests will verify form validation logic, atomic creation rollback, session lifecycle, and ownership authorization checks.

References

Epic 2: Discover Parks and Facilities

Purpose and scope

This epic provides the core spatial directory for the platform, seeded by NYC Parks Open Data. It allows recreational participants to browse an interactive map and list view to find parks and filter by specific athletic amenities (e.g., basketball courts, soccer fields). It establishes the foundational park dataset that all other features (events, reviews) will build upon.

System components

The directory interface will include a Map/List toggle view, filters for borough and amenities, and a dedicated Park Detail template. The map will utilize a frontend mapping library (e.g., Leaflet.js or Mapbox) to render geospatial pins. Backend Django views will handle search queries and filtering. The database will include Park and Facility models, populated via an ingestion script from the NYC Open Data APIs/CSVs. The Django ORM will join these models using the official GISPROPNUM identifier to map athletic facilities to their parent parks.

View interactive map and list

A recreational participant navigates to the park directory. The server queries the Django ORM for park locations and passes the geospatial data (lat/long derived from Open Data multipolygons) to the frontend. The user can seamlessly toggle between the interactive map view and a paginated list view. Map panning and zooming will dynamically update the visible pins.

Filter parks by location and amenities

The user selects filter criteria such as Borough (e.g., "Brooklyn") or specific amenities (e.g., "Basketball = True"). The Django backend receives these query parameters, filters the joined Park and Facility tables, and returns the matching subset. If no parks match the criteria, the server returns a clean empty state UI explaining that no data is available.

View park details

The user clicks on a specific park pin or list item. The Django server routes them to the park's detail page, querying the database for all associated facilities. The UI displays the park's name, verified amenities, surface types (e.g., Asphalt, Turf), and accessibility status sourced directly from the ingested city data.

Dependencies

Epic 2 relies strictly on external data from NYC Parks Open Data (specifically the "Parks Properties" and "Athletic Facilities" datasets). It acts as a dependency for Epic 3 (Events), Epic 6 (Reviews), and Epic 7 (Admin Moderation), as those epics require valid park records to function.

Validation

Implementation will be checked against stories #16–#21: the map successfully renders coordinates; toggle and filters accurately subset the data; invalid or empty queries return a user-friendly empty state; and park detail pages display correct, joined facility data. Automated tests will verify the Django ORM filtering logic and the data ingestion script.

For team review

  • Map Provider: Decide between Leaflet.js + OpenStreetMap (free/open-source) vs. Mapbox/Google Maps API (requires API keys and potential AWS Secrets management).
  • Data Ingestion Strategy: Decide whether we will run a one-time Python seed script to load the CSVs into our Postgres database, or if we will write a scheduled cron job/Celery task to periodically fetch updates from the NYC Open Data API.
  • Geospatial Database: Confirm if standard latitude/longitude columns in PostgreSQL are sufficient, or if we need to implement PostGIS for complex spatial queries (like "Find parks within 2 miles").

References

Epic 4: Join and Manage Event Participation

Purpose and scope

This epic enables users to discover upcoming public events and authenticated participants to join or cancel their attendance. Organizers and participants can view attendee rosters; organizers and authorized administrators can remove participants. Participation respects Epic 3's capacity and cancellation settings. Waitlists and automatic promotion are outside the MVP.

System components

The interface will include an upcoming-event feed, event details, Join and Cancel RSVP controls, capacity indicators, and an attendee roster. Removal controls will be available only to the event organizer or an authorized administrator. Django views will query shared Event and account records. A proposed RSVP model will link an event and participant and record active attendance. Database constraints will prevent duplicate active RSVPs for the same event and user. Rosters, remaining capacity, and Epic 3's capacity-update checks will use the same active RSVP set. The server will enforce permissions for every change regardless of the controls displayed in the interface.

Browse upcoming events

An unauthenticated or authenticated user will open the discovery feed and select an event. The server will load upcoming public events and display activity, schedule, location, description, and availability. Past events will be excluded from the default feed. Events without a participant limit will not display a fixed number of remaining places. The feed and detail view will reuse Epic 3's event records and listing components.

Join an event and enforce capacity

An authenticated participant will submit a Join request. The server will check event existence, cancellation status, duplicate attendance, and available capacity before saving an RSVP. The proposed implementation will serialize participation changes for the same event within a database transaction and recheck the active RSVP count before committing. Epic 3's capacity updates and event cancellation must coordinate with the same event-level protection. If two users request the last place, only one will succeed. Successful joining will update the roster, capacity, and button to an Attending state. Full events will display Full and disable joining. Duplicate, full, cancelled, or unauthorized requests will produce actionable errors without changing attendance. Backend checks will apply even when a request bypasses the interface.

Cancel an owned RSVP

A participant will select Cancel RSVP and confirm. The server will verify ownership and remove the RSVP or mark it inactive according to the agreed retention policy. The roster and active count will update together. A full event will reopen when a place becomes available, provided it is still open for joining. Failed database operations will roll back without partial changes. If the client loses the response, it will reload the server state before confirming the outcome, since a missing response does not prove that cancellation failed.

View the roster and remove a participant

The organizer and authenticated participants will be able to view confirmed attendees. After a removal confirmation, the server will verify event ownership or administrator permissions before removing or deactivating the selected RSVP through the protected participation workflow. Available capacity will be recalculated from active RSVPs. Unauthorized removal requests will return 403 Forbidden; failed operations will preserve the roster and capacity.

Dependencies

Epic 4 depends on Epic 1 for authenticated accounts, Epic 3 for events, ownership, capacity, and cancellation, and Epic 2 for park information associated with events. Epic 7 supplies administrator permissions and account restrictions. Epic 5 will reuse active RSVP records to determine posting eligibility. These epics will share event and attendance records.

Validation

Implementation will be checked against stories #29–#33: upcoming events show the required details; past events are excluded; valid joins persist; duplicate, full, cancelled, and unauthenticated attempts leave attendance unchanged; concurrent requests cannot exceed capacity; self-cancellation releases a place; and participant removal is restricted to the organizer or an authorized administrator. Tests will cover transaction rollback, capacity reopening, and consistency between roster entries and remaining capacity. Concurrency checks will run against the selected production database. Relevant tests will pass and code will be reviewed before stories are marked done.

For team review

  • Shared discovery scope: Clarify the overlap between Epic 3 story #23 and Epic 4 story #29 and reuse one feed and detail view.
  • RSVP retention: Decide whether cancellation and removal delete the RSVP or mark it inactive. Align duplicate prevention and rejoining with that choice.
  • Database concurrency: Confirm the production database and transaction or locking approach shared by joins, removals, capacity updates, and cancellation. Local SQLite checks must not substitute for production concurrency checks.
  • Roster visibility: Confirm whether all authenticated participants or only attendees can view the roster, and which profile fields it displays.
  • Closed participation: Agree on joining past events and whether a participant removed by an organizer may rejoin, coordinating with Epic 3 and Epic 7.

References

Epic 5: Coordinate Through Event Discussions

Purpose and scope

This epic provides event-specific text discussions for attendees and organizers to coordinate logistics. It supports reading and posting messages, organizer announcements, author editing and deletion, and administrator moderation. Direct messaging, external chat integrations, and notification delivery are outside this epic. Visibility for non-attendees remains a team decision.

System components

The event detail page will include a chronological thread, an empty-state prompt, a message form, and author-specific edit and delete controls. Organizers will have a Post as Announcement option; authorized administrators will have moderation controls. Django views will load and change messages scoped to the shared Event record. A proposed DiscussionMessage model will contain event, author, text, creation and update timestamps, and an announcement flag. The server will check authentication, attendance or organizer status for posting, author ownership for editing, and administrator permissions for moderation. Epic 4's RSVP records will supply attendance status. Content will be rendered as escaped text, and form submissions will use Django's CSRF protection.

View an event discussion

An authorized user will open an event's discussion section. The server will retrieve only messages belonging to that event and show author, timestamp, and content in chronological order. Announcements will carry an Organizer Announcement badge. An empty thread will invite participants to start the conversation. The agreed visibility rules will also apply to direct message-fetch requests.

Post a discussion message

An authenticated attendee or the event organizer will submit text. The server will verify the event and posting permission, reject empty or whitespace-only content, and associate the saved message with the authenticated author and selected event. After saving, the thread will update to display the message. Unauthenticated direct API requests will return 401 Unauthorized; users without posting permission will be rejected. Invalid or failed writes will create no partial message. Displaying a newly submitted message does not require real-time chat infrastructure.

Post an organizer announcement

The organizer will compose a message and select Post as Announcement. The server will verify ownership of that specific event before saving the announcement flag. The message will appear in the correct thread with a distinct badge. Other participants will not see the control, and direct requests setting the flag without organizer permission will return 403 Forbidden. Announcements will remain chronological unless the team agrees to additional pinning behavior.

Edit and delete an owned message

An author will select Edit, submit updated text, and save. The server will verify ownership and event association and apply the same nonblank validation as creation. Successful updates will persist and show an Edited indicator. Authors may also select Delete and confirm; the server will verify ownership before removing the message from the thread. Other users' edit or delete requests will return 403 Forbidden. Failed changes will leave the stored message unchanged.

Moderate discussion content

An authorized administrator will be able to remove inappropriate messages. The server will verify the administrator role, apply the agreed deletion policy, and record the action through Epic 7's audit history. Organizers do not gain moderation rights over other authors' messages. Administrative removal does not grant permission to rewrite another author's text. Story #38 currently requires deletion from both database and thread; an alternative retention policy must be agreed and reflected in that acceptance criterion.

Dependencies

Epic 5 depends on Epic 1 for accounts and authentication, Epic 3 for event identity and organizer ownership, and Epic 4 for attendance. Epic 7 provides administrator permissions, account restrictions, reporting, and moderation audit history. These features will share account, event, participation, and discussion records.

Validation

Implementation will be checked against stories #34–#38: threads stay scoped to their event; messages show author, timestamp, and content; empty threads show a prompt; valid attendee or organizer messages persist; blank and unauthorized submissions are rejected; only the organizer can post announcements; edits show an Edited indicator; deletions persist across refreshes; and administrator removal is restricted and audited. Tests will cover direct-request permissions, escaped text rendering, and unchanged records after failed writes. Relevant tests will pass and code will be reviewed before stories are marked done.

For team review

  • Discussion visibility: Epic #5 leaves non-attendee access unresolved, while story #34 refers broadly to authenticated participants. Confirm who can read; posting remains restricted to attendees and the organizer under #35.
  • Former attendees and closed events: Decide whether former attendees can still read or manage their messages and whether past or cancelled event threads become read-only. Coordinate with Epic 3 and Epic 4.
  • Deletion and moderation: Reconcile #38's database deletion requirement with Epic 7's proposed hidden or removed status, including what the audit entry retains.
  • Announcement priority: Story #36 requires a badge and #34 requires chronological order. Confirm whether the badge suffices or a separate pinned area is needed.
  • Message limits: Agree on maximum text length and pagination and reflect these decisions in validation criteria.

References

Epic 6: Rate and Review Parks

Purpose and scope

This epic lets recreational participants evaluate parks through community reviews and 1–5 star ratings. Reviews can describe conditions such as court surfaces, lighting, water fountains, and bathroom availability. Authenticated participants can submit feedback and edit or delete their own reviews. Administrators can remove inappropriate reviews.

System components

The park detail page will display its review list and rating summary, a review form for authenticated users, and edit and delete controls for review owners. Administrative removal will use the moderation tools described in Epic 7. Backend components will load park-specific reviews, validate submissions, check ownership and administrative permissions, and calculate the rating summary. A shared Review record will contain the park, author, review text, rating, timestamps, and removal status if the team adopts the proposed retention policy.

View park reviews and ratings

Opening a park detail page will load valid, visible reviews linked to that park's identifier. The page will show each review's text and rating, including any amenity feedback. Reviews belonging to other parks will be excluded. The rating summary will use the same eligible review set.

Submit a park review

An authenticated participant will submit review text and a rating from 1 to 5 for the selected park. The server will verify the account, confirm that the park exists, and validate the required text and rating range before saving the review.

Edit and delete an owned review

A review owner will be able to edit its text or rating, or delete the review. The server will verify ownership using the authenticated account and stored author before changing the record.

Update the park rating summary

The server will calculate the displayed summary from the park's current valid, visible reviews. Removed reviews will not contribute to the summary. When the last valid review is removed, the page will return to the unrated state.

Moderate park reviews

An authenticated administrator will be able to remove an inappropriate review through Epic 7's moderation interface. The server will check the administrator's role before applying the removal.

Dependencies

Epic 6 depends on Epic 1 for authenticated accounts and permissions, Epic 2 for park records and the park detail page, and Epic 7 for administrative moderation, reports, and audit history. These workflows will share account, park, and review records.

Validation

Implementation will be checked against stories #39–#43: reviews stay scoped to the selected park; valid submissions appear; invalid or unauthenticated submissions create no record; owners can edit and delete their reviews; unauthorized changes leave records unchanged; and administrator removal updates both the list and summary. Tests will cover summary refresh after each change and the empty state when no valid reviews remain. Relevant tests will pass before code review is completed.

For team review

  • Review limit: Decide whether a participant can have one review per park or multiple reviews.
  • Rating summary: The proposed display is the arithmetic mean of eligible ratings plus the review count. Agree on rounding and display precision.
  • Review removal: Align owner deletion and administrator removal with Epic 7's proposed hidden or removed status.

References

Epic 7: Administer Parks and Moderate the Community

Purpose and scope

This epic gives NYC Active administrators the tools to maintain accurate park information, review reports, moderate inappropriate content, and manage abusive accounts. Participants and event organizers can report concerns, while administrators decide how to address them.

System components

The interface will include a report form for users and an administration area for authorized administrators. Backend components will validate requests, check permissions, and coordinate changes. Data models will read and update the application database.

Maintain parks and facilities

An administrator will open the park management interface, select an existing park or facility, and submit corrections. Administrators will also be able to add facilities or amenities missing from the imported NYC Parks data.

Submit and review reports

An authenticated participant or organizer will be able to report an event, discussion comment, park review, or user account. A Report record will contain the reporter, the target type and identifier, the reason, submission time, status, and resolution details.

Moderate events, comments, and reviews

An administrator reviewing a report will be able to correct a reported event description or remove inappropriate events, comments, and reviews from public view. Removed content will be excluded from public listings, direct detail views, and review-rating calculations.

Manage user accounts

Administrators will be able to inspect accounts and change authorized roles or active status. Suspending an account will prevent login and authenticated actions.

Announcements, metrics and audit history

Administrators will be able to create administrative announcements. An administrative summary will display platform metrics. An AuditEntry record will capture the administrator, action, affected record, timestamp, and reason for each successful administrative change.

Dependencies

Epic 7 depends on Epic 1 for authentication and account records, Epic 2 for park and facility data, Epic 3 for events, Epic 4 for participation restrictions, Epic 5 for discussion comments, and Epic 6 for reviews and ratings. It will reuse their records rather than create separate copies.

Validation

Implementation will be checked against Epic 7's acceptance criteria: participants and organizers cannot perform administrative actions; invalid park updates do not overwrite valid data; reports reach the moderation queue; moderation decisions update public content and report status; suspended accounts cannot perform authenticated actions; and successful administrative changes appear in audit history.

For team review

  • Content removal: The proposed approach is to mark content as hidden or removed rather than immediately erase it.
  • Account removal: Confirm how permanent removal should affect events, comments, reviews, and RSVP records.
  • Announcement placement: Decide where administrative announcements should appear.
  • Platform metrics: Confirm the final metrics and their definitions.
  • Shared components: Align the Report, Announcement, and AuditEntry record names with the team's shared design.

References