Sequence Diagrams

This page documents the dynamic behavior of the Neighborhood Accessibility Mapper system. Each section below represents a core use case scenario modeled using UML Sequence Diagrams.

The diagrams illustrate the interaction between Actors (Users, Admins) and System Components (Objects, Services), focusing on the message flow and focus of control.

---

1. User Registration & Profile Creation

Refinement Notes & Assumptions

• Constructor Definition: The Sequence Diagram depicts the instantiation of RegisteredUser following a successful registration submission. The Class Diagram should be updated to include a constructor method: +RegisteredUser(email: String, fullName: String, passwordHash: String).

• Registration Data Collection: GuestUser.register() is shown triggering a self-call collectRegistrationData() to represent the form-filling step before credentials are submitted. This method is currently implied by the register() interaction but not explicitly defined in the Class Diagram. The Class Diagram should be updated to include: +collectRegistrationData() : void on GuestUser.

• Input Validation Abstraction: The login() method on RegisteredUser is reused as the entry point for credential submission during registration. A self-call validateInputs(email, passwordHash, fullName) is introduced to represent pre-persistence validation logic (format checks, required fields). This should be considered a private helper method and added to the Class Diagram as: +validateInputs(email: String, passwordHash: String, fullName: String) : Boolean.

• MobilityProfile Factory Access: MobilityProfile setup is shown as a direct creation step following account activation, called createMobilityProfile(mobilityAid, preferences). The Class Diagram defines MobilityProfile attributes and a 0..1 association to RegisteredUser but includes no constructor or factory method. The Class Diagram should be updated to include: +MobilityProfile(mobilityAid: MobilityAidType, avoidStairs: Boolean, avoidSteepSlopes: Boolean, maxSlopeGradient: Double).

• Missing NotificationType Value: The welcome notification sent at the end of registration uses NotificationType.REPORT_VERIFIED as the closest available enum value. No REGISTRATION_COMPLETE value currently exists in the NotificationType enum. It is assumed this value will be added. The Class Diagram NotificationType enum should be updated to include: REGISTRATION_COMPLETE.

• Database Abstraction: Since no specific Service or DAO classes exist in the Class Diagram, the VerificationEngine lifeline is used to represent both spam detection and trust scoring logic, acting as the controller for all validation-related data operations during registration. Internal calls such as checkPassiveTimeout() and calculateValidationScore() are represented as self-calls and should be considered private helper methods within VerificationEngine.

---

2. Route Calculation with Accessibility Filters

Refinement Notes & Assumptions

• Constructor Definition: The Sequence Diagram depicts the instantiation of RouteRequest using a create(origin, destination) message. The Class Diagram should be updated to include a constructor method: +RouteRequest(origin: GeoPoint, destination: GeoPoint).
• User-Profile Access: RouteRequest requires access to the user's MobilityProfile to apply accessibility filters. We assumed RegisteredUser has a public accessor method like +getMobilityProfile(), which is currently implied but not explicitly defined in the Class Diagram interactions.
• Search & Pin Return Values: The search() and dropPin() methods in MapView are shown returning specific coordinate objects (destination_point, origin_point) to be used as inputs for the route request.
• Internal Logic Abstraction: The calculate() method logic is visualized using self-calls (checkAccessibility, excludePathSegment) to represent the internal filtering algorithms required by SRS 1.2.2. These should be considered as private helper methods within the RouteRequest class logic.
• Database Abstraction: Since no specific "Service" or "DAO" classes exist in the Class Diagram, a generic Database lifeline is used to represent the retrieval of ObstacleReport objects. RouteRequest acts as the controller managing this data retrieval.

---

3. Submitting a New Obstacle Report

Refinement Notes & Assumptions

• Deduplication Logic: The system uses a Proximity Service to check a 20-meter radius before creation; if a match is found, the user confirms the existing issue instead of creating a duplicate pin.
• Media Optimization: Photos are compressed and stored via Cloud Storage, with the database saving only the URI to maintain high performance.
• Smart Status Transition: Reports are initialized as "Unverified" by default, but the system triggers Auto-Verify if the registered user's Trust Score exceeds the threshold.
• Unique Identification: Every submission is assigned a Unique ID by the database for municipal tracking and resolution.
• Authentication & Profile: It is assumed the user is logged in, allowing the system to verify their identity and current trust level.
• Hardware & Connectivity: The device is assumed to have active GPS and Camera permissions, with a stable network available for real-time cloud and server interaction.
• Spatial Infrastructure: The central database is assumed to support geospatial indexing to handle proximity queries efficiently.

---

4. Community Verification (Upvoting Logic)

Refinement Notes & Assumptions

• Interaction Constructor: The sequence diagram instantiates an Interaction object for the UPVOTE. The Class Diagram should explicitly add a constructor to handle this: +Interaction(type: InteractionType, target: ObstacleReport).
• Data Retrieval for Scoring: To calculate the validation score accurately, VerificationEngine needs to evaluate existing votes. It is assumed ObstacleReport has an implied accessor method like +getInteractions(): List<Interaction>.
• Audit Trail: When a report's status changes to VERIFIED, a StatusChange object must be created to log the transition, maintaining the Class Diagram's ObstacleReport "1" *-- "*" StatusChange composition relationship.
• Duplicate Prevention: It is assumed upvoteReport() contains internal business logic to prevent users from upvoting their own submissions or voting multiple times on the same report.
• Notification Trigger: Upon successful verification, the system is assumed to trigger a message to the original reporter utilizing the existing NotificationType.REPORT_VERIFIED enum value.

