Design Services

Overview

This page provides a structured approach for defining, configuring, and implementing registries and services in DIGIT. It covers MDMS configuration, access control, API design, internal implementation, reusable DIGIT services and registries, and end-to-end sequence diagrams.

The goal is to ensure that all services follow a consistent architecture and integrate seamlessly with DIGIT’s platform components such as Persister, Indexer, Workflow Service, User Service, and more.

Steps

Identify Registries & Services

To figure out what services you need to build, start with a simple exercise:

1. List all user activities

Write each activity in a table. Then separate the verb (action) and the noun (object).

Example: In “Verify Birth Certificate Application,” the word Application is unnecessary — the real activity is Verify Birth Certificate.

DIGIT already has many standard services, so use their terminology where possible. For example, say “Pay Charges” instead of “Make Payment.”

Activity	Generalized Activity	Verb	Noun
Apply for Birth Certificate	Create Birth Certificate	Create	Birth Certificate
Make Payment	Make Payment	Make	Payment
Verify Application	Verify Birth Certificate	Verify	Birth Certificate
Approve Application	Approve Birth Certificate	Approve	Birth Certificate
Send Notification	Send Notification	Send	Notification
Update Application	Update Birth Certificate	Update	Birth Certificate
Download Certificate	Download Birth Certificate	Download	Birth Certificate

2. Convert the verbs and nouns into services

Once your verbs and nouns table is ready, transform it into another table:

• Noun → becomes a Service

• Verb → becomes an Operation (API endpoint) inside that Service

Example:

Service	Operation
Birth Certificate	Create
	Update
	Verify
	Approve
	Download
Notification	Send

From this, you now have two services:

1. Birth Certificate Service

2. Notification Service

3. More services appear during design

When you start drawing sequence diagrams, you may discover additional services.

Example: Charge calculation varies by city, so it should not live inside the Birth Certificate Service. This leads to a separate service: Birth Certificate Charge Calculator Service.

Extract Workflows

In DIGIT, workflows are created using the Workflow Service. A workflow is simply a set of states and actions that move an application or request from start to finish.

1. Start with your swimlane diagrams

Look at the swimlane diagram for your process and extract:

• States (e.g., APPLIED, VERIFIED, APPROVED)

• Actions (e.g., VERIFY, APPROVE, REJECT)

• Actors / Roles (e.g., Employee, Approver, Citizen)

These become the building blocks of your workflow.

What is a workflow?

A workflow is a simple state machine:

• A process starts in one state

• Different actors perform actions

• Those actions move the process to the next state

Workflows help you track and control processes such as:

• Approving an application

• Onboarding an employee

• Granting a certificate or service

Any DIGIT module that needs step-by-step progression can use this.

The table below illustrates the process:

What is the state of the application?	Which role can act?	What actions can the role take?
Null	Applicant	Apply
Awaiting Verification	Verifier	Mark Verified Ask for Clarification
Awaiting Clarification	Applicant	Save/Update
Verified	Verifier	Assign Approver
Awaiting Approval	Approver	Approve Reject
Approved	-	-
Rejected	-	-

The above table needs to be translated into Workflow and MDMS service configurations.

At a high level, a workflow consists of:

1. States

2. Actions that can be taken in each state

3. Roles that can perform these actions.

Below is a sample workflow JSON template that can be customised.

3KB

sample-workflow-json.jsonc

Open

Sample workflow JSON

The states in the first column of the table are added to the states array in the workflow JSON. Each state has to be enumerated with the right attributes.

The actions in the third column of the table go into an actions JSON array inside each state object. These are the actions that can be taken on any given state to move it to another state. Each action object in the array has the following attributes:

• "action" - name of the action

• "nextState" - the state this action leads to

• "roles" - The roles that can take action on the state. These roles should be a subset of the roles in the second column of the table and need to map to the roles.json config in MDMS.

After preparing the workflow JSON, upload it to the Workflow Service using a REST API. A template JSON is usually provided and can be customised by plugging in your states, actions, and roles. Refer to this page to find out how this is done.

Identify Reference Data

DIGIT includes an MDMS that stores reference data for each module.

What goes into MDMS?

Store data that rarely changes, such as:

• Administrative boundaries

• Revenue hierarchies

• Property types

• Trade license types

If the data changes often and needs CRUD APIs, it should go into a registry/database, not MDMS.

How MDMS data is organised

• Reference data is stored in the forked MDMS repository.

• Inside the /data folder, each tenant (state or city) has its own folder.

• Each module should keep its master data in its own subfolder for easy management.

State-level vs City-level data

• State-level master data is configured in master-config.json inside the tenant folder.

