Skip to main content

compliance app

National HQ defines compliance requirements; chapters submit evidence; org admins (and optionally regional admins) review.

Models (9)​

  • NationalRequirement — what HQ asks for; categories (operational / financial / risk / membership / academic / other), priority levels, frequency (one-time / monthly / quarterly / semester / annual)
  • ComplianceTemplate — submission shape (file upload / form fields / checklist)
  • CompliancePeriod — a generated cycle (e.g., "Spring 2026 hazing prevention")
  • ChapterComplianceStatus — per-chapter, per-period status (open / in-review / approved / overdue)
  • ComplianceSubmission — what a chapter submits; evidence (file URLs, form values, attestations)
  • SubmissionAttachment — uploaded files for a submission
  • ComplianceAlert — generated when a chapter is at risk (overdue or incomplete)
  • UserFilterPreset — saved filter view in the compliance dashboard
  • ChapterRequirementOverride — chapter-specific exemption / variance

Key endpoints​

URLPurpose
GET /api/organizations/<id>/compliance/requirements/List requirements
POST /api/organizations/<id>/compliance/requirements/Create a requirement
GET /api/compliance/periods/<id>/Period detail
GET /api/chapters/<id>/compliance/status/Chapter status across all open periods
POST /api/compliance/submissions/Submit evidence
POST /api/compliance/submissions/<id>/approve/Approve (org admin)
POST /api/compliance/submissions/<id>/decline/Decline with feedback
GET /api/compliance/alerts/Active alerts
GET /api/compliance/dashboard/kpis/On-time rate, overdue counts, etc.

Permissions​

  • IsNationalAdmin — requirement CRUD, review submissions
  • IsNationalOrRegionalAdmin — view org-wide compliance, regional drill-down
  • IsChapterOfficer — submit on behalf of chapter

Background tasks​

  • calculate_compliance_scores — periodic; computes chapter health from on-time rate
  • generate_compliance_alerts — daily; raises alerts for chapters at risk
  • auto_escalate_overdue — daily; routes severely overdue items to regional / org admin

Signals​

  • post_save on ChapterComplianceStatus — triggers ComplianceAlert creation if status changes to overdue
  • post_save on ComplianceSubmission — marks ChapterComplianceStatus as in_review

Notable patterns​

Three submission types​

Defined on ComplianceTemplate.submission_type:

  • file_upload — drag-and-drop a PDF or doc; stored in S3 via SubmissionAttachment
  • form_fields — JSON-defined form (number, text, dropdown, date); validated against shape
  • checklist — list of items the chapter ticks off

Multi-tier review​

Some requirements need both regional approval first, then org-level approval. NationalRequirement.requires_regional_review boolean. The review queue moves through tiers in order.

Per-chapter overrides​

ChapterRequirementOverride lets HQ exempt a specific chapter (e.g., a chapter on probation may have different obligations) — exempt entirely, defer due date, or change template.

Alerts vs notifications​

ComplianceAlert is a domain object with state (active / acknowledged / resolved). When created, it also fires a Notification to relevant officers + admins. Acknowledging an alert doesn't dismiss the underlying issue — it just silences the alert.

KPI dashboard​

GET /api/compliance/dashboard/kpis/ aggregates:

  • On-time rate (last 90 days)
  • Overdue count by chapter
  • Top late offenders
  • Trends over time

Computed in real-time (no materialized cache). For very large orgs, this may need optimization.

Code paths​

  • Models: backend/apps/compliance/models.py
  • Views: backend/apps/compliance/views.py
  • Signals: backend/apps/compliance/signals.py
  • Tasks: backend/apps/compliance/tasks.py
  • Alert engine: backend/apps/compliance/services/alerts.py