Gerege Nexus¶

Gerege Eco System · Private platform

Gerege Nexus connects the organizations, services and users of Gerege Eco System. Only pre-authorized users can sign in. eID verifies identity; organization administrators grant access.

Gerege Nexus is the foundation of a Go backend, a Next.js web shell, a PostgreSQL database, an operator control plane and native clients. Business apps are added by distribution repositories as compile-time Go modules. This base repository is not a ready-made ERP suite for every sector.

Actual scope (2026-10-25): catalog/apps.json is empty — the core carries no business app; every app comes from a distribution's catalogue. The last app, io.gerege.nexus.sso_clients, moved out on 2026-08-25 to appstore-gerege-nexus, and every distribution pulls it from the app store. Migration history or frontend translations for apps such as contacts, products, inventory, billing, documents, government workflow and SSO clients may remain in this repository, but their working modules are not in this base binary. Routes for such apps do not open on this deployment.

Монгол · العربية · 中文 · English · Français · Русский · Español

What this repository actually contains¶

Part	Current implementation
Tenant plane	Authentication, session, tenant membership, RBAC, profile, app install/uninstall, AI API, devices, email verification, SSO client/provider, reporting engine
Operator plane	Tenant lifecycle, operator TOTP sign-in, audit, support, quota/metering, feature flags, runtime settings/credentials, announcements, backup/deploy management
Built-in apps	None. Every app arrives through the catalog — after `sso_clients` left on 2026-08-25, this binary contains no business app
Web	Public landing, login/setup, profile, app store, settings, control plane — all on `@gerege-systems/ui` (Tailwind 4); app screens (SSO clients, documents, contacts) remain in the shell, inert without their modules
Native	macOS, iOS/iPadOS, Windows, Android shells; PWA on Linux
Observability	`/health`, `/ready`, `/metrics`, structured logs, optional OTLP/Sentry; separate monitoring compose

Having a base platform route, table or service does not mean a user-facing business app necessarily exists. A module route works only when a compile-time module implements the pkg/nexus contract, is registered in the binary, is listed in the catalog and is installed for that tenant.

Not in this base binary¶

