Report Form Orchestrator
Component Detail
Description
Coordinates the full lifecycle of a post-session report: loading the org schema, initialising form state via Bloc/Riverpod, validating all fields on submit, assembling the report payload, and triggering persistence. Ensures the report is always linked to its parent activity record.
report-form-orchestrator
Summaries
The Report Form Orchestrator is the engine that ensures post-session reports are completed accurately and linked correctly to the activity records that drive organisational outcomes measurement. Without reliable report submission, organisations lose visibility into session quality, compliance evidence, and participant progress data — all of which directly affect funding accountability and program evaluation. This component handles the complexity of organisation-specific field schemas, meaning the same mobile application can serve multiple organisations with different reporting requirements without custom builds. By enforcing validation before submission and guaranteeing every report is tied to its parent activity, it protects data integrity at the point of collection, reducing costly data cleaning and reconciliation efforts downstream.
High data quality at submission translates directly to more trustworthy dashboards, better decision-making, and stronger compliance posture.
This is a high-complexity mobile service component with three hard dependencies: report-schema-service, report-field-validator, and post-session-report-repository. All three must reach API stability before end-to-end integration testing of the orchestrator can begin, making this a scheduling risk if any dependency slips. The component manages a multi-state form lifecycle (draft, validating, submitting, success, error), which requires thorough state transition testing including offline scenarios, partial submissions, and network failure recovery. Because it is tied to two data models — post-session-report and report-field-schema — any schema evolution will require coordinated updates across the orchestrator, validator, and repository layers.
State management is implemented via Bloc/Riverpod, so the team needs Flutter state management expertise. Allocate additional QA time for multi-org schema variance testing to ensure the schema-loading path handles all supported field configurations correctly.
The Report Form Orchestrator is a high-complexity mobile service component built with Bloc or Riverpod for state management. It initialises via initReport(activityId), which anchors the entire form lifecycle to a specific activity record — this foreign key association must be preserved through every state transition and included in the final payload. loadSchema(orgId) fetches and caches the org-specific field schema from report-schema-service; cache invalidation strategy should be considered for orgs that update schemas between sessions. Form state transitions flow through: draft → validating (on validateForm()) → submitting (on submitReport()) → success or error, with getFormState() exposing current state to the UI layer and resetForm() returning to draft.
updateField(fieldId, value) should dispatch granular state updates to avoid full widget rebuilds on each keystroke. The report-field-validator dependency handles per-field constraint evaluation; the orchestrator aggregates results and blocks submission on any failure. The post-session-report-repository is the persistence boundary — ensure the assembled payload conforms to the post-session-report and report-field-schema data model contracts before dispatch.
Responsibilities
- Load and cache org-specific field schema for the active organisation
- Manage form state (draft, validating, submitting, success, error)
- Validate all field values against schema constraints before submission
- Assemble and submit report payload linked to activity_id
Interfaces
initReport(activityId)
loadSchema(orgId)
updateField(fieldId, value)
validateForm()
submitReport()
getFormState()
resetForm()
Relationships
Dependencies (3)
Components this component depends on
Related Data Entities (3)
Data entities managed by this component