Requirements - bounswe/bounswe2026group11 GitHub Wiki

📖 Glossary

This section defines key terms used throughout the requirements to ensure consistent interpretation.

Administrator (Admin)

A privileged system role responsible for maintaining platform integrity. Administrators review reported events, manage the event category list, evaluate category suggestions submitted by users, and perform moderation actions when platform policies are violated.

Event

An activity organized by a host that has a location, time interval, description, privacy level, and participation constraints.

Event Discussion

A comment thread associated with an event where users can discuss event details, ask questions, or provide additional information related to the event.

Event Report

A complaint submitted by a user regarding an event that may violate platform policies (e.g., harmful content, hate speech, illegal activity). Reports are reviewed by administrators or moderators.

Event Status

Represents the lifecycle stage of an event. Possible values:

Active – event is upcoming or ongoing
Completed – event has ended (transitioned automatically when the end time passes)
Canceled – event has been canceled by the host

Event Tag

A flexible keyword label attached to an event to improve discoverability and filtering. Tags may represent specific attributes such as activities, equipment, or themes. Tags can be created by users and attached to events.

Event Version

A saved snapshot of an event's state at a given point in time. Each edit made by the host creates a new version. All versions are retained and visible to participants as a changelog.

Feedback

A post-event review submitted by a participant after event completion. Feedback consists of a mandatory rating score and an optional written message. Only users with an Approved participation record for the completed event may submit feedback.

Guest

A user who has been invited by the host to a private event. A guest may accept or decline the invitation.

Host

The user who creates and manages an event. The host has permissions to edit or cancel events, approve or reject join requests, manage invitations, and scan participant tickets.

Invitation

A direct request sent by the host to a specific user to join a private event. Invitations are delivered via email and in-app notification and include the event name, host name, event time, and options to accept or decline.

Join Request

A request submitted by a user to participate in a protected event. Possible states:

Pending – awaiting host decision
Approved – accepted by the host
Rejected – denied by the host
Expired – the request was not acted upon before the event
Canceled – canceled by the requester

Moderate Load

A workload level representing typical usage expected under normal operating conditions, including multiple users browsing, searching, and joining events; hosts managing events and approving join requests; and standard notifications being delivered.

Moderation Review

The process of evaluating reported events to determine whether they violate platform policies. Moderation may result in actions such as restricting or removing the event.

Notification Types

Categories of notifications that users may receive:

Push – real-time mobile or web notifications
Email – notifications sent to the user's registered email address
In-App – notifications stored and visible in the application's activity feed or inbox

Organizer Reliability Score

A computed score associated with a host, derived from the average ratings of their completed events and their event cancellation rate. The score is visible on event detail pages.

Participant

A user whose participation status in an event is Approved. Only approved participants are counted in official event metrics.

Participation

A record representing a user's involvement in an event, created when a join request is approved, or an invitation is accepted, or directly when joining public events.

Participation Status

Indicates the current state of a user's involvement in an event. Possible values:

Waiting Confirmation – the host should approve the join request, or the user must reconfirm attendance following a critical event change
Approved – user is an active, confirmed participant
Canceled – user has withdrawn, or the event is cancelled Only users with Approved status are counted as official participants in event metrics.

Private Event

An event that is only visible to invited users. Private events do not appear in search or map views. Participation is only possible through a direct invitation from the host.

Protected Event

An event that is visible in discovery results but requires host approval before a user can join. Users may view event details and submit a join request, which the host must accept before participation is confirmed.

Public Event

An event that is visible to all users and can be joined without host approval.

Reconfirmation

A process requiring participants to confirm their continued attendance after a critical change (time, location, or participation constraints) has been made to an event. Until reconfirmation is completed, the participant's status is set to Waiting Confirmation.

Relevance Score

A computed metric used to rank events in search and discovery results. May consider:

Distance from the user
Time proximity (how close the event is to the current time)
User preferences
Organizer reliability score
Popularity metrics

Ticket

A digital entry pass generated automatically after a user's participation is approved. Each ticket includes the participant's name, event title, date/time, and a unique QR code. Possible ticket statuses:

