api

The MGPL Diagnostics backend: one GraphQL endpoint for the whole lab.

Sign-in, patients, bookings, samples, results, reports, billing, books, GST, receivables, settlements, cash and bank, documents. TypeScript, GraphQL Yoga on Fastify, PostgreSQL (through PgBouncer) or MongoDB, Redis. Runs as any number of replicas behind a load balancer.

Docs · Architecture · Getting started · API reference · Client · Scaling

---

flowchart LR
  APP["Apps<br/>@mgpl-diagnostics/client"] -- "POST /graphql" --> LB["load balancer<br/>(nginx)"]
  LB --> API["api × N replicas<br/>controllers → services"]
  API --> K["auth-kit · db-kit · catalog-kit<br/>report-kit · invoice-kit · ledger-kit · finance-kit"]
  K --> PGB["PgBouncer<br/>transaction pooling"]
  PGB --> PG[("PostgreSQL")]
  K --> MG[("or MongoDB")]
  K -.-> R[("Redis")]
  R -. "BullMQ jobs" .-> W["worker<br/>emails · documents"]
  W --> K

Loading

What you get

• One endpoint. 140 queries and mutations; reports and invoices come back as base64 PDFs or HTML inside the response, CSV exports as text. No other routes except GET /health.
• The kits as internal libraries. auth-kit sessions and roles, db-kit storage and workflows, catalog-kit prices and reference ranges, report-kit and invoice-kit rendering, ledger-kit books, finance-kit GST and finance. See docs/01-overview.md.
• Access and refresh tokens. Short-lived JWTs plus single-use, rotating refresh tokens bound to the device; logout and disabling still apply at once. See docs/06.
• A worker on Redis + BullMQ for reset emails and background documents (npm run worker); without Redis the same jobs run in the API process. See docs/16-worker.md.
• Horizontal scaling through PgBouncer. Run N identical replicas behind a load balancer: sessions, login limits and jobs live in Redis, and PostgreSQL is reached through PgBouncer in transaction mode (the whole test suite runs through it). GET /health is the readiness check, SIGTERM drains gracefully, and docker compose up --scale api=N runs the whole stack. See docs/17-scaling.md.
• Layers. schema/ (SDL) → controllers/ (permissions, mapping) → services/ (kit calls) → kits.
• Safe by construction. The organisation and user come from the session; every record is checked against them and against its branch; unknown errors are masked; depth and list limits.
• Money in paise, books always balanced. Every invoice, payment and credit note posts its voucher in the same transaction.

Quick start

npm ci                             # kits from GitHub Packages; NODE_AUTH_TOKEN with read:packages (docs/03)
cp .env.example .env               # every variable documented; SMTP_URL / MAIL_FROM for mail
SEED_ORG_NAME=… SEED_ORG_CODE=MGPL SEED_BRANCH_CODE=ARG01 SEED_BRANCH_NAME=Arang SEED_BRANCH_STATE=22 \
SEED_OWNER_NAME=… SEED_OWNER_EMAIL=… SEED_OWNER_PASSWORD=… npm run seed
npm run dev                        # http://localhost:4000/graphql

mutation { login(input: { email: "owner@example.in", password: "…", orgCode: "MGPL" }) { token } }

query { viewer { user { name } organization { name } permissions } }

import { createMgplGraphQLClient } from "@mgpl-diagnostics/client";
const mgpl = createMgplGraphQLClient({ url: "http://localhost:4000/graphql" });
await mgpl.auth.login({ email, password, orgCode: "MGPL" });
const hits = await mgpl.catalog.search("cbc");

Docs

Everything from A to Z is in docs/, with Mermaid diagrams: overview, architecture, getting started, the generated API reference, errors, auth and permissions, domain flows, documents, configuration, data and money, testing, deployment, adding a feature, client, glossary, worker, scaling, and runnable examples. What has to happen outside this repo (releases, org settings, deployment) is in docs/LOCAL-AGENT-BRIEF.md.

Development

npm run typecheck
npm test                    # end-to-end over HTTP on PostgreSQL + MongoDB (TEST_BACKENDS=pg for one)
npm run build               # dist/main.js, dist/index.js
npm run schema              # schema.graphql
npm run docs:reference      # docs/04-api-reference.md
npm run llms                # llms-full.txt

Part of MGPL Diagnostics

Repo	Role
api	the backend: one GraphQL endpoint
client	frontend SDK (zero dependencies)
auth-kit · db-kit · catalog-kit	auth, data, test catalog
report-kit · invoice-kit	report and invoice rendering
ledger-kit · finance-kit	books, GST and finance
security-kit · mail-kit · worker-kit	security headers, client IP and device signals; mail; background jobs
pgbouncer-kit	PgBouncer setup (config, userlist, compose, TLS) for the connection pooler in front of PostgreSQL
report-studio	Next.js reference app

_{© MGPL Diagnostics (Maa Gayatri Path Lab). All rights reserved; see LICENSE. ledger-kit is our own software, not affiliated with Tally Solutions.}