Transcription State Manager
Component Detail
Description
A BLoC/Cubit that owns the dictation state machine for a single free-text field session: idle → requesting-permission → recording → processing → complete / error. Coordinates between the speech recognition service, the partial transcription repository, and the UI layer, ensuring state is always consistent and that partial results are persisted before the final result is committed.
transcription-state-manager
Summaries
The Transcription State Manager is the control centre that orchestrates the entire voice dictation experience, ensuring that microphone activation, real-time transcription display, and final text delivery all happen in a coordinated and reliable sequence. From a business perspective, its most important function is protecting data integrity: partial transcriptions are persisted before the final result is committed, meaning that if a session is interrupted by a call, a low-battery event, or an app backgrounding, users do not lose what they have already dictated.
It also enforces the product requirement that dictation is only permitted after the relevant activity has been completed, preventing incorrect workflow sequences that could have compliance or audit implications. By centralising all dictation logic in one place, it makes the feature easier to extend — for example, adding a new field type or a new permission model — without touching multiple scattered components.
This medium-complexity BLoC/Cubit component sits at the centre of the dictation feature's dependency graph, making it a coordination point that must be delivered and tested before the full UI integration can begin. It has three upstream dependencies — Speech Recognition Service, Partial Transcription Repository, and Dictation Scope Guard — all of which must be available for integration testing. The state machine has six states (idle, requesting-permission, recording, processing, complete, error) and the transitions between them must be tested exhaustively, including concurrent event handling (e.g., stopDictation called while permission request is in flight). The context validation via Dictation Scope Guard introduces a business-rule dependency that requires product sign-off on scope conditions before implementation can be finalised.
Plan for unit tests covering every state transition and error recovery path; these tests will be the primary regression safety net for future changes to the dictation feature.
The Transcription State Manager is a Flutter BLoC/Cubit implementing a finite state machine with states: idle, requesting-permission, recording, processing, complete, and error. `startDictation(FieldContext context)` first validates the context via `dictation-scope-guard` before delegating to `speech-recognition-service.startListening()`. During recording, it subscribes to `transcriptionStream()` and for each partial event calls `partial-transcription-repository.persist()` before emitting via `partialTranscriptionStream()`. On `stopDictation()`, it transitions to processing, awaits the final transcription event, commits it via `finalTranscription()`, then transitions to complete.
`cancelDictation()` calls `speech-recognition-service.cancelListening()` and clears persisted partials before returning to idle. All state transitions are guarded against invalid events (e.g., stop when already idle) to prevent the UI from driving the machine into an inconsistent state. Expose state and partial results as `Stream
Inject all dependencies through the constructor and provide a mock-friendly interface for unit testing each transition in isolation.
Responsibilities
- Drive the dictation state machine (idle, recording, processing, complete, error)
- Delegate start/stop commands to the speech recognition service
- Persist partial transcriptions after each engine emission
- Expose the current state and latest transcription text as observable streams
- Enforce the post-activity-only constraint by validating the calling context
Interfaces
startDictation(FieldContext context)
stopDictation()
cancelDictation()
stateStream()
partialTranscriptionStream()
finalTranscription()
reset()
Relationships
Dependencies (3)
Components this component depends on
Dependents (3)
Components that depend on this component
Used Integrations (1)
External integrations and APIs this component relies on