Document foundation contracts and write developer integration guide

epic-speech-to-text-input-foundation-task-014 — Write a developer-facing integration guide documenting all four foundation components: NativeSpeechApiBridge (platform abstraction contract and usage patterns), DictationScopeGuard (compliance rule and integration requirements for any consumer), PartialTranscriptionRepository (crash-resilience pattern and session lifecycle), and AccessibilityLiveRegionAnnouncer (usage guidelines and politeness levels). Include Riverpod provider dependency graph and sequence diagrams for the permission request flow.

high priority low complexity documentation pending documentor Tier 4

Acceptance Criteria

Guide covers all four components: NativeSpeechApiBridge, DictationScopeGuard, PartialTranscriptionRepository, AccessibilityLiveRegionAnnouncer

Each component section includes: purpose, public API (method signatures), usage example in Dart, and integration constraints

DictationScopeGuard section explicitly documents the business rule: dictation is prohibited during active peer mentoring sessions

AccessibilityLiveRegionAnnouncer section documents all supported politeness levels (polite, assertive) and when to use each per WCAG 2.2 AA

A Riverpod provider dependency graph (text-based Mermaid diagram or equivalent) is included showing provider relationships

A sequence diagram for the microphone permission request flow is included (covering: first-launch, already-granted, denied, permanently-denied)

Guide is written in English and is self-contained — a new developer can integrate all four components without reading source code

All code examples compile against the actual implemented interfaces

Technical Requirements

frameworks

Flutter

Riverpod

data models

ScopeGuardResult

PartialTranscription

SpeechPermissionState

security requirements

Document that DictationScopeGuard is a compliance control — consumers must not bypass it

Note GDPR/privacy implications: dictation is blocked during sessions to prevent inadvertent recording of session content

Execution Context

Execution Tier

Tier 4

Tier 4 - 323 tasks

Can start after Tier 3 completes

View Full Execution Plan

Implementation Notes

Use Markdown format stored in the repository under docs/speech-to-text/foundation-integration-guide.md. For the Riverpod dependency graph, use a Mermaid flowchart block (supported by most Markdown renderers). For sequence diagrams, use Mermaid sequenceDiagram syntax. Prioritize practical 'how to consume' documentation over internal implementation details.

Include a 'Common Mistakes' section covering: forgetting to check ScopeGuardResult before starting dictation, not handling the mid-session blocking stream event, and misusing AccessibilityLiveRegionAnnouncer politeness levels. Document that all four components are designed to be tested without platform channels — mock strategies should be included.

Testing Requirements

No automated tests for documentation. However, all Dart code examples in the guide must be manually verified to compile and run correctly against the implemented APIs before the guide is merged.

A peer review by at least one other developer who was not involved in the implementation is required to validate clarity.

Component

Native Speech API Bridge

infrastructure medium

Dependencies (4)

Write unit and widget tests for AccessibilityLiveRegionAnnouncer. Verify that announcements are dispatched via SemanticsService, that rapid calls are debounced correctly, that assertive announcements bypass debounce, and that the announcer is a proper singleton with no duplicate registrations. Use flutter_test and mock SemanticsService. epic-speech-to-text-input-foundation-task-005 Write comprehensive unit tests for all PartialTranscriptionRepository methods using an in-memory SQLite test database. Cover: successful save and retrieval, session-scoped isolation, stale record cleanup, concurrent write safety, and crash-recovery scenario where saved data survives app restart simulation. epic-speech-to-text-input-foundation-task-003 Write integration tests using flutter_test and mock MethodChannel handlers to validate the full NativeSpeechApiBridge lifecycle on both iOS and Android simulated environments. Test: permission grant/deny flows, partial result streaming, final result delivery, error propagation (network unavailable, no speech detected, permission denied), and graceful stop/cancel without resource leaks. epic-speech-to-text-input-foundation-task-010 Write thorough unit tests for DictationScopeGuard covering all state transitions: dictation allowed when no session active, dictation blocked when session is active, mid-dictation blocking when session starts during an ongoing dictation, and correct reason codes returned in ScopeGuardResult. Use mocked ActiveSessionState providers to simulate all scenarios without platform dependencies. epic-speech-to-text-input-foundation-task-013

Epic Risks (3)

high impact medium prob technical

iOS 15 on-device speech recognition has a 1-minute session limit and requires network fallback for longer sessions. Peer mentor way-forward dictation may routinely exceed this limit, causing silent truncation of transcribed content without user feedback.

Mitigation & Contingency

Mitigation: Implement session-chunking logic in NativeSpeechApiBridge that automatically restarts recognition before the limit is reached, preserving continuity via partial concatenation. Document the iOS 15 vs iOS 16 on-device recognition behaviour difference in code comments.

Contingency: If chunking causes user-visible interruptions, surface a non-blocking informational banner on iOS 15 devices informing users that very long dictation sessions may need to be broken into segments, and use PartialTranscriptionRepository to persist each chunk immediately.

high impact medium prob scope

On iOS, speech recognition permission can only be requested once. If the user denies the permission, the app cannot re-request it. A poor first-impression permission flow will permanently disable dictation for those users, impacting the Blindeforbundet blind-user base who rely on dictation most.

Mitigation & Contingency

Mitigation: Design the NativeSpeechApiBridge permission flow to show a clear pre-permission rationale screen before the OS dialog. Implement a graceful degradation path that hides the microphone button and shows a settings deep-link when permission is permanently denied.

Contingency: If users have already denied permission before the rationale screen is added, provide a settings deep-link in DictationScopeGuard's denial message directing users to iOS Settings > Privacy > Speech Recognition to re-enable manually.

medium impact low prob integration

The approved field IDs and screen routes configuration in DictationScopeGuard may fall out of sync with the actual report form schema as new fields are added by org administrators, silently blocking dictation on legitimately approved fields.

Mitigation & Contingency

Mitigation: Source the approved field configuration from the same org-field-config-loader used by the report form, rather than a hardcoded list. Add a developer-time assertion that logs a warning when a dictation-eligible field type is rendered but not in the approved routes map.

Contingency: Provide a runtime override mechanism in the scope guard that coordinators or admins can use to temporarily whitelist a field ID while the config is updated, with an automatic expiry.

Quick Links

All Tasks Execution Plan