Bufdir Report
Data Entity
Description
A structured compliance report submitted to Bufdir (Norwegian Directorate for Children, Youth and Family Affairs) by a member organization. Aggregates peer mentor activity data for a defined reporting period into the field schema required by Bufdir, supporting one-click generation and export for grant accountability.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key, immutable after creation | PKrequiredunique |
organization_id |
uuid |
Foreign key to the organization that owns this report. Enforces tenant isolation — all queries must be scoped to this value. | required |
reporting_period_start |
datetime |
Inclusive start of the Bufdir reporting period (typically the first day of a calendar year or half-year cycle) | required |
reporting_period_end |
datetime |
Inclusive end of the Bufdir reporting period (typically the last day of a calendar year or half-year cycle) | required |
status |
enum |
Lifecycle state of the report. Controls which operations are permitted. | required |
bufdir_format_version |
string |
Version identifier of the Bufdir field-mapping specification used to generate this report. Ensures reproducibility and traceability when the format spec changes. | required |
report_data |
json |
The fully mapped Bufdir report payload as structured JSON, keyed by Bufdir field identifiers. Stored at generation time so re-export does not require re-aggregation. | - |
activity_count |
integer |
Total number of approved activity records included in this report | - |
participant_count |
integer |
Count of unique contacts (participants) represented across all included activities | - |
volunteer_count |
integer |
Count of unique peer mentors who logged at least one approved activity in the reporting period | - |
total_hours |
decimal |
Sum of all activity durations (in hours) included in the report, as required by Bufdir's quantitative reporting fields | - |
generated_at |
datetime |
Timestamp when report_data was successfully populated and status transitioned to 'ready' | - |
generated_by_user_id |
uuid |
User ID of the Coordinator or Org Admin who triggered report generation | - |
export_format |
enum |
File format selected at the time of export. Null until the report is exported. | - |
exported_at |
datetime |
Timestamp of the most recent export action. May be updated on re-export. | - |
exported_by_user_id |
uuid |
User ID of the actor who performed the most recent export | - |
export_file_path |
string |
Object storage key or path of the most recently generated export file. Used by the PDF/XLSX export adapter to serve signed download URLs. | - |
failure_reason |
text |
Human-readable error description populated when status transitions to 'failed'. Used for admin diagnostics. | - |
notes |
text |
Optional free-text notes from the Org Admin or Coordinator, e.g. explaining anomalies in the data before submission | - |
created_at |
datetime |
Record creation timestamp, set server-side on insert | required |
updated_at |
datetime |
Last modification timestamp, updated on every write | required |
Database Indexes
idx_bufdir_report_org_id
Columns: organization_id
idx_bufdir_report_org_period
Columns: organization_id, reporting_period_start, reporting_period_end
idx_bufdir_report_status
Columns: status
idx_bufdir_report_created_at
Columns: created_at
Validation Rules
period_start_before_end
error
Validation failed
period_not_entirely_in_future
error
Validation failed
organization_must_exist_and_be_active
error
Validation failed
export_format_required_on_export
error
Validation failed
report_data_required_before_export
error
Validation failed
missing_required_bufdir_fields_warning
warning
Validation failed
Business Rules
tenant_isolation
Every read and write operation must be scoped to the authenticated user's organization_id. A user from Organization A must never be able to read or modify Organization B's Bufdir reports.
role_required_for_generation
Only users with Coordinator or Org Admin role may trigger report generation. Peer Mentors have no access to Bufdir report records.
role_required_for_export
Only Coordinator or Org Admin may export a report. Enforced by Export Access Guard before any signed URL or file is served.
unique_report_per_org_per_period
Only one Bufdir report record may exist per organization per reporting period. Attempting to generate a duplicate report for an existing period must raise a conflict error.
only_approved_activities_included
The report_data payload must aggregate only activities with status 'approved'. Pending or rejected activities must be excluded from all Bufdir metrics.
format_version_pinned_at_generation
The bufdir_format_version is set at generation time from the active format specification and must not change after the report reaches 'ready' status. This guarantees re-exports reproduce the same field mapping.
export_audit_required
Every export action (status transition to 'exported') must produce an immutable audit log entry recording user ID, org ID, period, format, and timestamp.
status_transition_valid
Status must follow the allowed state machine: pending → generating → ready → exported. Transitions to 'failed' are allowed from 'generating'. Direct jumps (e.g. pending → exported) are not permitted.