Implement branding token injection in TenantContextService
epic-organization-selection-and-onboarding-core-logic-task-006 — Implement the branding token injection step: after terminology labels are loaded, fetch the org's branding configuration from OrgBrandingCache and apply design token overrides (primary color, logo asset path, font variant) into the Flutter ThemeData provider. Ensure the theme update is atomic and does not cause visible flash.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
The theme application must be a single atomic operation to avoid flicker. The recommended pattern is: construct the full new `ThemeData` object in memory first, then emit it as a single Riverpod state update — never update `primaryColor` and `textTheme` in separate notifier calls. Use Flutter's `ColorScheme.fromSeed(seedColor: tokens.primaryColor)` to generate a full Material 3 color scheme from the org's primary color — this ensures all derived colors (secondary, surface, onPrimary, etc.) are coherent and accessible. For WCAG contrast validation, implement a simple helper `bool meetsAA(Color foreground, Color background)` using the W3C relative luminance formula — this is a ~10-line utility function.
The `load` sequence in `SupabaseTenantContextService` after this task: (1) emit loading, (2) fetch labels → inject labels, (3) fetch branding → apply theme, (4) emit ready. Both steps 2 and 3 must complete before emitting `ready` to prevent partially-initialized tenant context reaching the UI.
Testing Requirements
Unit tests with `flutter_test`: (1) valid hex color string parses correctly to Flutter `Color`, (2) invalid hex string falls back to default primary color and logs a warning, (3) `OrgBrandingCache.get(orgId)` returns null on first call, the resolver fetches from Supabase, and a second call returns the cached value without a Supabase call, (4) `ThemeNotifier.applyBranding(tokens)` emits a single state update with the updated ThemeData — assert `notifyListeners` called exactly once, (5) org with no branding entry results in default theme being preserved. Widget integration test: wrap a `MaterialApp` with a `ThemeNotifier`-driven theme, call `applyBranding`, pump one frame, and assert the rendered primary color matches the injected value. WCAG contrast check: write a test that asserts a known low-contrast color triggers the fallback path.
TenantContextService must invalidate all downstream Riverpod providers when the org context changes (org switch scenario). If any provider caches org-specific data without subscribing to the tenant context, it will serve stale data from the previous org after a switch — which is both a UX failure and a potential GDPR violation.
Mitigation & Contingency
Mitigation: Define a single TenantContextProvider at the root of the Riverpod provider graph that all org-scoped providers depend on via ref.watch(). When TenantContextService.seedContext() runs, it invalidates TenantContextProvider which cascades invalidation to all dependents. Document this pattern in an architectural decision record so all developers follow it.
Contingency: Implement a post-switch integrity check that re-fetches a sample of each major data entity type and confirms the returned org_id matches the newly selected context; surface a reload prompt if any mismatch is detected.
MultiOrgMembershipResolver must query role assignments across potentially multiple tenant schemas. The anon or authenticated Supabase RLS policy may not permit cross-schema queries, making it impossible to return the full list of orgs a user belongs to in a single call.
Mitigation & Contingency
Mitigation: Design the membership query to use a dedicated Supabase edge function or a shared public schema view that aggregates role assignments across tenant schemas with a service-role key, returning only the org IDs the calling user is permitted to see. This keeps the client read-only.
Contingency: If cross-schema queries cannot be made safely, fall back to a per-org sequential membership check using the list of known org IDs and coalesce results client-side with appropriate timeout handling.
go_router redirect guards behave differently on web vs. mobile for deep links and browser back-button navigation. If the app is later deployed as a Progressive Web App (PWA) for admin use, the OrgRouteGuard may loop or fail to apply correctly on browser navigation events.
Mitigation & Contingency
Mitigation: Implement the guard as a GoRouter.redirect callback (not a ShellRoute redirect) following go_router best practices for platform-agnostic guards. Write widget tests that simulate navigation with and without auth/org context on both mobile and web target platforms in CI.
Contingency: If web-specific guard behaviour differs unacceptably, introduce a platform check in the guard and apply separate redirect logic branches for web vs. mobile until a unified solution is found.
In Phase 2 the OrgSelectionService will need to coordinate the handoff to BankID/Vipps authentication after the org is selected, storing the returned personnummer against the correct tenant's member record. If the service is designed too narrowly for Phase 1 email/password flow, retrofitting Phase 2 will require invasive changes to an already-tested component.
Mitigation & Contingency
Mitigation: Design OrgSelectionService with an AuthHandoffStrategy interface from the start (Phase 1 implementation: email/password, Phase 2: BankID/Vipps). The strategy pattern makes the Phase 2 swap an additive change rather than a rewrite. Stub the interface in Phase 1 with a TODO comment referencing the Phase 2 epic.
Contingency: If Phase 2 requirements diverge significantly from Phase 1 assumptions, create a dedicated Phase2OrgSelectionService subclass that extends the base and overrides the auth handoff step, preserving Phase 1 behaviour unchanged.