Layered architecture¶
The ecosystem is made of five layers. Each layer serves the one above it; the upper layer knows nothing of the lower layer's internals and talks to it only through its contract.
┌──────────────────────────────────────────────────────────────────────────┐
│ LAYER 4 — VERTICAL PRODUCTS │
│ ring.dgov.mn Ring System — process re-engineering │
│ hurdan.dgov.mn Khurdan platform — service delivery / oversight │
│ developer.gerege.mn Developer Portal (dgov counterpart exists) │
│ wallet.gerege.mn Gerege Wallet — citizen digital wallet │
│ geregekiosk.mn Gerege Kiosk — self-service terminal platform │
├──────────────────────────────────────────────────────────────────────────┤
│ LAYER 3 — PLATFORM FOUNDATION │
│ ── 2nd generation: Nexus — modular monolith, app store ──────────────── │
│ nexus.gerege.mn Gerege Nexus — upstream, 8 modules │
│ eduge.mn Eduge.mn — sector brand fork │
│ (domain pending) Gerege SSO — sign-in focused fork │
│ ── 1st generation: Template — a fork per repo ───────────────────────── │
│ template.gerege.mn Gerege Template Platform │
│ template.dgov.mn Government Template Platform V3.0 (+ Node.js port) │
│ gerege.mn Gerege Platform (an SSO provider in its own right) │
│ → Clean Architecture Go + Next.js BFF + Gemini AI pipeline │
├──────────────────────────────────────────────────────────────────────────┤
│ LAYER 2 — IDENTITY / SSO (OIDC provider) │
│ sso.gerege.mn Gerege SSO sso.dgov.mn Government SSO │
│ dan.gerege.mn DAN Gateway gsign.gerege.mn G-Sign │
│ → first-party Go OAuth2/OIDC code (Hydra fully replaced), one DB │
│ → eID proxy: relays permitted eID services to registered apps only │
├──────────────────────────────────────────────────────────────────────────┤
│ LAYER 1 — IDENTITY / PKI CORE │
│ eID Mongolia (eid-platform-mn) │
│ server (Go) · web · admin · iOS SDK · Android SDK · macOS/Windows │
│ 2-of-2 threshold ECDSA · dual key / dual cert (PIN1 auth / PIN2 sign) │
│ CA · OCSP · CRL · TSA │
├──────────────────────────────────────────────────────────────────────────┤
│ LAYER 0 — DATA EXCHANGE │
│ X-Road instance MN — central server, security servers │
│ Adjacent service: xyp.gerege.mn (company registry lookups) │
└──────────────────────────────────────────────────────────────────────────┘
Layer 0 — Data exchange¶
What: A standardised channel for data exchange between organisations —
X-Road (instance MN).
Role: Member organisations call each other's services in an authenticated,
signed and timestamped way. Each security server represents its own member; the
central server signs and distributes the trust list (globalconf).
Notable link: eID Mongolia acts as X-Road's CA — that is, Layer 1 supplies the root of trust to Layer 0.
Status: Partial The central server and the first security servers are up and the topology is defined; broad rollout is still in progress.
Layer 1 — Identity / PKI core¶
What: eID Mongolia — the national eID platform (Smart-ID / eIDAS style).
Role: Identify and authenticate citizens and organisations, and produce legally binding signatures. Plus the full certificate lifecycle: issuance (CA), validity checking (OCSP/CRL) and timestamping (TSA).
Key decisions:
- 2-of-2 threshold ECDSA — the signing private key never exists in full on either side.
- Dual key / dual certificate — PIN1 → authentication, PIN2 → signature.
- The identifier is
civil_id; the ETSI ID isPNOMN-<civil_id>for a person andNTRMN-<...>for an organisation. - KYC via DAN, with face-recognition liveness.
Consumers: Layer 2 (SSO) directly; Layers 3–4 through SSO.
Status: Production
Layer 2 — Identity / SSO¶
What: OAuth2/OIDC providers — Gerege SSO
(sso.gerege.mn) and Government SSO (sso.dgov.mn), plus the adjacent
DAN Gateway and G-Sign.
Role — three things:
- Identity provider — RPs can
Sign in with Gerege. Authorization code + PKCE (S256), rotating refresh tokens with reuse detection,client_credentials. - eID proxy — permitted eID services are relayed only to registered applications. Apps never reach eID directly.
- The single home for app registration — OAuth clients and client secrets are created and stored here, and nowhere else.
No Hydra
Ory Hydra was previously used and has since been rewritten as first-party Go code. The separate Hydra database was merged into the main one. The result: one fewer external dependency, one fewer migration chain, and lower operating cost.
Status: Production
Layer 3 — Platform foundation¶
This layer now has two generations. Both are in production, and the transition between them is under way.
2nd generation — Gerege Nexus Production¶
What: a modular monolith platform — business modules implement a Go Module
contract and compile into one binary; which apps are active for a tenant is
decided by the app store (app_installations) in PostgreSQL.
What changed: in the 1st generation, a new product meant a fork of the template. On Nexus, a new product is usually a new module — or, for a brand, a fork of the upstream that is refreshed by merging from it.
| 1st generation (Template) | 2nd generation (Nexus) | |
|---|---|---|
| New product | Fork the template | Write a module, or fork for a brand |
| Distribution | One deployment per repo | Per tenant, through the app store |
| How code travels | open-gerege-core · @gerege/ui-core packages |
Upstream → forks merge from it |
| Calls between modules | HTTP | In-process Go calls |
Current forks: nexus.gerege.mn (upstream, reference deployment) ·
eduge.mn (education sector) · Gerege SSO (centred on the sign-in layer, no
domain yet).
The eight modules shipped: Contacts · Products · Inventory · Billing & e-Barimt · Digital Documents · Developer Portal · PDF E-Sign (eID PIN2) · Government services (configurable workflow, hierarchy, SLA).
Nexus does not replace layer 2
Nexus carries its own OAuth2/OIDC provider, but it serves that deployment's own tenants and third-party clients. Ecosystem-wide, the only route to identifying a citizen remains layer 2 — Nexus, too, never reaches eID directly.
1st generation — Template Platform Production¶
What: the Template Platform — a production-ready foundation for building digital services; plus Gerege Platform, an extended variant that can act as an SSO provider itself.
Role: A new service starts with all of this ready on day one:
- eID + Google authentication, sessions (JWT access + refresh rotation),
- organisations and membership, protected by RLS,
- RBAC (
superadmin → admin → manager → user), audit log, - API gateway (services / routes / consumers / API keys / policies + telemetry),
- AI pipeline (Gemini) — chat, STT/TTS, translation, knowledge base,
- a hardened security baseline (CSP/HSTS, CORS allow-list, rate limiting, RLS),
- observability (OpenTelemetry + Prometheus + structured logs).
Status: Production
Layer 4 — Vertical products¶
What: Real products branched from the template.
| Product | Purpose | Status |
|---|---|---|
| Developer Portal | API catalogue, app-registration gateway | Production |
| Gerege Wallet | Citizen digital wallet | Partial |
| Gerege Kiosk | Self-service terminal platform | Production |
| Ring System | Re-engineering of public service processes | Partial |
| Khurdan platform | Service delivery and oversight | Production |
Ring and Khurdan run on the government line.
The dependency rule¶
All code in the ecosystem observes the following dependency direction:
graph TD
L4["Layer 4 — Vertical products"] --> L3["Layer 3 — Platform foundation"]
L3 --> L2["Layer 2 — SSO / OIDC"]
L2 --> L1["Layer 1 — eID / PKI"]
L2 -.->|"lookups"| L0["Layer 0 — X-Road"]
L1 -.->|"acts as CA"| L0The rule: never reach across a layer. A Layer 4 application does not call eID directly — it always goes through SSO. This both keeps credentials in one place and keeps the audit trail unbroken.
The one permitted "downward" link is eID → X-Road CA: it is the root of trust and is therefore exempt from the layering rule.