Document data access layer contracts and security model
epic-coordinator-statistics-dashboard-foundation-task-012 — Write developer documentation for the complete data access layer: StatsRepository API contracts, StatsCacheManager invalidation events and TTL behaviour, RoleAccessValidator scope rules and exception types, database view schema with index descriptions, dual-layer security model (RLS + validator), and GDPR compliance notes for NHF, HLF, and Blindeforbundet multi-org deployments. Include sequence diagrams for cache hit, cache miss, and invalidation flows.
Acceptance Criteria
Technical Requirements
Execution Context
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.
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.
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.
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.