> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/complaints-management/design/architecture/data-ontology.md).

# Data Ontology

DIGIT Complaint Management System Domain Ontology

{% hint style="info" %}
**About this page**

This page defines the concepts (entities), the relationships between them, and the mechanics that govern their behaviour, across the Complaint Management System (hereby referred to as ‘CMS’) and the Configurator that helps administer it. 

***Note:** Diagrams are illustrative simplifications, not exhaustive schemas.*
{% endhint %}

## Overview

At the heart of it, a single complaint follows the below-mentioned linear journey

Citizen → Grievance Routing Officer → Resolver <->Resolver Supervisor → Planner

<div align="left"><img src="https://2437503360-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxNs29HvQfLFAPZCcDd7D%2Fuploads%2F1SlZd188esdf8hbTRJFn%2Funknown.png?alt=media&amp;token=fdf423ae-bcd4-417b-a81b-555d44eef9c1" alt="" height="291" width="576"></div>

* Citizen - Files a complaint for a grievance they are facing. Their entire interaction with CMS is submitting it and, later, checking its status, rating resolved complaints or reopening it.
* GRO  (Grievance Routing Officer) - assesses the complaint and assigns it to the right Resolver- the “Complaint Assessor” role. Their role may or may not be assigned a “Department” in the system.&#x20;
* Resolver Supervisor — oversees the Resolvers under them and steps in when something goes wrong. This maps to the SUPERVISOR role. When a complaint breaches its State-level SLA , it gets auto-escalated along the Resolver's reporting line.
* Resolver - The last-mile employee (LME) who resolves the complaints — the “Complaint Resolver” role (Access Role code PGR\_LME).&#x20;
* Planner - Someone overseeing multiple jurisdictions — a government official or department head — Curious about the accumulated pattern of complaints and Resolver activity to make governance and policy decisions.
* Admin - In the context of the Complaint Management System, an Admin is the user who configures the flow and actions of a complaint from citizen to resolver.

## 1. Core Domain Map

The entities below are grouped into five domains. Most of CMS's real complexity lives in how these domains reference each other.

{% hint style="info" %}
**Note:** Jump to section 2.6 to see how all the below entities interact with each other.
{% endhint %}

### 1.1 Account Entities

<table><thead><tr><th width="131.86328125">Entity</th><th>Definition</th></tr></thead><tbody><tr><td>Tenant</td><td>An independent account - a root (state/country) or a city/sub-tenant under it.</td></tr><tr><td>Department</td><td>A functional unit within a tenant (e.g. Public Works, Sanitation).</td></tr><tr><td>Designation</td><td>A job title within a tenant for an employee (e.g. Field Officer).</td></tr><tr><td>User</td><td>The base identity/login account - May be citizens, employees, or system accounts.</td></tr><tr><td>Employee</td><td><p>A user at the end of consuming and resolving a complaint. </p><p>Note: An “Employee” entity may also be a “Citizen” entity</p></td></tr><tr><td>Assignment</td><td>One employee's tenure in a department + designation, with a reporting line.</td></tr></tbody></table>

### 1.2 Geographic Entities

<table><thead><tr><th width="180.4140625">Entity</th><th>Definition</th></tr></thead><tbody><tr><td>Boundary Hierarchy</td><td>A named, ordered set of geographic levels for an account/ tenant (e.g. City → Ward → Locality).</td></tr><tr><td>Boundary</td><td><p>One specific geographic area at one level of a hierarchy.</p><p><br>Example: The country Kenya constitutes a boundary, and so does the city of Bomet within Kenya.<br><br>The relationship between Kenya and Bomet is defined in the Boundary Hierarchy.</p></td></tr><tr><td>Jurisdiction</td><td>A Boundary an employee is scoped to work within.<br><br>Example: Ward Chesoen in Bomet will be the defined jurisdiction for a particular employee.</td></tr></tbody></table>

### 1.3 Complaint & Workflow Entities

<table><thead><tr><th width="166.8046875">Entity</th><th>Definition</th></tr></thead><tbody><tr><td>Complaint Hierarchy</td><td>A named set of levels a tenant defines for organizing complaint categories.<br><br>This determines the shape of the classification system for complaints.<br><br>The default set hierarchy for is Category → Sub-Type </td></tr><tr><td>Complaint Type</td><td>A leaf node of the Complaint Hierarchy — what a citizen actually selects when filing.<br><br>Eg: For a Complaint Type “Streetlights”, a citizen may choose the Complaint Sub-Type as “Streetlight not working” or “Installation of new streetlight”</td></tr><tr><td>Complaint (Service Request)</td><td>A citizen's filed grievance</td></tr><tr><td>Business Service (Workflow)</td><td>The overall rulebook for how one type of request gets handled, start to finish. Consider it as a named flowchart. "PGR" is the flowchart for complaints specifically by default.<br><br>Formally, it is the state-machine definition governing a complaint type's lifecycle. </td></tr><tr><td>State</td><td>One step in a Business Service's lifecycle.<br><br>It is a specific stopping point on the business service flowchart- where a complaint currently is right now (e.g. "waiting to be assigned," "waiting to be fixed," "resolved").</td></tr><tr><td>Action</td><td>A transition available from a state and who may trigger it.<br><br>"Assign" moves a complaint from Pending for Assignment to Pending at Resolver. "Resolve" moves it from Pending at Resolver to Resolved.</td></tr><tr><td>Workflow Process</td><td>A historical record of one actual transition between states due to an action on one actual complaint.</td></tr></tbody></table>

