> 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/health/design/architecture/low-level-design/services/health-services/worker-registry.md).
# Worker Registry
### Overview
The **Worker Registry Service** is a new system that keeps track of **campaign workers** — the field staff who go out and do the hands-on work during a health campaign (for example, distributing supplies or administering commodities).
Think of it as the "HR + Payroll card file" for campaign workers. It stores:
* **Who the worker is**, linked back to their main personal record (called an "individual" record elsewhere in the system)
* **How to pay them** — bank details, payment provider, payee name and phone number
* **Proof of their work** — a signature and photo that get captured automatically the first time they log attendance
This is a **brand-new service** introduced in this release. Nothing here is an update to something older — it's all new.
***
### What's new in this?
During a health campaign, people are recruited to work in the field. The system already has a general record for every person ("individual"). But workers need extra information that doesn't belong on that general record — mainly:
* Payment information (so they can actually get paid)
* Campaign-specific proof of work (signature, photo)
This service exists to hold that extra worker-specific information, and to connect it back to the person's main record.
**In one sentence:** *"Who are the workers on this campaign, how do we pay them, and do we have their signature/photo on file?"*
***
### What the Service Actually Does
#### Keeps Worker Records
Workers can be created and updated in **bulk** (many at once), which matches how other parts of the system handle large volumes of data during a campaign rollout.
#### Links Workers to People
Each worker is connected to one or more "individual" records through a linking table. This means the system can:
* Look up which worker corresponds to a given person, **and**
* Look up which people are behind a given worker record
#### Automatically Captures Signature & Photo
The **first time** a worker logs their attendance, the system automatically grabs their signature and photo from that event and saves it to their worker record — no separate upload step is needed.
> ⚠️ **Important limitation:** This only happens once. If the signature or photo needs to be corrected later, someone has to manually update the record — the automatic capture won't overwrite it.
#### Protects Sensitive Information
Payment and personal details are **encrypted** while stored, and only unlocked (decrypted) when they need to be shown to an authorized caller. This protects sensitive financial and personal data at rest.
#### Works Across Multiple Regions/States
The system that listens for attendance events is built to work whether it's deployed for a single location or a central system serving multiple states/regions.
***
### Business Flow
**A. Onboarding a Worker**
1. Workers are created in bulk.
2. Each worker is checked against the existing "individual" records to make sure they're real, valid people already in the system.
3. A link is created connecting the worker to their individual record(s).
**B. Getting Ready to Pay Workers**
1. When a worker is created or updated, their payment details (bank, provider, payee info) are checked for completeness and validity.
2. This ensures that when it's time to actually send payments, all the needed information is already in place.
**C. Capturing Proof of Work**
1. The first time a worker logs attendance, an event is triggered.
2. The system finds the matching worker record.
3. If the worker doesn't already have a signature/photo on file, it saves the one from this event.
4. If they already have one, the event is ignored (see limitation above).
**D. Searching for Workers**
1. Workers can be looked up either by their own worker ID or by the ID of the person (individual) linked to them.
2. Results always come back showing which individual(s) are connected to that worker.
**E. Keeping Data Safe**
1. Sensitive fields are encrypted before being saved.
2. They're only decrypted when returned to someone authorized to see them.
***
### How the Pieces Fit Together
The diagram below shows two flows:
* **Top half — Creating a Worker:** A client (another system or user) submits worker details. The system checks everything is valid, generates IDs, encrypts sensitive data, saves it, and returns the clean (decrypted) worker info.
* **Bottom half — Attendance Enrichment:** When a worker's first attendance record comes in, the system automatically finds their profile and fills in their signature/photo — but only if it's missing.
***
### 6. Key Access Points
These are the "doors" other systems use to interact with the Worker Registry:
| What You Can Do | How |
| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| Create many workers at once | Submit a bulk request; the system validates everyone and returns the finished, readable records |
| Update many workers at once | Submit changes; only the fields you send are changed — nothing else is wiped out |
| Search for workers | Search by worker ID or by the linked person's ID; must specify which location/tenant you're searching in |
| Link workers to people in bulk | Submit a bulk request to create these connections |
| Automatic attendance capture | Happens automatically in the background when a worker's first attendance record is submitted |
***
### 7. What This Service Relies On
This service doesn't work alone — it depends on several other systems:
* **Individual Records System** — to confirm the people behind each worker actually exist
* **ID Generator** — to create unique worker IDs
* **Encryption Service** — to protect sensitive payment and personal data
* **Master Data System** — for location-specific reference data
* **Shared Utilities** — common tools and validation used across the health campaign systems
* **Messaging System (Kafka)** — carries the events that trigger saves and the attendance-capture process
* **Database (PostgreSQL)** — where worker and worker-to-person link records are stored
* **Cache (Redis)** — speeds up repeated lookups
* **A separate "writer" service** — actually commits the database changes for create/update actions
***
### 8. How Problems Are Handled
* **Bad data is caught early.** Before anything is saved, every worker record is checked; only valid ones move forward, and errors are collected and reported.
* **Updates don't erase what you didn't mean to change.** If you update part of a worker's record, the rest stays exactly as it was — it won't get blanked out.
* **A bad attendance event won't break anything.** If something goes wrong while processing an attendance event, it's simply logged and skipped — it won't crash the system.
* **Signature/photo capture won't overwrite existing data.** Once it's set, a new attendance event won't replace it (this is by design, though it has the trade-off noted below).
* **Searching with no results returns quickly and cleanly**, rather than running an unnecessarily broad search.
* **Invalid location/tenant IDs produce a clear, readable error** rather than a technical crash message.
***
### 9. Known Limitations & Risks
It's worth being aware of a few current limitations:
1. **No automatic retry for failed attendance events.** If an attendance-triggered update fails, it's simply dropped — there's no automatic "try again later" mechanism.
2. **Signature/photo can only be captured once automatically.** If it needs to be corrected, that has to be done manually through an update.
3. **Depends on the Individual Records System being available.** If that system is down, or if a batch is too large, validating worker-to-person links can be affected.
4. **Local database setup requires an extra manual step.** Automatic database setup (migrations) is turned off by default in local environments.
5. **Searching always requires specifying a location/tenant.** There's no way to search across all locations at once.
6. **Data quality depends heavily on the encryption service working correctly.** If it's misconfigured, worker data could be stored or returned in a garbled, unreadable state.
***
### 10. Technical Snapshot
| Item | Detail |
| ----------------- | -------------------------------------------------------------------- |
| Release | v2.1 — first version of this service |
| Built With | Spring Boot 3.2.2, Java 17 |
| Shared Components | Common health-campaign libraries, encryption client, tracing library |
***
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.digit.org/health/design/architecture/low-level-design/services/health-services/worker-registry.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.
