​
Module Map

​
Domains

​
Tenancy & Auth

Platform

Admin · platform userTenants (e.g. Namma Yatri). Holds service-account credentials and dashboard users. Every user belongs to one platform.Tables: platforms

Auth

Platform service accountPOST /auth/token — the partner backend exchanges a phone number and id-proof for an app JWT. Aarokya find-or-creates the user.Tables: users (find-or-create)

​
Identity

User

App user · adminProfile, onboarding, soft-delete. App users act on their own record; admins manage all.Tables: users

Dependant

App user · adminFamily members linked to a user. Append-only versioned rows — every update supersedes the previous version. The SELF dependant is system-managed.Tables: dependants

MRN

App user · benefit provider · adminLinks a dependant to a benefit provider with an external Medical Record Number. Unique per (dependant, provider) pair.Tables: mrns

​
Benefit Catalogue

Benefit Provider

Admin · providerCompanies that offer benefits (e.g. Narayana). Holds its own service-account credentials and dashboard users. A provider must exist before any benefit references it.Tables: benefit_providers

Benefit

Provider / admin write · authenticated readCatalogue offerings — CONSULTATION or INSURANCE_POLICY — linked to a provider, with typed benefit_details.Tables: benefits

Benefit Entity

Admin readAppend-only record of a benefit granted to a user (the join between a user and a CONSULTATION or INSURANCE_POLICY benefit instance).Tables: benefit_entities

​
Money

Account

App user · admin · trusted backendA holder’s ring-fenced accounts plus balance and ledger, backed by the PBA (Prepaid Bank Account) ledger. Holders are users or sponsors.Tables: accounts

Order

App user · adminA self-contribution top-up and its settlement status against the user’s account.Tables: orders

Sponsor

Trusted backendAn entity (individual or organisation) that funds workers’ care — with its own PBA account, balance, deposits, and contributions.Tables: sponsors

​
Insurance & Autopay

Insurance Policy

App user · adminPreview → enrollment form → issue a Narayana policy, then track it through its provider-driven lifecycle. Documents and admin management included.Tables: insurance_policies

Mandate

App user · adminA recurring UPI autopay authorisation that funds a user’s premiums, with register, status, pause, resume, and revoke.Tables: mandates

Mandate Execution

Trusted backend · adminOne scheduled debit attempt against a live mandate, claimed idempotently and reconciled with the upstream order.Tables: mandate_executions

Benefit Provider Order

Provider · adminAn external order placed with a benefit provider (e.g. an insurer), debited from the user’s account.Tables: benefit_provider_orders

​
Care

Consultation

App user · adminA chat-thread teleconsultation against an eligible benefit, bridged to the Narayana conversation gateway — messages, attachments, read receipts, and a status lifecycle.Tables: consultations

​
Authentication Model

Every request is a bearer JWT. Tokens are minted by Keycloak (service accounts, admins, dashboard users) or by POST /auth/token (app users). When a token expires the issuer re-authenticates — the partner backend simply calls POST /auth/token again.

​
User Lifecycle

​
Shared Infrastructure

AuthN middleware

AuthNMiddleware authenticates every request app-wide and injects an Actor; handlers pull web::ReqData<Actor> and authorize with actor.require_*()? — no handler can skip auth accidentally.

Error Envelope

All errors return {"error": {"code": "...", "message": "..."}}. Switch on code (e.g. MR_1103), not message.

OpenAPI / Swagger

The OpenAPI spec and a Swagger UI are served by the backend, generated from the route handlers via utoipa. The same spec powers the Try It Out playground here.

​
Money & IDs

Amounts

Stored internally as integer minor units (MinorUnit) with a Currency enum. At the API boundary an amount is an AmountResponse object — { "value": 99.99, "currency": "INR" } — value in major units.

Identifiers

User IDs are 12-digit numeric strings (printable on a card). Every other entity uses a UUID v7 (time-sortable). IDs are always generated server-side — never client-supplied.