Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🌠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 facility and address rows 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 / Address POJOs.

  • Kafka — carries the async create, update, and delete pipeline.

  • egov-persister (deployed via the configs/ repo) — writes the facility and address rows to Postgres from the save-*, update-*, and delete-* 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 facility and shared address tables, 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.

Endpoint
Purpose

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

Topic
Dir
Purpose

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:

  1. Send the request. A client calls to create, update, or delete on /facility/v1.

  2. Validate and enrich. The service checks the payload, generates IDs where needed, and validates the boundary or locality code.

  3. Publish the event. The service acknowledges the request and publishes a Kafka event for persistence.

  4. Persist and index. egov-persister writes the facility and address rows. The transformer and indexer update dashboard-facing read models from the same event.

  5. 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 202 before 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 with BOUNDARY_SERVICE_SEARCH_ERROR.

  • Idempotency is via clientReferenceId. Resubmitting the same one should not create a duplicate row.

  • Optimistic locking via rowVersion protects against concurrent edits on update.

  • Soft delete (isDeleted) applies everywhere. Nothing is hard-deleted. Search excludes deleted rows by default unless includeDeleted=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 tracer 2.9.2), so database errors are now handled uniformly via tracer's ExceptionAdvise — clients get a consistent error shape instead of a raw 500 on a DataAccessException.

  • OpenTelemetry plumbing added: OpenTelemetry BOM and instrumentation BOM added to pom.xml for version alignment. OTEL exporters (otel.traces/logs/metrics.exporter) are explicitly set to none, keeping tracing opt-in per environment rather than on by default.

  • Shared-library version bumps: health-services-common and health-services-models updated in lockstep across health services; facility module version moved to 1.2.1.

Known Risks / Limitations

  • Search filters are basic. Only isPermanent, usage, storageCapacity and boundaryCode are real query columns. There is no name search, no project filter, and no "updated by others" sync filter on this branch.

  • usage is 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?