Activity Registration Cubit
Component Detail
Description
Bloc/Cubit that owns the complete wizard state machine for the Quick Activity Registration flow. Each wizard step has its own state slice; the Cubit validates completeness before allowing progression and coordinates the final Supabase insert with optimistic local state update.
activity-registration-cubit
Summaries
The Activity Registration Cubit is the business logic engine behind the Quick Activity Registration feature — the core workflow through which peer mentors log their work. Its optimistic local state update ensures the app feels instantaneous even on poor network connections, which is critical for field adoption where connectivity is unreliable. By pre-populating intelligent defaults, it reduces the time-per-submission, directly increasing the volume of activity data captured. Higher data capture volume means better programme visibility, more accurate reporting, and stronger outcomes evidence for stakeholders and funders.
This component is the operational backbone of mentor engagement and data quality, making it one of the highest-value components in the mobile application.
This is the highest-complexity component in the registration wizard and carries the most delivery risk. It manages a multi-step state machine, integrates with two external dependencies (ActivityRegistrationService and RegistrationDefaultsManager), and coordinates an optimistic insert pattern that requires careful handling of success, failure, and rollback scenarios. Plan for 4–6 days of development, plus dedicated QA time covering all wizard step transitions, validation edge cases, offline/flaky network behaviour, and state reset after submission. The Supabase async confirmation path must be tested with simulated latency and failure injection.
Dependency on RegistrationDefaultsManager means that component must be stable before integration testing can begin. Treat this as a critical path item.
ActivityRegistrationCubit is a BLoC/Cubit managing a multi-slice wizard state machine. Each field (activityType, date, duration, notes) is a discrete state slice; the currentStep index drives which view is active. On init, loadDefaults() calls RegistrationDefaultsManager to pre-populate sensible values. advanceStep() and retreatStep() guard transitions — advanceStep() runs field-level validation and emits a validation error state rather than advancing if required fields are absent.
submitRegistration() performs an optimistic local insert (emit success state immediately for UX) then awaits ActivityRegistrationService.save(); on service failure it rolls back local state and emits a failure state with an error payload. reset() returns the Cubit to its initial state for re-use. Unit test every state transition, validation guard, and the optimistic rollback path with mocked service responses.
Responsibilities
- Manage step-by-step wizard state (current step, each field value)
- Pre-populate defaults from RegistrationDefaultsManager on initialisation
- Validate required fields before allowing step advancement
- Coordinate optimistic local insert and async Supabase confirmation
- Emit registration success or failure states to the UI
Interfaces
loadDefaults()
selectActivityType(ActivityType type)
setDate(DateTime date)
setDuration(int minutes)
setNotes(String? notes)
advanceStep()
retreatStep()
submitRegistration()
reset()
Relationships
Dependencies (2)
Components this component depends on
Dependents (5)
Components that depend on this component