Tenant Context Service
Component Detail
Description
Central service responsible for seeding and maintaining the active tenant context after an organization is selected. Loads organization-specific terminology labels, feature flags, and branding tokens into the app state so all downstream screens render correctly for the selected organization. Acts as the single source of truth for the current tenant throughout the session.
tenant-context-service
Summaries
The Tenant Context Service is the core infrastructure that makes the platform's multi-tenant model commercially viable. It is the engine that transforms a single application into a branded, configured experience for each partner organization — loading their unique terminology, feature permissions, and visual identity at session start. Without this service, every partner would receive an identical generic interface, eliminating the white-label value proposition that justifies enterprise licensing fees. The service also enforces feature flag boundaries between organizations, ensuring that premium or pilot features are only exposed to authorized tenants, protecting both revenue differentiation and contractual obligations.
Secure session persistence means users resume their correct organizational context without friction on every app launch.
TenantContextService is the highest-complexity component in this group and a critical path dependency for the majority of the application's screens. It must be completed before the multi-org switcher, the org selection service handoff, and any screen that renders org-specific branding or feature-flagged content. Plan for four to six days of development, integration testing, and security review. Complexity drivers include: async loading of terminology and branding tokens, feature flag application to global app config, secure storage integration for session persistence, and stream-based reactive exposure to BLoC and Riverpod providers.
Key risks are latency on setTenantContext() affecting perceived app startup performance, and data consistency if the org profile changes between sessions. Load testing with multiple org configurations is recommended before release.
TenantContextService is a high-complexity shared service that must be initialized before any UI depending on org-specific data renders. setTenantContext(String orgId) is the primary entry point — it should sequentially fetch org terminology labels, feature flags, and branding tokens from OrganizationRepository, then persist the orgId via SecureStorageAdapter and update TenantSessionStore. Expose a watchTenantContext() stream (backed by a StreamController or Riverpod StateNotifierProvider) so UI layers react to context changes without polling. getTerminologyLabel(), isFeatureEnabled(), and getBrandingToken() are synchronous accessors that read from the in-memory cache populated during setTenantContext() — these must throw or return sensible defaults if called before context is set.
clearTenantContext() must purge both in-memory state and secure storage. Write integration tests covering: context set → read → clear cycle, session resumption on cold start, and behavior when org profile is unavailable.
Responsibilities
- Load and cache org-specific terminology label mappings
- Apply organization feature flags to the global app config
- Inject branding tokens (colors, logos) into the design token system
- Expose the current tenant context to all BLoC and Riverpod providers
- Persist the selected org ID to secure storage for session resumption
Interfaces
setTenantContext(String orgId) -> Future<void>
clearTenantContext() -> Future<void>
getCurrentOrgId() -> String?
getTerminologyLabel(String key) -> String
isFeatureEnabled(String featureKey) -> bool
getBrandingToken(String tokenKey) -> dynamic
watchTenantContext() -> Stream<TenantContext>
Relationships
Dependencies (3)
Components this component depends on
Dependents (4)
Components that depend on this component
Related Data Entities (3)
Data entities managed by this component