Contacts, products, inventory and billing business apps
The Organisation & People department/employee app (the organization's legal profile at /organisation remains part of the platform)
Documents backend module and report UI. An optional frontend client for contract/inbox exists in this repo, but the matching contract API is not yet in the current base or in the client-gerege-nexus distribution; if the endpoint does not actually respond, its link does not appear on the landing
Government services workflow UI/module
The whole station — dashboard, channels, peer/exchange API, envelope contract. On 2026-08-27 its last part moved to client-gerege-nexus
External system connectors and webhooks (Google Drive, Dropbox, Meet, customer URL). These also left on 2026-08-27; only the credential-sealing cipher remains in the core (nexus.SecretSealer). Automatically sending signed documents outward was also removed from the core
A general adaptive circuit breaker, singleflight, generic retry engine

Some of these were split out into product distribution repositories. See docs/MODULES.md for how a module is written and arrives through the catalog, docs/DISTRIBUTION.md for how a distribution takes and updates the core, and docs/ARCHITECTURE.md for the current architecture.

Key capabilities¶

Compile-time module SDK: route, permission, menu, dependency, migration, report, AI tool and capability contracts.
Per-tenant app installation and RBAC gate. A route of a module that is not installed or is disabled returns 403.
Local catalog or Ed25519-signed remote catalog; cache fallback and manual/background sync.
Password, eID, DAN, Google and upstream OIDC sign-in; also an OAuth2/OIDC provider.
PostgreSQL workspace, registry, operator schemas with RLS/role protection.
With Redis configured, cache invalidation and shared rate limiting across replicas; without it, a single-process fallback.
Load shedding for concurrent requests. Each external client has its own timeout/retry policy; a generic circuit breaker that does not exist is not claimed as part of the platform.
With a Gemini key: chat, speech-to-text, text-to-speech, translation. Distribution modules register their own AI tools for business data; the base deployment does not fabricate inventory or billing figures.
Design system: the web shell and console are on @gerege-systems/ui, and the single source of tokens is the library's theme.css. Each deployment changes its look without editing code, through BRAND_THEME_* environment variables and the "Get code" CSS from ui.gecore.mn/#theme (DEVELOPMENT.md).
E-ID, DAN and XYP (ХУР) clients are in the platform. In the production environment mocks are off by default; using the real services requires the respective credentials.

Repository layout¶

backend/
  cmd/                  api, migrate, bootstrap, catalog tools
  db/migrations/        base PostgreSQL migrations
  internal/kernel/      low-level mechanisms shared by the three planes
  internal/operator/    deployment/operator plane
  internal/workspace/   plane acting on behalf of an organization
  internal/person/      a person's own space — /api/v1/me
  internal/apps/        assembly point for distribution modules (empty for now)
  pkg/nexus/            public SDK for distribution modules
  pkg/host/             public entry point that boots a distribution binary
frontend/               Next.js web shell and control plane UI
catalog/                base catalog, manifests, chronicle
native-apps/            macOS, iOS/iPadOS, Windows, Android clients
deploy/                 image, compose, nginx, monitoring
docs/                   index of current, historical and proposal documents

Running¶

Prerequisites¶

Docker Compose, or
Go 1.26+, Node.js 20+, PostgreSQL 16+

Docker Compose¶

docker compose up -d
docker compose ps

Compose starts PostgreSQL, Redis, a one-shot migration, the backend and the frontend. Use these addresses:

Tenant web: http://nexus.localhost:3000
Control plane web: http://admin.localhost:3000
API health: http://localhost:8080/health

Development demo account:

Field	Value
Email	`admin@example.com`
Password	`Password123!`
Tenant	`Demo Corporation` (`demo`)

SEED_DEMO_DATA is enabled by default outside production. In production the demo account is not created unless true is given explicitly.

Manual¶

First start PostgreSQL (and Redis if needed), then:

cd backend
go mod download
DATABASE_URL="postgres://postgres:postgrespassword@localhost:5432/platform_db?sslmode=disable" \
  go run ./cmd/migrate up

PUBLIC_ORIGIN=http://nexus.localhost:3000 \
ALLOWED_ORIGINS=http://nexus.localhost:3000,http://admin.localhost:3000 \
CONTROL_PLANE_HOST=admin.localhost \
  go run ./cmd/api

In another terminal:

cd frontend
npm ci
CONTROL_PLANE_HOST=admin.localhost \
NEXT_PUBLIC_API_URL=http://nexus.localhost:8080/api/v1 \
NEXT_PUBLIC_CONTROL_PLANE_API_URL=http://admin.localhost:8080/api/platform/v1 \
  npm run dev

Do not guess production configuration from the README. Follow .env.example for the full set of variables and safe defaults, proxmox-gerege-net (stack/nexus) for the running deployment's configuration, and docs/OPERATIONS.md for the steps to create the first tenant/operator.

API and catalogue sources of truth¶

The API list in the README is not the complete contract. Sources that are checked together with the code:

Platform route snapshot: backend/pkg/host/testdata/routes.txt
Module SDK public API snapshot: backend/pkg/nexus/testdata/api.txt
Base catalog: catalog/apps.json (API gateway only)
SSO contract of the module SDK: backend/pkg/nexus/ssoclients.go
Configuration: .env.example

The base public endpoints include /health, /ready, /metrics, auth, setup, OAuth2/OIDC, app store, device enrollment and email verification. Routes that require a tenant session, control plane routes and module routes are each protected separately.

Tests¶

cd backend
go test ./...
go vet ./...

cd ../frontend
npm ci
npm test
npm run lint
npm run build

On top of this, CI adds migration-backed race tests, API/route boundary, PWA, host, translation-gap report, Docker build, govulncheck, gosec and native client builds. See .github/workflows/ci.yml, security.yml and native-clients.yml for the exact commands that run.

Language and documentation status¶

The UI source strings are in Mongolian and English; Arabic, Chinese, French, Russian and Spanish overlays exist. Missing overlay strings fall back to English and CI reports the gaps — no claim is made that every screen is 100% translated.

The README exists in seven languages. Not every technical document has seven translations; the language and status of each file are recorded in docs/README.md. Files named PLAN, PROPOSAL, PROMPT or WORKLOG are not the current runtime contract. Do not use them on their own as a source for operating instructions.

Security and project status¶

Do not publish vulnerabilities in public issues; use the private reporting procedure in SECURITY.md.