### 1.4 Permissions Entities

<table><thead><tr><th width="162.5078125">Entity</th><th>Definition</th></tr></thead><tbody><tr><td>Access Role</td><td>A named label for a role (e.g. GRO, PGR_LME).</td></tr><tr><td>Role Action</td><td>The actual permission that connects an Access Role to one specific thing that role is allowed to do.<br><br>The Role alone doesn't unlock anything- the Role Action is what assigns value to the Role itself.</td></tr></tbody></table>

### 1.5 Analytics Entities

<table><thead><tr><th width="159.69921875">Entity</th><th>Definition</th></tr></thead><tbody><tr><td>Dashboard</td><td><p>A single screen that gathers multiple KPI tiles together so someone can assess aggregated complaint activity at a high level. </p><p><br>Authenticated dashboards are present for Employees and Admins.</p></td></tr><tr><td>Public Dashboard</td><td>Citizen-facing dashboard that displays aggregate complaint KPI’s without requiring a login.</td></tr></tbody></table>

### 1.6 Relationship Between Entities

* **Account entities** — A Tenant/Account has many Departments, Designations, and Employees. Adding a new City under an existing Root is dynamic; adding a new Root requires a service restart, because state-level services read a single root-tenant setting once at startup.
* **Geographic** — An Employee's Jurisdiction is a reference to one Boundary — it's what scopes which complaints they may see or act on. A Complaint is tagged to a Boundary at filing time; this is the mechanical basis of boundary-based routing.
* **Complaint lifecycle** — A Complaint Type's department field points at the same Department master that an Employee's Assignment uses. This is the actual routing link: a complaint can only be validly assigned to an employee in the matching department — an enforced server-side check, not just convention.
* **Permissions** — An Access Role only becomes meaningful once paired with Access Actions via a Role Action grant — the Role alone is just a label. Business Service Actions, however, reference Access Role codes directly, bypassing Role Action entirely.
* **Analytics** — Every Workflow Process transition eventually feeds the analytics layer, which is what a KPI Definition queries.&#x20;

## 2. Complaint Lifecycle

<div align="left"><img src="https://2437503360-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxNs29HvQfLFAPZCcDd7D%2Fuploads%2FzjVkAixdhSQq4MBfcBjb%2Funknown.png?alt=media&amp;token=b4540bc7-d3be-44ee-8741-044b4bb5591a" alt="" height="383" width="576"></div>

### 2.1 SLA (Service Level Agreement)

A defined time commitment for how long a task is allowed to take before it's considered overdue. In CMS, an SLA sets the expected resolution window for a complaint; once that window passes without resolution, the complaint is flagged as breached.

<table><thead><tr><th width="155.36328125">SLA type</th><th width="295.3203125">What it governs</th><th>Resolution order</th></tr></thead><tbody><tr><td>Business Service SLA</td><td>A single default deadline for the whole workflow (e.g. 5 days for any complaint).</td><td>Fallback — used only when no Complaint-Type SLA is set</td></tr><tr><td>Complaint-Type SLA</td><td>A more specific deadline set per complaint category</td><td>Takes priority over the Business Service default when present.</td></tr><tr><td>State-level SLA</td><td><p>How long a complaint may sit in one specific step before escalating.</p><p><br>Example: If a complaint sits with a resolver for &#x3C;x> days without a change in state, then the State-level SLA will kick-in to escalate this to their supervisor.</p></td><td>Independent — does not participate in the above fallback; answers a different question.</td></tr></tbody></table>

### 2.2 Escalation

When a complaint sits too long in a state (per its State-level SLA), it can automatically move to a Supervisor rather than staying with the original assignee.&#x20;

This is driven by two things together: the State-level SLA timer, and the employee's organisational reporting line (an escalated complaint goes to that specific employee's supervisor, not merely to anyone holding a Supervisor role).

### 2.3 Reject, Reopen, Rate, Resolve&#x20;

The lifecycle of a complaint has multiple end points. Resolved or Rejected marks an end state for a complaint, whereas Reopen and Rate denote an action to be taken on a complaint that has reached the said end state.

