medium priority low complexity documentation pending documentor Tier 5

Acceptance Criteria

StatsRepository API contract documents every public method: signature, parameters, return type, thrown exceptions, and a usage example
StatsCacheManager section describes all TTL values (default and overrides), supported partition key formats, the invalidation event schema, and LRU capacity configuration
RoleAccessValidator section lists every supported role (coordinator, org_admin, global_admin), the exact scope each role is granted, and the exception type thrown for each violation
Database view schema section includes the view name, all column names and types, the WHERE clause used, and the indexes that serve each query pattern
Dual-layer security section explains how RLS (enforced by Supabase) and RoleAccessValidator (enforced in Dart) complement each other, and what each layer protects against
GDPR compliance section covers: what personal data is returned by each query, data minimisation rationale, retention policy, and any org-specific constraints for NHF, HLF, and Blindeforbundet
Three sequence diagrams are included: cache hit flow, cache miss flow, and mutation-triggered invalidation flow — each as Mermaid or PlantUML embedded in the Markdown
All exception type names in the documentation match the actual Dart class names in the codebase
A member of another team can read the document and correctly answer: 'Which exception is thrown when a coordinator queries another coordinator's data?' and 'How long does a cached stats query remain valid by default?'

Technical Requirements

frameworks
Flutter
Dart
Supabase Flutter SDK
apis
Supabase RLS
Supabase PostgREST
data models
StatsRepository
StatsCacheManager
RoleAccessValidator
StatsCachePartition
MutationEvent
StatsAccessDeniedException
performance requirements
Documentation must accurately reflect the ≤ 100 ms indexed-lookup SLA established in integration tests
security requirements
No real credentials, project URLs, or user IDs may appear in documentation examples — use placeholder values like <SUPABASE_URL>
GDPR section must be reviewed by a team member familiar with Norwegian data protection requirements before merge

Execution Context

Execution Tier
Tier 5

Tier 5 - 253 tasks

Can start after Tier 4 completes

Implementation Notes

Write the documentation as a Markdown file at docs/data-access-layer.md. Structure it with the following top-level sections: Overview, StatsRepository API Reference, StatsCacheManager Reference, RoleAccessValidator Reference, Database Views and Indexes, Dual-Layer Security Model, GDPR Compliance, Sequence Diagrams, and Changelog. Use Mermaid sequenceDiagram blocks for the three diagrams — they render natively in GitHub and most documentation platforms. For the GDPR section, focus on: (a) which fields constitute personal data (coordinator ID, peer mentor name, activity notes), (b) that queries return only aggregated or role-scoped data, (c) that raw activity notes are never returned in stats queries, and (d) that Blindeforbundet has stricter requirements around epikrise data that must never intersect with the stats layer.

Verify all exception type names by running grep -r 'class Stats.*Exception' lib/ before writing.

Testing Requirements

Documentation quality is verified through a peer review checklist: (1) every public API method in StatsRepository has a corresponding entry in the docs, (2) all exception class names match grep output against the Dart source, (3) all three sequence diagrams render without errors in a Mermaid previewer, (4) GDPR section is reviewed by a team member with knowledge of Norwegian GDPR obligations. No automated test suite is required for documentation, but the review checklist must be completed and signed off before the task is closed.

Component
Role Access Validator
service low
Epic Risks (3)
high impact medium prob technical

Pre-aggregated Supabase views may still be slow for orgs with very large activity datasets (NHF with 1,400 chapters). If the view query plan performs sequential scans, dashboard load times could exceed acceptable thresholds and degrade the perceived value of the feature.

Mitigation & Contingency

Mitigation: Design views with composite indexes on (org_id, coordinator_id, month) from the start. Run EXPLAIN ANALYZE during development against a seeded dataset of realistic scale. Add materialized view refresh strategy if needed.

Contingency: If live view performance is insufficient, convert to materialized views refreshed on a schedule or on activity-write triggers. Expose the refresh delay transparently in the UI with a 'last updated' timestamp.

high impact low prob security

Supabase RLS policies for the stats views may not be configured correctly during initial migration, potentially allowing cross-coordinator data leakage before the RoleAccessValidator layer is reached. This is a security and compliance risk.

Mitigation & Contingency

Mitigation: Write RLS integration tests as part of this epic that explicitly verify a coordinator JWT cannot read another coordinator's stats rows. Apply RLS policies in the migration script itself, not as a manual step.

Contingency: If an RLS gap is discovered post-deployment, immediately disable the stats screen via a feature flag, apply the corrected RLS migration, and re-enable after verification. Log and audit all queries that ran during the gap window.

medium impact medium prob integration

Cache invalidation logic may not be triggered correctly when a new activity is registered by a peer mentor or when an expense approval is granted. Stale data could cause coordinators to make decisions based on outdated KPIs, undermining trust in the dashboard.

Mitigation & Contingency

Mitigation: Define explicit invalidation event contracts with the activity registration and expense approval pipelines. Implement an event bus subscription within StatsCacheManager. Document the invalidation contract in code.

Contingency: If event-driven invalidation proves unreliable, add a manual 'Refresh' pull-to-refresh gesture on the dashboard and reduce TTL to 5 minutes as a fallback degradation strategy.