• Use "isStateLevel": true if cities should not override this data.

• Cities (sub-tenants) can define their own module data inside their folders.

Note that MDMS does not follow any inheritance rules between tenants and sub-tenants. That is, a sub-tenant defining data within their folders will NOT implicitly inherit master tenant data.

Naming Rules

• Folder and file names can be anything.

• But module names and master names inside the JSON must match what is defined in:

  • master-config.json

  • Your module code

If these names don't match, MDMS will not return the data.

Example: https://github.com/egovernments/egov-mdms-data/blob/UAT/master-config.json

Tenancy configuration

In the tenant folder:

• tenants.json lists all tenants (states + cities)

• Used by the frontend login screen to show the dropdown

• Backend services do not require it to run

• This folder also stores:

  • Logos

  • Shape files

  • Latitude / Longitude

  • Other tenant metadata like logos, shape files, lat long coordinates and other tenant information

Sample tenant information can be referred to here.

Extract Roles & Access Control MDMS Configuration

A part of the MDMS configuration for access control can be extracted from the table above. All new services need to provide access control for the URIs they expose via role action mappings. A module needs to define roles, actions (URIs) and role-action mapping.

Note that this is only a part of the MDMS configuration. Any other configuration that the module requires has to be set up in MDMS separately.

Configure Roles

Create a file called roles.json. All the unique roles in the second column of the table need to go into the JSON in the following format. This needs to be copied to the MDMS repository under the following path:

/{{mdms-repo}}/data/{{tenantId}}/ACCESSCONTROL-ROLES

For this sample application, we will have two roles: EMPLOYEE and CITIZEN.

// Roles JSON 
{[
{
      "code": "{{Role1}}", //Example: Employee
      "name": "{{Role1 Display Name}}",//Example: ULB Employee
      "description": "Default role for all employees"
},
{
      "code": "{{Role2}}",
      "name": "{{Role2 Display Name}}",
      "description": "End user citizen"
},
]
}

Configure Actions

Add the URIs from the API spec in a file called actions-test.json under the following path:

/{{mdms-repo}}/data/{{tenantId}}/ACCESSCONTROL-ACTIONS-TEST/

All URIs for the module need to be included here. The ACTION_ID needs to be unique and manually generated. Pick a unique ID series for your module.

{
      "id": {{ACTION_ID}}, //Needs to be a hand generated unique ID
      "name": "Create birth certificate",
      "url": "/birth-services/v1/_create",
      "parentModule": "",
      "displayName": "Create Birth certificate application",
      "orderNumber": 0,
      "enabled": false,
      "serviceCode": "birth-services",
      "code": "null",
      "path": ""
}

Configure Role-action Mapping

Add the role action mapping in a file called roleactions.json under the following path:

/{{mdms-repo}}/data/{{tenantId}}/ACCESSCONTROL-ROLEACTIONS/

{
      "rolecode": "EMPLOYEE",
      "actionid": {{ACTION_ID}},
      "actioncode": "",
      "tenantId": "{{tenantId}}"
    }

Detailed Design For Registries & Services

Designing a service in DIGIT has two main parts:

1. External Service Interface

This is your API layer.

• Defined using OpenAPI/Swagger.

• Start with a sample (like the Swagger Pet Store) and update it for your module.

• Identify all fields of your object (e.g., Birth Certificate fields) from user stories.

• The YAML you create can generate:

  • Controller code

  • Service client

  • API documentation

2. Internal Implementation

This is your service logic and storage.

It involves:

• Creating the class diagram

• Designing the database tables where your main object (e.g., Birth Certificate) will be stored

Identify DIGIT Reusable Registries & Services

Use the questions below to see which platform services your module needs:

• Do users log in? → Use User Service

• Do certain users need special permissions? → Use Role Service

• Do you need reference data (e.g., gender list)? → Use MDMS

• Do you need multi-language support? → Use Localisation Service

• Need to save data? → Use Kafka + Persister Service

• Need search or dashboards? → Use Indexer + ElasticSearch + Decision Support System (DSS)

• Need tamper-proof audit logs? → Use Signed Audit Service

• Need to upload documents? → Use File Store Service

• Need workflow steps? → Use Workflow Service

• Need SMS/Email/App notifications? → Use Notification Service

• Need to track user behaviour? → Use Telemetry Service (UI must send events)

Develop Sequence Diagrams

Once you know which services you need, draw sequence diagrams to show:

• How your module talks to DIGIT services

• How data flows end-to-end for each use case

This will help clarify the full process from request to response. A sequence diagram is illustrated below.

Typical Sequence Diagram for DIGIT