<table><thead><tr><th width="93.359375">Action</th><th width="163.5625">Who does it</th><th width="212.44921875">Available when the complaint is</th><th>Result</th></tr></thead><tbody><tr><td>Resolve</td><td>The assigned field employee (LME)</td><td>Assigned and being worked on</td><td>Status becomes Resolved. Work is done, the complaint is not closed.</td></tr><tr><td>Reject</td><td>The Grievance Redressal Officer (GRO)</td><td>Awaiting assignment or reassignment</td><td>Status becomes Rejected. The complaint will not be actioned.</td></tr><tr><td>Reopen</td><td>The citizen, or staff at an assisted channel on their behalf</td><td>Resolved or Rejected, within the Reopen Window</td><td>Complaint returns to the assignment queue and starts again.</td></tr><tr><td>Rate</td><td>The citizen, or an assisted channel on their behalf</td><td>Resolved or Rejected. </td><td>The complaint is permanently closed.</td></tr></tbody></table>

## 4. Identity & Organisational Model

<div align="left"><img src="https://2437503360-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxNs29HvQfLFAPZCcDd7D%2Fuploads%2Fy4zeCONfoKvFcNCgW5Mn%2Funknown.png?alt=media&amp;token=fae32992-a047-455d-9350-5d407c2f90f7" alt="" height="348" width="576"></div>

A User is the underlying login account — every person who can sign in, citizen or staff, is a User. An Employee is not a separate account: it is HR context wrapped around a User of type EMPLOYEE. Department, Designation, Jurisdiction, and the reporting line all live on the Employee record; the User record underneath only holds the login and the Access Roles.

A Resolver's ability to log in comes from their User record, but their ability to see only complaints in their area (jurisdiction-based access), or to be recognised as someone's manager, comes from their Employee record.

## 5. Roles Roster

### 5.1 Administrative Roles&#x20;

<table><thead><tr><th width="203.55859375">Role</th><th>Scope</th></tr></thead><tbody><tr><td>Platform administrator</td><td>The user intended to onboard a brand-new tenant/account onto the CMS platform for the first time. </td></tr><tr><td>Account administrator</td><td>The user intended to run a specific account (a city or a state) through the configurator.</td></tr></tbody></table>

### 5.2 Operational Roles&#x20;

<table><thead><tr><th width="168.15625">Role</th><th>Function</th></tr></thead><tbody><tr><td>CITIZEN</td><td>File complaints; the public-facing account type.</td></tr><tr><td>CSR</td><td>File a complaint on a citizen's behalf (counter/customer service).</td></tr><tr><td>GRO</td><td>Assesses and assigns incoming complaints (“Complaint Assessor").</td></tr><tr><td>DGRO</td><td>A department-scoped variant of GRO.</td></tr><tr><td>PGR_LME</td><td>Resolves the complaint on the ground (“Complaint Resolver”).</td></tr><tr><td>SUPERVISOR</td><td>The target of automatic escalation, tied to the reporting line.</td></tr><tr><td>AUTO_ESCALATE</td><td>A system-only role representing automated transitions (This is not a person)</td></tr><tr><td>EMPLOYEE</td><td>The baseline role that every staff account holds.</td></tr></tbody></table>

## 6. Notifications: Configuration & Delivery

<table><thead><tr><th width="182.33984375">Concept</th><th>Answers</th></tr></thead><tbody><tr><td>Notification Routing</td><td>When should a notification fire, and who should receive it? (e.g. “on Resolve, notify the Citizen”)</td></tr><tr><td>Notification Template</td><td>What does the message actually say?</td></tr><tr><td>Notification Provider</td><td>How does it get physically delivered? (e.g. Twilio for SMS, WhatsApp Business, via Novu as the orchestration layer)</td></tr></tbody></table>

## 7. Analytics & Dashboard Data Model

CMS analytics are built from three purpose-built data layers (“grains”), each answering a different kind of question. Nearly every KPI is a filter or aggregation on top of one of these three, not custom logic per metric.

<table><thead><tr><th width="155.765625">Grain</th><th width="321.43359375">Answers</th><th>Dimensions</th></tr></thead><tbody><tr><td>Grain</td><td>Answers</td><td>Dimensions</td></tr><tr><td>complaint_events</td><td>What happened, and in what order? </td><td>One row per transition</td></tr><tr><td>complaint_facts</td><td>What's true right now? (the current snapshot)</td><td>One row per complaint</td></tr><tr><td>complaint_open_state_daily</td><td>How has this trended over time? </td><td>One row per open complaint per day</td></tr></tbody></table>

A KPI Definition is a specific question asked of one of these grains. A Dashboard Pack is a curated set of those questions, laid out together for a user to scan at a glance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.digit.org/complaints-management/design/architecture/data-ontology.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.