Report
Data Entity
Description
A team or coordinator-level activity report record aggregating activity data across peer mentors in a local association. Distinct from bufdir_report — these are operational reports used by coordinators for team oversight, not mandatory Bufdir grant submissions. Scoped to an organization for multi-tenancy.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Globally unique identifier for the report record | PKrequiredunique |
organization_id |
uuid |
Foreign key to the owning organization. Multi-tenancy root — all report data is scoped to one organization. | required |
local_association_id |
uuid |
Foreign key to the local association whose peer mentor activity data is aggregated in this report. A coordinator's report is always scoped to one association. | required |
generated_by_user_id |
uuid |
Foreign key to the user (Coordinator or higher) who triggered generation of this report. | required |
report_type |
enum |
Classification of the report scope. team_activity aggregates all peer mentor activity; peer_mentor_activity is scoped to a single mentor; coordinator_summary is a high-level KPI snapshot. | required |
period_start |
datetime |
Inclusive start of the reporting period (UTC). Activities with date >= period_start are included. | required |
period_end |
datetime |
Inclusive end of the reporting period (UTC). Activities with date <= period_end are included. | required |
generated_at |
datetime |
Timestamp when report data aggregation completed. Null while status is pending or generating. | - |
status |
enum |
Lifecycle state of the report. Reports transition from pending → generating → complete or failed. | required |
filters |
json |
Snapshot of filter parameters used to generate this report: activity_type_id, peer_mentor_id, custom date overrides. Stored for reproducibility and audit. | - |
data |
json |
Aggregated report data payload as generated. Contains per-mentor activity counts, total hours, last activity dates, and summary totals. Populated on completion; null while pending/generating. | - |
row_count |
integer |
Number of peer mentor rows included in the aggregated report. Used for pagination hints and export size estimation. | - |
export_format |
enum |
Format of the most recent export of this report. Null if report has never been exported. | - |
exported_at |
datetime |
Timestamp of the most recent export action. Null if report has never been exported. | - |
error_message |
text |
Human-readable error description when status is failed. Used for coordinator feedback and debugging. | - |
created_at |
datetime |
Timestamp when the report record was created (report generation requested). | required |
updated_at |
datetime |
Timestamp of the most recent status or data update to this report record. | required |
Database Indexes
idx_report_organization_id
Columns: organization_id
idx_report_local_association_id
Columns: local_association_id
idx_report_generated_by_user_id
Columns: generated_by_user_id
idx_report_org_assoc_period
Columns: organization_id, local_association_id, period_start, period_end
idx_report_status
Columns: status
idx_report_created_at
Columns: created_at
Validation Rules
period_start_not_future
error
Validation failed
period_end_not_future
warning
Validation failed
organization_id_exists
error
Validation failed
local_association_id_exists
error
Validation failed
generated_by_user_exists
error
Validation failed
status_transition_valid
error
Validation failed
data_required_on_completion
error
Validation failed
filters_valid_json
error
Validation failed
Business Rules
organization_scoped_access
A report record is always owned by exactly one organization. No query may return report records from a different organization than the authenticated user's active organization context.
coordinator_association_scope
A Coordinator may only generate or read reports for local associations they are a member of via user_organization_roles. Organization Administrators may read all associations under their organization. Global Administrators have no restriction.
minimum_role_for_generation
Only users with Coordinator role or higher may create (trigger generation of) a report. Peer Mentors are explicitly excluded from report generation.
period_end_after_period_start
period_end must be strictly after period_start. Zero-length or inverted periods are rejected.
local_association_belongs_to_organization
The local_association_id must reference a local association that belongs to the same organization as organization_id. Cross-tenant association references are rejected.
data_immutable_after_completion
Once a report reaches status=complete, the data and filters fields must not be mutated. A new report record must be created if a re-run is required.
export_updates_metadata_only
Exporting a completed report updates only export_format and exported_at. The data and filters fields remain unchanged. Export does not alter report status.
CRUD Operations
Storage Configuration
Entity Relationships
An organization has many team and coordinator-level operational reports generated within it