medOS Sequence

Scope: ever-api-global-sequence · Stack: NestJS + Moleculer + MongoDB · Port: internal

Centralised sequence and counter issuer for the platform. Every service that needs a running number — Hospital Number (HN), Visit Number (VN), Admission Number (AN), Episode (EP), Encounter (EN), and tenant-defined counters — calls this service rather than minting numbers locally. Allocation is performed atomically at the database level so that, under concurrent requests, each caller receives a distinct value with no gaps and no collisions. The service also formats raw sequence values into human-readable running numbers using per-tenant pattern settings (prefix, year style, zero-padding).

core

modules

HN · VN · AN

primary identifiers

atomic

allocation guarantee

gapless

per-counter ordering

Responsibilities

• Atomic next-value allocation. Each counter is a single document keyed by name; the next value is taken with an atomic find-and-increment so concurrent callers never see the same number.
• Gapless, strictly ordered counters. Because increments are serialised at the document level, every issued value is unique and monotonic per counter.
• Running-number formatting. Raw sequence integers are rendered into formatted identifiers (e.g. an AN prefix, a Buddhist-Era or Gregorian year, and a zero-padded body) according to configured settings.
• Per-tenant pattern overrides. Prefix, run type (year style), and length are resolved from administration settings; sensible defaults apply when a tenant has not configured a given counter.
• Range enforcement. HN and AN allocations are validated against configured minimum and maximum bounds, raising an out-of-range error rather than issuing an invalid identifier.

Major modules

Module	Purpose
sequence (globalSequence)	Core next-value generator and running-number formatter. Exposes the allocation and formatting actions; resolves HN/AN/EN/EP patterns.
_setting (administrationSetting)	Loads per-tenant pattern definitions — run type, prefix, and length — used to format HN and AN running numbers.

Generator

sequence

Atomic next-value allocation plus running-number formatting for HN, AN, EN, and EP.

nextgenerate-running-number

Settings

_setting

Pattern definitions (run type, prefix, length) and per-tenant overrides; falls back to defaults when unset.

run typeprefixlength

Actions

The service exposes two Moleculer actions used by other backend services:

Action	Returns	Description
sequence.next	numeric value	Allocates and returns the next raw integer for a named counter.
sequence.generateRunningNumber	formatted string	Allocates the next value for a known identifier and formats it per settings.

Identifier formatting is dispatched by name. hn, an, en, and ep each have a dedicated formatter; an unknown name raises a sequence-name-not-found error.

How allocation works

  caller service                global-sequence              MongoDB
       |                              |                         |
       |  sequence.next (name) ------>|                         |
       |                              | findOneAndUpdate        |
       |                              |   { _id: name }         |
       |                              |   $inc: { seq: 1 }  ---->|
       |                              |   upsert, return new    |
       |                              |<------- seq value -------|
       |                              | (HN/AN range check)     |
       |<------- next value ----------|                         |
       |                              |                         |
       |  generateRunningNumber ----->|  load _setting          |
       |                              |  format prefix+year+pad |
       |<------- "AN67000123" --------|                         |

The atomic find-and-increment is the single point of serialisation: no application lock is needed, and the upsert means a counter springs into existence on first use.

Pattern examples

Formatting combines a prefix, a year rendered in either Buddhist-Era (BE) or Gregorian (AD) style, and a zero-padded running body sized to a configured total length.

Counter	Shape	Example
Hospital Number	HN + year + padded body	HN67000417
Admission Number	AN + year + padded body	AN67000123
Visit Number	prefix + year + padded body	VN6700129

Configuration

Per-tenant pattern settings are read from administration settings:

Setting	Meaning
*_RUN_TYPE	Year style for the formatted number — BE (Buddhist Era) or AD (Gregorian).
*_PREFIX	Leading text of the formatted identifier (e.g. HN, AN).
*_LENGTH	Total target length; the running body is zero-padded to fill it.

HN settings are required and validated by type. AN settings are optional — when they are absent or mistyped, the AN formatter falls back to its built-in defaults (a BE year, an AN prefix, and a total length of 10) so every tenant has a working admission-number issuer out of the box.

Related catalog items

• seq.* — sequence allocation and running-number generation.
• setting.* — administration-setting lookups for counter patterns.

See also

• Backend overview
• Architecture overview
• Foundation service
• Administration service