Valid – active and ready for scanning
Used – successfully scanned by the host; no longer valid for entry
Canceled – voided due to event cancellation or user withdrawal
Expired – event has ended without the ticket being scanned

✅ Functional Requirements

1. User Management & Profiles

1.1 User Registration & Login

1.1.1 The system shall allow users to register using phone number–based authentication.
1.1.2 The system shall send a verification code via SMS during registration.
1.1.3 Users shall be able to log in using phone number or email or username + password.
1.1.4 The system shall prevent login with invalid credentials and display an error message.

1.2 User Profiles

1.2.1 A user profile shall contain a profile photo, name, and bio.
1.2.2 Users shall be able to edit their profile information.
1.2.3 Users shall view their participation history, organized events, and ratings.

1.3 Participation History

1.3.1 The system shall record all events a user created or attended.
1.3.2 Users shall filter participation history by keyword, date, category, or location.

2. Event Creation & Structure

2.1 Event Creation

2.1.1 Users shall create events via a “Create a New Event” button.
2.1.2 The following fields shall be mandatory during event creation:
- Location
- Time interval (start & optional end time)
- Category
- Description
- Event image
- Host (auto-filled as the logged-in user)
2.1.3 The system shall validate that all mandatory fields are filled.
2.1.4 Users shall upload an image or choose from predefined icons.
2.1.5 Host shall create optional participation constraints like age-limit or required equipments.

2.2 Location Model

2.2.1 The location shall support a single point or a multi-point route.
2.2.2 The system shall validate map coordinates before saving.
2.2.3 The system shall allow users to open an event location directly in Google Maps.
2.2.4 Clicking the event location shall open the Google Maps application or web interface with navigation directions.
2.2.5 The system shall support both single-point locations and route-based events.

2.3 Categorization

2.3.1 Users shall select a category from a predefined list.
2.3.2 The system shall allow category filtering.
2.3.3 Each event shall have exactly one category selected from the predefined category list.
2.3.4 Users shall be able to submit suggestions for new categories.
2.3.5 Only administrators shall be able to approve and add new categories to the system.

2.4 Custom Tags

2.4.1 Users shall be able to add up to 5 custom tags.
2.4.2 Users shall be able to mark tags as favorite for faster event discovery.

3. Privacy & Access Control

3.1 Privacy Levels

3.1.1 The system shall support three privacy types:
- Public
- Protected (join request + approval)
- Private (invitation only)
3.1.2 Private events shall not appear in search or map views.
3.1.3 Only invited users shall be able to view private events.

3.2 Join Request Logic

3.2.1 Public events may allow open join requests.
3.2.2 Protected events shall require host approval.
3.2.3 Hosts shall accept or reject join requests.

3.3 Access Control

3.3.1 Only hosts shall be able to edit the events.
3.3.2 Unauthorized users shall see an “Access Denied” view.

3.4 Guest Invitations & Management

3.4.1 The system shall allow hosts to invite multiple users simultaneously by uploading a list of usernames for private events.
3.4.2 When inviting guests, the system should provide an auto-complete search function to find registered users by username.
3.4.3 Hosts shall be able to view a real-time guest list showing who has Accepted, Declined, or Not Responded.

4. Event Lifecycle Management

4.1 Event Status Model

4.1.1 Each event shall have one of the following statuses:
Active, Completed, Canceled.
4.1.2 An event shall automatically move from Active to Completed when its end time passes.
4.1.3 Canceled events shall remain visible to participants with a visible "Canceled" badge.
4.1.4 Only the host shall be able to cancel an event.

4.2 Event Editing

4.2.1 Only the host shall edit an event.
4.2.2 The system shall record each edit as a new event version.
4.2.3 The system shall maintain a visible changelog for participants.
4.2.4 Participants shall receive notifications when critical changes occur:
- Start / End Time (Reconfirmation Required)
- Location / Route (Reconfirmation Required)
- Participation Constraints (Reconfirmation Required)

4.3 Reconfirmation Logic

