Bufdir Alignment Validator
Component Detail
Description
Service that verifies the aggregation logic used by the dashboard exactly matches the counting rules that will be applied at Bufdir export time. Runs on-demand during development and as a diagnostic tool to confirm zero reconciliation delta between displayed totals and exported totals.
bufdir-alignment-validator
Summaries
The Bufdir Alignment Validator directly protects the organization's credibility and funding position by ensuring that every number displayed on staff dashboards is identical to what gets submitted in official Bufdir reports. Discrepancies between reported and actual figures pose a compliance risk and could trigger audits or funding complications. By making reconciliation automatic and continuous, this component eliminates the manual cross-checking that previously consumed coordinator time and introduced human error. The result is a faster, more confident reporting cycle and a defensible audit trail that demonstrates organizational integrity to government stakeholders.
This component sits at the intersection of two critical delivery streams — the dashboard display pipeline and the Bufdir export pipeline — and must be developed after both are sufficiently stable to validate against. Its medium complexity means a single mid-senior developer can own it within a one-to-two sprint window, but scheduling depends on the stats-repository and export service being functionally complete first. Testing requires coordinated data fixtures that exercise edge cases in aggregation logic, including partial windows, missing entries, and role-boundary conditions. Regression risk is moderate: any future change to either the dashboard aggregation or the export logic must re-trigger validation runs, making this component a living diagnostic checkpoint throughout the project lifecycle.
The Bufdir Alignment Validator is a service-layer component that accepts two parallel snapshot objects — a StatsSnapshot representing dashboard-computed totals and an ExportSnapshot representing Bufdir-export-computed totals — and performs field-level comparison across all aggregated dimensions. It exposes three interfaces: a synchronous validate() method returning a structured ValidationResult, a getDiscrepancies() method returning a typed List
Key implementation consideration: the aggregation logic used internally must mirror the exact SQL or RPC logic used in the export pipeline — any divergence in rounding, null handling, or boundary inclusivity will produce false positives.
Responsibilities
- Cross-check dashboard aggregation results against export aggregation logic
- Report discrepancies with field-level detail for debugging
- Expose a flag indicating whether dashboard and export totals are aligned
Interfaces
validate(StatsSnapshot dashboard, ExportSnapshot export) ValidationResult
getDiscrepancies(StatsSnapshot dashboard, ExportSnapshot export) List<Discrepancy>
isAligned(String peerMentorId, TimeWindow window) Future<bool>