🏠 Overview › ✅ Implementation Tasks ›✅ epic-organization-selection-and-onboarding-core-logic-task-001

Define MultiOrgMembershipResolver Dart interface and data models

epic-organization-selection-and-onboarding-core-logic-task-001 — Define the abstract Dart interface for MultiOrgMembershipResolver including the OrgMembership model, MembershipResolutionResult (single/multi discriminated union), and session cache contract. Establish the Riverpod provider signature that downstream components will depend on.

critical priority low complexity backend pending backend specialist Tier 0

Acceptance Criteria

Abstract Dart class `MultiOrgMembershipResolver` is defined with a `resolve(String userId)` method returning `Future<MembershipResolutionResult>`
`OrgMembership` model contains: orgId (String), orgName (String), role (OrgRole enum: admin/coordinator/peerMentor), isActive (bool), and joinedAt (DateTime)
`MembershipResolutionResult` is a sealed class with two variants: `SingleOrgResult(OrgMembership membership)` and `MultiOrgResult(List<OrgMembership> memberships)`
Session cache contract is defined as an abstract `MembershipCache` interface with `get(String userId)`, `set(String userId, MembershipResolutionResult)`, and `invalidate(String userId)` methods
Riverpod provider is declared as `final multiOrgMembershipResolverProvider = Provider<MultiOrgMembershipResolver>((ref) => throw UnimplementedError())` in a dedicated providers file
All models are immutable (use `@immutable` annotation or `freezed` if in stack) with `==` and `hashCode` overrides
File structure follows existing project layer conventions (e.g., `lib/features/auth/domain/`)
No concrete Supabase or network code exists in this task — interface only
Dart analyzer reports zero errors and zero warnings on the new files

Technical Requirements

frameworks
Flutter
Riverpod
data models
OrgMembership
MembershipResolutionResult
MembershipCache
OrgRole
performance requirements
Interface methods must be designed to be async-safe (all return Futures)
Data models must be lightweight value objects with no heavy dependencies
security requirements
OrgMembership must not expose raw Supabase JWT or session tokens
userId parameter must be treated as opaque string — no logging of its value

Execution Context

Execution Tier
Tier 0

Tier 0 - 440 tasks

Implementation Notes

Use Dart sealed classes (available in Dart 3+) for `MembershipResolutionResult` to get exhaustive pattern matching in downstream consumers — this eliminates null checks and guards at call sites. Define `OrgRole` as an enum with `fromString` factory for safe deserialization from Supabase JSON. Place the cache contract in the same domain layer file as the resolver interface so they are versioned together. The Riverpod provider should use `Provider` (not `AsyncNotifierProvider`) at this stage since the interface is synchronous — the concrete implementation will override this in task-002.

Avoid using `freezed` unless it is already a declared project dependency, to keep this task self-contained.

Testing Requirements

Unit tests using `flutter_test`. Write tests for: (1) OrgMembership equality and hashCode correctness with identical and differing fields, (2) MembershipResolutionResult pattern matching — verify both SingleOrgResult and MultiOrgResult branches are exhaustively matchable via Dart `switch`, (3) OrgRole enum serialization roundtrip (String → enum → String), (4) a mock implementation of MultiOrgMembershipResolver can be constructed and its `resolve` method can be stubbed. Aim for 100% branch coverage on the model layer. No integration tests needed at this stage.

Component
Multi-Organization Membership Resolver
service medium
Epic Risks (4)
high impact medium prob technical

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.

medium impact medium prob security

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.

medium impact low prob technical

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.

medium impact medium prob scope

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.

Quick Links
All Tasks Execution Plan