Activity Flag
Data Entity
Description
An audit record marking an activity as suspicious, duplicate, requiring review, or otherwise flagged by an administrator or coordinator. Supports the Activity Oversight workflow in the Admin Web Portal.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
activity_id |
uuid |
FK to activities table — the activity being flagged | required |
flagged_by_user_id |
uuid |
FK to users table — admin or coordinator who raised the flag | required |
organization_id |
uuid |
FK to organizations table — tenant scoping | required |
flag_type |
enum |
Category of flag raised on the activity | required |
reason |
text |
Human-readable explanation for why the flag was raised | required |
status |
enum |
Resolution state of this flag | required |
resolution_note |
text |
Note recorded when flag is resolved or dismissed | - |
resolved_by_user_id |
uuid |
FK to users — admin who resolved or dismissed the flag | - |
resolved_at |
datetime |
Timestamp when the flag was resolved or dismissed | - |
duplicate_of_activity_id |
uuid |
For flag_type=duplicate: FK to the activity this is considered a duplicate of | - |
auto_detected |
boolean |
True when flag was raised by DuplicateDetectionService rather than a human | required |
created_at |
datetime |
Timestamp when the flag was created | required |
updated_at |
datetime |
Timestamp of last update to this flag record | required |
Database Indexes
idx_activity_flags_activity_id
Columns: activity_id
idx_activity_flags_organization_status
Columns: organization_id, status
idx_activity_flags_flagged_by
Columns: flagged_by_user_id
idx_activity_flags_created_at
Columns: created_at
idx_activity_flags_flag_type_status
Columns: flag_type, status
Validation Rules
reason_min_length
error
Validation failed
resolved_at_set_on_terminal_status
error
Validation failed
duplicate_of_activity_id_only_for_duplicate_type
error
Validation failed
duplicate_of_activity_id_different_from_activity_id
error
Validation failed
flagged_by_user_must_have_coordinator_or_admin_role
error
Validation failed
organization_id_matches_activity_organization
error
Validation failed
Business Rules
single_open_flag_per_type_per_activity
Only one open flag of a given flag_type may exist per activity at a time. Attempting to raise a duplicate type on the same activity is rejected unless the existing flag is resolved or dismissed.
auto_flag_on_duplicate_detection
When DuplicateDetectionService identifies a potential duplicate activity, it automatically creates a flag with flag_type=duplicate and auto_detected=true. No human action required.
resolution_requires_note
Setting status to resolved or dismissed requires a non-empty resolution_note and a resolved_by_user_id.
org_scoped_access
Flags are only visible and actionable by users within the same organization_id. Global Admins require explicit support access grant to the org before accessing its flags.
flagged_activity_blocked_from_approval
An activity with at least one open flag cannot be approved in ActivityApprovalService until all flags are resolved or dismissed.
audit_log_on_resolution
Every status transition (open → under_review, under_review → resolved/dismissed) must produce an entry in audit_logs.