Duplicate Detection BLoC
Component Detail
Description
Flutter BLoC state management unit for the duplicate detection flow. Manages the state transitions between idle, checking, duplicate-found (with candidates), proceeding, merging, and resolved states. Consumed by both the activity wizard and the coordinator deduplication queue screen.
duplicate-detection-bloc
Summaries
The Duplicate Detection BLoC directly protects the organization's data quality by preventing duplicate activity records from entering the system before they corrupt reports and analytics. Clean, deduplicated data reduces the administrative burden on coordinators who would otherwise spend significant time manually identifying and reconciling conflicting entries. Accurate activity records strengthen the reliability of member engagement metrics used in strategic planning, grant reporting, and stakeholder presentations. By embedding automatic deduplication directly into the activity submission workflow, this component eliminates a recurring operational pain point at zero marginal cost per submission, supporting scalable data governance and preserving organizational credibility with funders and partners.
This medium-complexity BLoC manages the state machine for the full duplicate detection and resolution lifecycle and has hard dependencies on the duplicate-detection-service and duplicate-resolution-handler, both of which must reach stability before this component can be integrated and tested end-to-end. It surfaces in two distinct screens—the activity wizard and the coordinator deduplication queue—creating two separate testing surfaces that require coordination between UI and service teams. Each of the six state transitions (idle, checking, duplicate-found, proceeding, merging, resolved) needs independent test coverage, including edge cases around async race conditions during RPC calls. Budget additional QA time for integration testing across both screen contexts and ensure service contracts are locked down early to avoid late-stage rework.
This Flutter BLoC implements a six-state machine: idle → checking → duplicateFound (carrying the candidate list payload) → proceeding or merging → resolved or cancelled. It depends on duplicate-detection-service for the RPC call that returns match candidates and on duplicate-resolution-handler for post-decision side effects. Events are CheckForDuplicatesEvent, ProceedAnywayEvent, MergeActivityEvent, and CancelSubmissionEvent. The Stream
Guard mapEventToState transitions with isClosed checks and use switchMap or equivalent to prevent stale RPC responses from advancing state after cancellation. The activity data model is the primary payload carried through intermediate states.
Responsibilities
- Manage state machine for the full duplicate detection and resolution lifecycle
- Emit DuplicateFound state with candidate list when RPC returns matches
- Emit Resolved or Cancelled state after user action is processed
- Reset to idle state when activity wizard is closed or submission is complete
Interfaces
add(CheckForDuplicatesEvent)
add(ProceedAnywayEvent)
add(MergeActivityEvent)
add(CancelSubmissionEvent)
state DuplicateDetectionState
stream Stream<DuplicateDetectionState>
Relationships
Dependencies (2)
Components this component depends on