4.3.1 If time or location is changed after approval, previously approved participants shall be required to reconfirm attendance.
4.3.2 If privacy level changes to Private, non-invited participants shall lose access.
4.3.3 Reconfirmation requests shall trigger a notification.

4.4 Join Request State Handling

4.4.1 Join requests shall have one of the following states:
Pending, Approved, Rejected, Expired,Canceled.
4.4.2 Approved users shall automatically gain full event access, and their 'Participation Status' shall be set to 'Approved'.
4.4.3 Rejected users shall not see detailed participant information, and a participation record will not created for these users.

4.5 Participation Status Model

4.5.1 Each approved join request shall create a Participation record for the event.
4.5.2 A Participation shall have one of the following statuses: Waiting Confirmation, Approved, Canceled.
4.5.3 Participation status shall be Waiting Confirmation until user reconfirms attendance after major event changes.
4.5.4 Participation status shall become Approved when:
- Host approves the join request, or
- User reconfirms attendance after a required reconfirmation.
4.5.5 Participation status shall become Canceled if:
- User withdraws from the event, or
- Host removes the participant from the event.
4.5.6 Only users with Approved participation status shall be considered official participants in event metrics.

5. Discovery & Search

5.1 Visibility Rules

5.1.1 Public and Protected events shall appear in map and list views.
5.1.2 Private events shall only appear to invited users.
5.1.3 Protected events shall display limited details to non-approved users.

5.2 Geospatial Filtering

5.2.1 Users shall filter events by selecting a radius distance.
5.2.2 Route-based events shall be discoverable if any point of the route intersects the selected radius.

5.3 Time Filtering

5.3.1 Users shall filter events using start and end date ranges.
5.3.2 Events outside the selected time interval shall not appear in results.

5.4 Category & Tag Filtering

5.4.1 Users shall filter events by predefined categories.
5.4.2 Users shall filter events by custom tags.

5.5 Search Behavior

5.5.1 Search shall match across:
- Event title
- Description
- Tags
- Location name
5.5.2 Search results shall respect privacy and access control rules.

5.6 Favorite Locations

5.6.1 Users shall define favorite locations.
5.6.2 Favorite locations may be used as default discovery centers.

5.7 Ranking & Prioritization

5.7.1 Events shall be ranked based on relevance score.
5.7.2 Relevance may consider:
- Distance
- Time proximity (how close is event to the current time)
- User preferences
- Organizer reliability score
- Popularity metrics

6. Interaction & Engagement

6.1 Save / Favorite Events

6.1.1 Users shall save events to a personal favorites list.
6.1.2 Saved events shall be accessible from a dedicated section.

6.2 Event Metrics

6.2.1 Each event shall display:
- Number of approved participants
- Number of pending requests (host only)
- Number of saves (to favorites)
6.2.2 Metrics shall update in every page refresh.

6.3 Feedback & Rating

6.3.1 Only users who participated in a completed event shall be able to leave feedback.
6.3.2 Feedback shall include:
- Rating score (mandatory)
- Optional message
6.3.3 Feedback section shall only be enabled after event completion.

6.4 Organizer Reliability

6.4.1 Each host shall have a reliability score derived from:
- Average event ratings
- Cancellation rate
6.4.2 Reliability score shall be visible on event detail pages.

6.5 Event Discussions

6.5.1 Each event shall provide a discussion section where users can post comments.
6.5.2 Only authenticated users shall be able to post comments.
6.5.3 Comments shall be displayed in chronological order.
6.5.4 Hosts shall be able to delete inappropriate comments within their events.
6.5.5 Users shall be able to edit or delete their own comments.

7. Notifications

7.1 Real-Time Updates

7.1.1 The system shall support notifications via Push (Mobile/Web) and Email.
7.1.2 Users should have the ability to toggle specific notification types.
7.1.3 The application shall include an in-app "Inbox" or "Activity Feed" where all past notifications are stored for at least 7 days.

7.2 Event Changes

7.2.1 Notifications shall be triggered for the following changes to events:
- Time changes
- Location changes
- Event cancellations

7.3 Join Requests

7.3.1 Hosts shall receive notifications when users request to join their events.
7.3.2 Users shall receive notifications when their join requests are accepted or rejected.

