Architecture Specification

System architecture, layering and technical decisions behind Gerege Nexus. The project is built on the Gerege Template Platform (open-gerege-mn-erp) template.

Монгол  ·  English

1. System overview

Gerege Nexus is a high-performance modular monolith ERP and business application platform wired directly into Mongolia's national digital infrastructure.

1.1 High-performance modular monolith

• Zero-latency execution — business modules (contacts, products, inventory, billing, documents, developer_portal, gov_services, esign, ledger, office) implement the Go Module contract and compile into a single binary.
• Tenant app store — whether a module is active for a tenant is decided dynamically from PostgreSQL (app_installations).
• DAG dependency resolution — a directed acyclic graph plus semver constraints resolve module dependencies without cycles.
• Catalog sync — catalog/apps.json is the single source of truth and the apps table is reconciled from it on every boot.

1.2 Cloud-native resilience (inspired by go-zero)

• Adaptive circuit breaker (resilience/breaker.go) — Google SRE sliding window error-rate rejection. Every live national-service call is guarded by a per-service breaker through observability.Guard (dan/eid/ebarimt/xyp/esign).
• Adaptive load shedding (resilience/loadshedder.go) — returns 503 Service Unavailable once in-flight concurrency is exceeded.
• Exponential backoff retry (resilience/retry.go) — retries transient failures.

1.3 State data exchange and identity

• XYP state exchange — citizen civil registration (WS100101) and legal entity data (WS100201).
• DAN and E-ID (eidmongolia.mn, developer.gerege.mn) — PKI digital signature, mobile OTP, bank SSO and biometric face verification.
• OAuth2 / OIDC provider (/.well-known/openid-configuration) — the platform's own authorisation server: authorization code with PKCE (S256 only), RS256 id_tokens published through JWKS, rotating refresh tokens and a consent screen. It is the only way an external app learns who somebody is — the platform never runs anybody else's code.

Mock mode is a development convenience only; it is disabled automatically when ENVIRONMENT=production.

2. Architecture diagram

+-----------------------------------------------------------------------------------+
|                                    Gerege Nexus                                   |
+-----------------------------------------------------------------------------------+
                                          |
                +-------------------------+-------------------------+
                |                                                   |
      +-------------------+                               +-------------------+
      | Next.js 16 Client |                               |  Go 1.26 Backend  |
      |   (App Router)    |                               |   (Chi Router)    |
      +-------------------+                               +-------------------+
                |                                                   |
        +-------+-------+                                   +-------+-------+
        |               |                                   |               |
+---------------+ +---------------+                 +---------------+ +---------------+
| AI Copilot UI | | E-ID / DAN    |                 | Cloud-Native  | | State Exchange|
|  Drawer Panel | | SSO Provider  |                 | Resilience    | | (xyp.gerege)  |
+---------------+ +---------------+                 +---------------+ +---------------+
                                                            |
                                                    +---------------+
                                                    | Schema-per-  |
                                                    | tenant Postgres|
                                                    +---------------+

3. Request pipeline

1. Shared middleware — logging, panic recovery, load shedding, Prometheus metrics, security headers, CORS.
2. Authentication — the session token is read from the cookie or the Authorization: Bearer header and resolved against the sessions table. Only the SHA-256 digest of the token is stored.
3. Tenant context — tenant_id is placed in the Go context and scopes every query.
4. App gate — each module route checks app_installations; an uninstalled or disabled app returns 403 Forbidden.
5. Module handler — business logic and database transactions.

4. Core data model

Where they live: platform_events and webhook_endpoints/deliveries stay in public as queue infrastructure (two-second pollers must discover every tenant's work in one query). Other business tables live in each tenant's tenant_<uuid> schema; identity, RBAC, the app store and the audit trail stay in public.

See DATABASE_SCHEMA.md for the full schema reference.

All schema changes go through goose migrations in backend/db/migrations/. Runtime DDL is not allowed.

4.1 External service boundary

The following systems are external service workers we do not own — the platform only consumes them through clients and never re-implements their internals:

Every client follows the same contract: (1) mock mode via config.MockEnabled — off by default in production; (2) error-classified retry (transport/5xx only — a 4xx or a business rejection is never repeated); (3) context cancellation honored; (4) national_service_calls_total and national_service_mock_mode metrics. Everything else we build ourselves — the platform's purpose is to make creating new business apps fast and free (make new-app scaffolding, see MODULE_AUTHORING_GUIDE.md).

4.2 How modules talk to each other

Apps share a binary but never reach into each other's tables. Three sanctioned channels:

Dependencies run one way: master-data modules (contacts, products) sit at the bottom of the graph and depend on nothing above them, and each consumer declares the narrow interface it needs at its own call site.

Full rationale: RESEARCH_ERP_MODULARITY.md.

5. Architectural decisions

6. Maintainers

• Gerege Systems Development Team (@gerege-systems)
• Gemini AI, Claude AI