# centre-for-open-societal-systems/oan_grievance_service architecture

> Architecture diagram of the GitHub repository centre-for-open-societal-systems/oan_grievance_service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/centre-for-open-societal-systems/oan_grievance_service
- Repository: https://github.com/centre-for-open-societal-systems/oan_grievance_service

## Overview

OAN Grievance Service is a Frappe backend for grievance intake and redressal. Users and staff reach versioned REST endpoints to save drafts or submit cases; the backend validates and persists grievances, applies access controls, routes cases to officers, tracks workflow and SLA deadlines, and sends notifications. Supporting capabilities include attachments and scanning, change requests, audit/timeline history, dashboards, and configurable master data. The graph uses the README and source-index references for relationships; unsampled implementation details are not assumed.

Main entry points: [`oan_grievance_service/api/v1/grievance.py`](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/api/v1/grievance.py) (Grievance API), [`oan_grievance_service/services/routing.py`](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/routing.py) (Assignment routing), [`oan_grievance_service/services/sla.py`](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/sla.py) (SLA and escalation), [`oan_grievance_service/tasks.py`](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/tasks.py) (Scheduled jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and intake"]
  node_router["API router<br/>[router.py]"]
  node_grievance_api["Grievance API<br/>[grievance.py]"]
  node_draft_api["Draft API<br/>[draft.py]"]
  node_attachment_api["Attachment API<br/>[attachment.py]"]
end

subgraph group_casework["Casework services"]
  node_grievance_doc["Grievance record<br/>[grievance.py]"]
  node_routing["Assignment routing<br/>[routing.py]"]
  node_lifecycle["Case lifecycle<br/>[lifecycle.py]"]
  node_sla["SLA and escalation<br/>[sla.py]"]
  node_ticket["Ticket numbering<br/>[ticket_number.py]"]
  node_timeline["Case timeline"]
  node_change_requests["Change requests"]
end

subgraph group_governance["Access and configuration"]
  node_access["Permission rules<br/>[permissions.py]"]
  node_rbac["Officer assignments"]
  node_areas["Administrative areas"]
  node_masters["Service configuration"]
end

subgraph group_operations["Operations and reporting"]
  node_notifications["Notifications<br/>[notifications.py]"]
  node_scanning["Attachment scanning<br/>[scanning.py]"]
  node_tasks["Scheduled jobs<br/>[tasks.py]"]
  node_dashboards["Dashboards and statistics<br/>[dashboard.py]"]
end

node_users(("Submitters and staff"))
node_database[("Frappe database")]
node_clamav["ClamAV service"]
node_sms["SMS gateway"]

node_users -->|"submit requests"| node_router
node_router -->|"routes to"| node_grievance_api
node_router -->|"routes to"| node_draft_api
node_router -->|"routes to"| node_attachment_api
node_grievance_api -->|"creates and reads"| node_grievance_doc
node_grievance_api -->|"invokes"| node_routing
node_grievance_api -->|"invokes"| node_lifecycle
node_grievance_api -->|"invokes"| node_sla
node_grievance_api -->|"generates ticket"| node_ticket
node_grievance_api -->|"reads timeline"| node_timeline
node_grievance_api -->|"checks access"| node_access
node_draft_api -->|"saves draft"| node_grievance_doc
node_draft_api -->|"generates ticket"| node_ticket
node_attachment_api -.->|"uses scanner"| node_scanning
node_routing -->|"queries assignments"| node_rbac
node_routing -->|"matches area scope"| node_areas
node_routing -->|"invokes"| node_sla
node_routing -->|"invokes"| node_lifecycle
node_routing -->|"queues notices"| node_notifications
node_sla -->|"sends reminders"| node_notifications
node_sla -->|"records events"| node_timeline
node_sla -->|"finds escalation officers"| node_rbac
node_change_requests -->|"checks permissions"| node_access
node_change_requests -->|"checks assignments"| node_rbac
node_tasks -->|"runs jobs"| node_sla
node_tasks -->|"dispatches notices"| node_notifications
node_tasks -->|"runs scans"| node_scanning
node_tasks -->|"invokes routing"| node_routing
node_notifications -.->|"sends SMS"| node_sms
node_scanning -.->|"scans uploads"| node_clamav
node_grievance_doc -.->|"persists records"| node_database
node_rbac -.->|"stores assignments"| node_database
node_masters -.->|"stores configuration"| node_database
node_users -.->|"views summaries"| node_dashboards

click node_router "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/api/router.py"
click node_grievance_api "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/api/v1/grievance.py"
click node_draft_api "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/api/v1/draft.py"
click node_attachment_api "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/api/v1/attachment.py"
click node_grievance_doc "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_management/doctype/grievance/grievance.py"
click node_routing "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/routing.py"
click node_lifecycle "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/lifecycle.py"
click node_sla "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/sla.py"
click node_ticket "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/ticket_number.py"
click node_timeline "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_management/doctype/grievance_timeline/grievance_timeline.py"
click node_change_requests "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_requests/doctype/grievance_change_request/grievance_change_request.py"
click node_access "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/permissions.py"
click node_rbac "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_access_control/doctype/grievance_rbac_assignment/grievance_rbac_assignment.py"
click node_areas "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_masters/doctype/grievance_administrative_area/grievance_administrative_area.py"
click node_masters "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_masters/doctype/grievance_service_category/grievance_service_category.py"
click node_notifications "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/notifications.py"
click node_scanning "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/scanning.py"
click node_tasks "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/tasks.py"
click node_dashboards "https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/dashboard.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_router,node_grievance_api,node_draft_api,node_attachment_api toneBlue
class node_grievance_doc,node_routing,node_lifecycle,node_sla,node_ticket,node_timeline,node_change_requests,node_database toneAmber
class node_access,node_rbac,node_areas,node_masters toneMint
class node_notifications,node_scanning,node_tasks,node_dashboards toneRose
class node_users,node_clamav,node_sms toneIndigo
```

## Components

### API and intake

- [API router](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/api/router.py): `oan_grievance_service/api/router.py`
- [Grievance API](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/api/v1/grievance.py): `oan_grievance_service/api/v1/grievance.py`
- [Draft API](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/api/v1/draft.py): `oan_grievance_service/api/v1/draft.py`
- [Attachment API](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/api/v1/attachment.py): `oan_grievance_service/api/v1/attachment.py`

### Casework services

- [Grievance record](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_management/doctype/grievance/grievance.py): `oan_grievance_service/grievance_management/doctype/grievance/grievance.py`
- [Assignment routing](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/routing.py): `oan_grievance_service/services/routing.py`
- [Case lifecycle](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/lifecycle.py): `oan_grievance_service/services/lifecycle.py`
- [SLA and escalation](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/sla.py): `oan_grievance_service/services/sla.py`
- [Ticket numbering](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/ticket_number.py): `oan_grievance_service/services/ticket_number.py`
- [Case timeline](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_management/doctype/grievance_timeline/grievance_timeline.py): `oan_grievance_service/grievance_management/doctype/grievance_timeline/grievance_timeline.py`
- [Change requests](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_requests/doctype/grievance_change_request/grievance_change_request.py): `oan_grievance_service/grievance_requests/doctype/grievance_change_request/grievance_change_request.py`

### Access and configuration

- [Permission rules](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/permissions.py): `oan_grievance_service/permissions.py`
- [Officer assignments](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_access_control/doctype/grievance_rbac_assignment/grievance_rbac_assignment.py): `oan_grievance_service/grievance_access_control/doctype/grievance_rbac_assignment/grievance_rbac_assignment.py`
- [Administrative areas](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_masters/doctype/grievance_administrative_area/grievance_administrative_area.py): `oan_grievance_service/grievance_masters/doctype/grievance_administrative_area/grievance_administrative_area.py`
- [Service configuration](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/grievance_masters/doctype/grievance_service_category/grievance_service_category.py): `oan_grievance_service/grievance_masters/doctype/grievance_service_category/grievance_service_category.py`

### Operations and reporting

- [Notifications](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/notifications.py): `oan_grievance_service/services/notifications.py`
- [Attachment scanning](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/scanning.py): `oan_grievance_service/services/scanning.py`
- [Scheduled jobs](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/tasks.py): `oan_grievance_service/tasks.py`
- [Dashboards and statistics](https://github.com/centre-for-open-societal-systems/oan_grievance_service/blob/develop/oan_grievance_service/services/dashboard.py): `oan_grievance_service/services/dashboard.py`

### Other components

- **Submitters and staff**
- **Frappe database**
- **ClamAV service**
- **SMS gateway**

## Connections

- Submitters and staff → API router: submit requests (evidence: `README.md`)
- API router → Grievance API: routes to (evidence: `oan_grievance_service/api/router.py`)
- API router → Draft API: routes to (evidence: `oan_grievance_service/api/router.py`)
- API router → Attachment API: routes to (evidence: `oan_grievance_service/api/router.py`)
- Grievance API → Grievance record: creates and reads (evidence: `oan_grievance_service/api/v1/grievance.py`)
- Grievance API → Assignment routing: invokes (evidence: `oan_grievance_service/api/v1/grievance.py`)
- Grievance API → Case lifecycle: invokes (evidence: `oan_grievance_service/api/v1/grievance.py`)
- Grievance API → SLA and escalation: invokes (evidence: `oan_grievance_service/api/v1/grievance.py`)
- Grievance API → Ticket numbering: generates ticket (evidence: `oan_grievance_service/api/v1/grievance.py`)
- Grievance API → Case timeline: reads timeline (evidence: `oan_grievance_service/api/v1/grievance.py`)
- Grievance API → Permission rules: checks access (evidence: `oan_grievance_service/api/v1/grievance.py`)
- Draft API → Grievance record: saves draft (evidence: `oan_grievance_service/api/v1/draft.py`)
- Draft API → Ticket numbering: generates ticket (evidence: `oan_grievance_service/api/v1/draft.py`)
- Attachment API → Attachment scanning: uses scanner (evidence: `README.md`)
- Assignment routing → Officer assignments: queries assignments (evidence: `oan_grievance_service/services/routing.py`)
- Assignment routing → Administrative areas: matches area scope (evidence: `oan_grievance_service/services/routing.py`)
- Assignment routing → SLA and escalation: invokes (evidence: `oan_grievance_service/services/routing.py`)
- Assignment routing → Case lifecycle: invokes (evidence: `oan_grievance_service/services/routing.py`)
- Assignment routing → Notifications: queues notices (evidence: `oan_grievance_service/services/routing.py`)
- SLA and escalation → Notifications: sends reminders (evidence: `oan_grievance_service/services/sla.py`)
- SLA and escalation → Case timeline: records events (evidence: `oan_grievance_service/services/sla.py`)
- SLA and escalation → Officer assignments: finds escalation officers (evidence: `oan_grievance_service/services/sla.py`)
- Change requests → Permission rules: checks permissions (evidence: `oan_grievance_service/grievance_requests/doctype/grievance_change_request/grievance_change_request.py`)
- Change requests → Officer assignments: checks assignments (evidence: `oan_grievance_service/grievance_requests/doctype/grievance_change_request/grievance_change_request.py`)
- Scheduled jobs → SLA and escalation: runs jobs (evidence: `oan_grievance_service/tasks.py`)
- Scheduled jobs → Notifications: dispatches notices (evidence: `oan_grievance_service/tasks.py`)
- Scheduled jobs → Attachment scanning: runs scans (evidence: `oan_grievance_service/tasks.py`)
- Scheduled jobs → Assignment routing: invokes routing (evidence: `oan_grievance_service/tasks.py`)
- Notifications → SMS gateway: sends SMS (evidence: `README.md`)
- Attachment scanning → ClamAV service: scans uploads (evidence: `README.md`)
- Grievance record → Frappe database: persists records (evidence: `README.md`)
- Officer assignments → Frappe database: stores assignments (evidence: `README.md`)
- Service configuration → Frappe database: stores configuration (evidence: `README.md`)
- Submitters and staff → Dashboards and statistics: views summaries (evidence: `README.md`)