---

5. Authority Issue Resolution

## Refinement Notes & Assumptions

• Dashboard as Shared Resource: The Sequence Diagram shows InfrastructureAuthority accessing a single shared Dashboard instance. This is consistent with the Class Diagram's many-to-one relationship (InfrastructureAuthority "*" -- "1" Dashboard), where all officers share one dashboard and filter issues individually rather than having separate dashboard instances.

• Photo Creation & Attachment: The diagram depicts a two-step process: first creating a Photo object with PhotoType = POST_REPAIR, then attaching it to the ObstacleReport via addPhoto(). The Class Diagram's composition relationship (ObstacleReport "1" *-- "1..*" Photo) supports this, but the ObstacleReport class should be updated to include an explicit +addPhoto(photo: Photo) method if not already present.

• StatusChange as Audit Trail: When the status is updated to RESOLVED_AWAITING_VALIDATION, a StatusChange object is created with fromStatus = VERIFIED and toStatus = RESOLVED_AWAITING_VALIDATION. This relies on the composition relationship (ObstacleReport "1" *-- "*" StatusChange) in the Class Diagram. The StatusChange class currently lacks a constructor; it should include +StatusChange(from: ReportStatus, to: ReportStatus, notes: String).

• Mandatory Pre-conditions for Resolution: The alt fragment enforces that both a post-repair photo and official notes must be provided before the status can change. This business rule is implied by SRS 1.5.3 but is not explicitly modeled in the Class Diagram. A validation method such as -validateResolutionRequirements(): Boolean could be added to InfrastructureAuthority as a private helper.

• Notification Triggering: The VerificationEngine is used to trigger notifications to the original reporter and all users who previously upvoted the report. This assumes VerificationEngine has access to the Interaction records (type = UPVOTE) to identify affected users. The Class Diagram's dependency (VerificationEngine ..> ObstacleReport) supports reading report data, but an additional dependency on Interaction may be needed: VerificationEngine ..> Interaction.

• Repair Notes Storage: The addRepairNotes() method is shown on InfrastructureAuthority, but the notes themselves are stored in the StatusChange.notes field when the status transition is recorded. No separate "RepairNotes" entity exists in the Class Diagram; the StatusChange class serves this purpose.

---

6. Admin Moderation & User Banning

Refinement Notes & Assumptions

• ModerationQueue as an Implicit Object: The Class Diagram does not define a dedicated ModerationQueue class. In the Sequence Diagram, it is introduced as a conceptual lifeline to represent the admin's view of flagged reports. In practice, this could be implemented as a filtered query on ObstacleReport objects where associated Interaction records have type = FLAG. The Class Diagram may benefit from either a dedicated class or a method on Administrator such as +viewModerationQueue(): List<ObstacleReport> (which already exists).

• Flagging via Interaction: The flagReport() method on RegisteredUser creates an Interaction object with type = FLAG. This is consistent with the Class Diagram's InteractionType enum which includes FLAG, and the RegisteredUser → Interaction ("performs") association. The flag count for a given report can be derived by counting Interaction records of type FLAG targeting that ObstacleReport.

• VerificationEngine for Spam Detection: The detectSpam() method on VerificationEngine is used by the Administrator to assist in content review. The Class Diagram already defines this method on VerificationEngine. The dependency VerificationEngine ..> ObstacleReport supports reading report data for analysis.

• StatusChange as Audit Trail for Deletion: When a report is deleted (status set to CLOSED), a StatusChange object is created with fromStatus = REPORTED and toStatus = CLOSED along with admin notes. This is consistent with the composition relationship ObstacleReport "1" *-- "*" StatusChange. The StatusChange class should include a constructor: +StatusChange(from: ReportStatus, to: ReportStatus, notes: String) — the same recommendation noted in Section 5.

• banUser() and Account Status Transition: The banUser() method on Administrator changes the target RegisteredUser's status attribute from ACTIVE to BANNED, using the AccountStatus enum. A corresponding StatusChange-like audit record is created for the user ban. Note: The current Class Diagram tracks StatusChange only for ObstacleReport; if user account status changes also need an audit trail, a similar mechanism (or a generalized StatusChange) should be introduced for RegisteredUser.

• suspendUser() as an Alternative Path: The Class Diagram defines both +banUser() and +suspendUser() on Administrator. The Sequence Diagram models the banUser() path (permanent ban, AccountStatus = BANNED). A similar alternative flow could use suspendUser() with AccountStatus = SUSPENDED for less severe violations. This could be modeled with an alt fragment if needed.

• Notification with SPAM_WARNING Type: The NotificationType enum includes SPAM_WARNING, which is used to notify the offending user about the moderation action. The Notification class's +send() method handles delivery. The diagram assumes Notification can be created with a recipient reference, though the Class Diagram does not explicitly show a recipient attribute — this could be added as -recipient: RegisteredUser or derived from the report's submitter.

• Database Lifeline: As with other sequence diagrams in this project, a generic Database lifeline is used to represent persistence operations. This is not modeled in the Class Diagram but is necessary to show where state changes (report status, user status, interaction records, notifications) are committed.

---

7. Trust Score Update & Badge Awarding

Refinement Notes

• RegisteredUser.incrementTrustScore() — New method. The class diagram defines trustScore : Integer as an attribute but has no dedicated method to modify it. This method encapsulates the trust score increment logic.
• Database lifeline — Added to explicitly represent persistence operations. Not modeled in the class diagram but necessary to show where state changes (status, trustScore, badge, notifications) are committed.