🌠Facility
Overview
Facility is the registry of physical places in a health campaign — warehouses, health posts, clinics, storage points and distribution centres. Each facility row records what the place is, how much it can hold, and where it sits on the map.
It stores name, usage or type, permanence, storage capacity, and a shared address with GPS coordinates and a boundary or locality code.
In short: "which places exist in this campaign, what are they for, and where are they?"
Other services point to these places. Stock records movements into and out of a facility. Project links facilities to a campaign plan. Facility is the single source of truth they validate against.
At a glance
Used by: campaign setup, stock flows, project planning, field search, and dashboards.
Input: facility details, storage capacity, address, GPS, and boundary/locality code.
Output: validated facility records, search results, and downstream persistence/index events.
Source of truth: the facility registry, persisted as
facilityandaddressrows in Postgres.
Dependencies
idgen — generates facility IDs. Address IDs are UUIDs generated locally.
boundary-service — validates that each facility's locality or boundary code exists, so a facility cannot point at an unknown place.
health-services-common / -models — shared clients, validators, query builders, and the
Facility/AddressPOJOs.Kafka — carries the async create, update, and delete pipeline.
egov-persister (deployed via the
configs/repo) — writes thefacilityandaddressrows to Postgres from thesave-*,update-*, anddelete-*topics.egov-indexer / transformer → Elasticsearch — builds the dashboard read model (
facilityIndex-v1) from the same events. The transformer also caches facilities in memory to enrich other events.Redis — supports the shared repository cache layer. Search-by-id checks cache first.
Postgres — system of record for
facilityand sharedaddresstables, with tenant-aware schema resolution.
Data Model
Facility stores the business identity of a place. It carries the facility name, usage, permanence flag, and storage capacity. Each facility owns one address row through addressId. That address stores the GPS coordinates and the boundary or locality code. Updates use rowVersion for optimistic locking. Deletes are soft through isDeleted.

Business Flow
During campaign setup, facilities are created. This is usually done in bulk. Each facility is tied to a boundary or locality, so it has a known place on the map.
During campaign runtime, other services look up facilities. Stock checks the facility before recording a movement. The field app searches facilities by area. Project associates facilities with campaign tasks.
As things change, a facility's details can be updated. That includes name, capacity, and address. A facility can also be soft-deleted when it is no longer in use.
For dashboards and enrichment, facility events flow through the transformer and indexer into Elasticsearch. The transformer also keeps facilities in memory so other events can be enriched with facility names and locations.
Key APIs / Entry Points
Base path /facility/v1.
The service supports single and bulk create, update, delete, and search.
POST /facility/v1/_create
Register one facility. Validation and enrichment are synchronous. Persistence is asynchronous.
POST /facility/v1/bulk/_create
Register many facilities at once through Kafka.
POST /facility/v1/_update, /bulk/_update
Correct a facility's details.
POST /facility/v1/_delete, /bulk/_delete
Soft-delete a facility.
POST /facility/v1/_search
Find facilities by isPermanent, usage, storageCapacity, boundaryCode (locality), id, plus tenantId / limit / offset / lastChangedSince / includeDeleted URL params.
Kafka entry points (async). Bulk requests land on create-facility-bulk-topic, update-facility-bulk-topic, and delete-facility-bulk-topic. The service's own consumer picks them up. Persisted results go out on save-facility-topic, update-facility-topic, and delete-facility-topic for the persister, indexer, and transformer.
Swagger contract:
Kafka topics
create-facility-bulk-topic
in
Bulk facility create requests
update-facility-bulk-topic
in
Bulk facility update requests
delete-facility-bulk-topic
in
Bulk facility delete requests
save-facility-topic
out
Persist new facilities
update-facility-topic
out
Persist facility updates
delete-facility-topic
out
Persist facility soft-deletes
Process Flow
Use this reading order:
Send the request. A client calls to create, update, or delete on
/facility/v1.Validate and enrich. The service checks the payload, generates IDs where needed, and validates the boundary or locality code.
Publish the event. The service acknowledges the request and publishes a Kafka event for persistence.
Persist and index.
egov-persisterwrites thefacilityandaddressrows. The transformer and indexer update dashboard-facing read models from the same event.Serve reads. Search reads from Postgres. Search-by-id checks Redis first.
Writes are asynchronous.
Reads are synchronous.
The service does not write to Postgres directly.
A 202 means the request was accepted, not that the rows are already visible in Postgres.
Sequence Diagrams



Failure / Retry Handling
Async, no batch rollback. A bulk request returns
202before persistence. If one record in the batch fails validation in the consumer, it does not roll back the others. Check consumer logs and the record status. The consumer catches its own errors and logs them rather than re-throwing.Boundary check is a hard stop. If a facility's locality code is unknown, that record is flagged
NON_EXISTENT_ENTITY. If the boundary-service call itself fails, the whole batch errors withBOUNDARY_SERVICE_SEARCH_ERROR.Idempotency is via
clientReferenceId. Resubmitting the same one should not create a duplicate row.Optimistic locking via
rowVersionprotects against concurrent edits on update.Soft delete (
isDeleted) applies everywhere. Nothing is hard-deleted. Search excludes deleted rows by default unlessincludeDeleted=true.If the persister config for the facility topics is missing or stale in an environment, the API can accept writes while rows never appear in Postgres.
Recent Changes
Maintenance-only release: No new APIs, search filters, columns, or business behaviour changes. Updates are limited to
pom.xml,application.properties,CHANGELOG.md, and a test config.Tracer / error-handling upgrade: Bumped shared
health-services-common(carrying tracer2.9.2), so database errors are now handled uniformly via tracer'sExceptionAdvise— clients get a consistent error shape instead of a raw 500 on aDataAccessException.OpenTelemetry plumbing added: OpenTelemetry BOM and instrumentation BOM added to
pom.xmlfor version alignment. OTEL exporters (otel.traces/logs/metrics.exporter) are explicitly set tonone, keeping tracing opt-in per environment rather than on by default.Shared-library version bumps:
health-services-commonandhealth-services-modelsupdated in lockstep across health services; facility module version moved to 1.2.1.
Known Risks / Limitations
Search filters are basic. Only
isPermanent,usage,storageCapacityandboundaryCodeare real query columns. There is no name search, no project filter, and no "updated by others" sync filter on this branch.usageis a free string. Conventions are valued like a warehouse or health post, but the DB does not enforce them.Boundary-service is a hard dependency for create and update. A boundary lookup failure aborts the batch. An environment with a misconfigured or down boundary service cannot register facilities.
Address is denormalised per facility. Each facility owns its own address row through
addressId. The same physical place created twice yields two address rows.Search-by-id reads Redis first. Stale cache entries can, in theory, be returned for ID lookups. Filtered non-ID search always hits Postgres.
No batch rollback. Partial success in a bulk request is normal. Downstream consumers must reconcile from per-record status, not from the
202.
Last updated
Was this helpful?