7.4 Private Event Invitations

7.4.1 Invited users shall receive both email and in-app invitations.
7.4.2 Notifications shall include:
- Event name
- Host name
- Event time
- Options to accept or decline the invitation

8. Archiving & History

8.1 Past Events Archive

8.1.1 Events shall automatically move from "Active "to the “Past” status once they have ended.

8.2 Searchable History

8.2.1 Archived events shall be searchable by users.
8.2.2 To comply with privacy standards, the system shall provide an option for users to "Clear History," which anonymizes their participation data while retaining aggregate stats for platform analytics.

8.3 Historical Data Retention

8.3.1 Historical data shall be retained for analytics purposes.

9. Ticket Generation & Validation

9.1 Ticket Generation

9.1.1 Upon successful join (for public events) or host approval (for protected/private events), the system shall generate a unique digital ticket for the participant.
9.1.2 Each ticket shall be associated with a unique QR Code containing an encrypted or signed token for secure identification and validation.
9.1.3 The ticket view shall display the participant’s name, event title, date/time, and the unique QR Code.
9.1.4 QR codes shall not be displayed in the web interface; they shall only be accessible through the mobile application.

9.2 Ticket Status & States

9.2.1 Each ticket shall have a Status field with the following possible values:
- Valid: The ticket is active and ready for scanning.
- Used: The host has successfully scanned and validated the ticket; it is no longer valid for entry.
- Canceled: The ticket is void due to event cancellation or user withdrawal.
- Expired: The event has ended without the ticket being marked as "Used."

9.3 QR Scanning

9.3.1 The system shall provide a "Scan Ticket" interface accessible only to the event host.
9.3.2 Upon scanning a participant's QR code, the system shall verify the ticket's authenticity and check if the current status is "Valid."
9.3.3 If the ticket is valid, the system shall:
- Update the status to "Used" in the database immediately.
- Display a success confirmation to the host.
- Timestamp the entry for audit purposes.
9.3.4 If the ticket has already been marked as "Used," "Canceled," or "Expired," the system shall display an error message to the host and deny entry.

10. Event Reporting & Moderation

10.1 Reporting Events

10.1.1 Users shall be able to report events they consider inappropriate or harmful.
10.1.2 Reports shall include a reason selected from predefined categories (e.g., hate speech, harassment, illegal activity, misleading information).
10.1.3 The system shall store reported events for moderation review.

10.2 Moderation Review

10.2.1 Reported events shall be reviewed by moderators.
10.2.2 Moderators shall be able to mark events as:
- Approved (no violation)
- Restricted
- Removed
10.2.3 If an event is removed due to policy violations, participants shall receive a notification.
10.2.4 Moderation decisions shall be logged for auditing purposes.

⚙️ Non-Functional Requirements

11. Performance

11.1 Query Performance

11.1.1 Geospatial queries should ideally respond within 300ms under moderate load.
11.1.2 Search queries should ideally respond within 200ms under moderate load.

11.2 Scalability

11.2.1 The system shall be able to handle multiple concurrent users.
11.2.2 The notification service should support batch notifications efficiently.

12. Reliability & Integrity

12.1 Data Integrity

12.1.1 Event versioning shall maintain atomicity.
12.1.2 No data loss shall occur during updates.
12.1.3 The system shall maintain an audit trail for all critical data modifications.

12.2 Concurrent Access

12.2.1 The system shall prevent conflicting concurrent edits.

13. Security

13.1 Secure Authentication

13.1.1 Passwords shall be hashed using industry-standard procedures and algorithms (e.g., Argon2).
13.1.2 Verifications (e.g. SMS, E-Mail) shall be rate-limited.

13.2 Access Isolation

13.2.1 Private event and user data shall be restricted from unauthorized users.
13.2.2 Invitation lists shall be securely stored or encrypted.

13.3 Data Protection

13.3.1 Backups shall maintain the same security protections as primary data sources.

13.4 Application Security

13.4.1 Security-relevant events (login attempts, access violations, deletion approvals) shall be logged for monitoring and auditing.