Technology stack¶
Every platform in the ecosystem runs on one stack. That is not an accident: it means a developer moving from one repo to the next has nothing new to learn, and a security fix can be rolled out to every system in the same shape.
Where Gerege Nexus differs
Gerege Nexus runs on the same stack (Go · chi ·
pgx · no ORM · Next.js App Router) but differs in three ways: it is a
modular monolith (modules compile into one binary and are distributed per
tenant through an app store), it migrates with goose, and it leans on
PostgreSQL alone, without Redis. Versions: Go 1.25 · Next.js 15.
Backend¶
| Component | Choice |
|---|---|
| Language | Go 1.26 |
| HTTP | standard library net/http + the go-chi/chi router |
| Database | PostgreSQL — jackc/pgx (pgxpool), hand-written SQL |
| Cache / session | Redis |
| Architecture | Clean Architecture — handler → usecase → repository → domain |
Why no ORM?
The data layer is written as hand-written SQL on top of pgx. The
reasons: to use Postgres features that run deep in the database — Row-Level
Security (RLS), CTEs, LISTEN/NOTIFY, JSONB — directly rather than through
an ORM's abstraction; and to remove the need to guess what query will
actually be generated.
The hard rule of Clean Architecture: no back-imports. The business core
(domain, usecase) never imports a web framework. That is what guarantees
the HTTP layer can be swapped without touching business logic.
Frontend¶
| Component | Choice |
|---|---|
| Framework | Next.js 15/16, App Router |
| Pattern | BFF (Backend-for-Frontend) |
| Data layer | TanStack Query |
What BFF means here: the browser never talks to the backend directly. It only talks to Next.js routes on the same domain, and those proxy to the backend from the server side.
The result: tokens never reach client-side JavaScript — a cookie session is used instead, and XSS stops being a token-theft vector. On top of that comes double CSRF protection (a custom header plus an origin check).
Mobile and desktop¶
| Platform | Technology |
|---|---|
| iOS | Swift, SPM SDK (GeregeSmartID) + a per-brand app |
| Android | Kotlin / Jetpack Compose SDK |
| macOS | SwiftUI RP client + USB token kit |
| Windows | MSIX (signed) |
| Web RP | TypeScript SDK |
AI pipeline¶
Built on Gemini, as an SDK-free REST client plus function calling:
- text and voice chat,
- STT (speech → text) and TTS (text → speech),
- live translation,
- a pgvector knowledge base indexed from code and documentation,
- answers in the user's own language; a chat widget that needs no login.
Layered system prompt: guardrails hard-coded in the source, plus scope and
instructions that admins configure through the database. That keeps the
assistant inside its intended boundaries. The search_knowledge tool grounds
answers in real data from the knowledge base and prevents invented ones.
Cryptography¶
The signing code was ported from a Java/Spring original, so it has to remain fully compatible at the wire level. That is locked down with frozen golden vectors:
- compressed SEC1 EC point serialisation,
- Java
BigInteger.toByteArray()semantics (sign-byte behaviour).
The Go server, the iOS SDK and the Android SDK must all produce byte-identical results.
Never delete a golden vector
The golden.json files cannot be regenerated. They are the only proof
of compatibility with the original system. Any change to cryptographic code
must be checked against these tests.
Infrastructure¶
| Component | Choice |
|---|---|
| Containers | Docker Compose |
| CI/CD | GitHub Actions (with self-hosted Windows/macOS runners) |
| Edge | nginx — TLS termination, rate limiting, reverse proxy |
| Certificates | Let's Encrypt (certbot, webroot) |
| Documentation | MkDocs Material + mkdocs-static-i18n, multilingual |
See Deployment and CI/CD for the detail.
Observability¶
- OpenTelemetry — distributed tracing,
- Prometheus — metrics (
/metrics), - Zap — structured logging,
- Audit log — hash-chained, append-only; readable by admins only, with an integrity check available.
Closed in production
/metrics and /swagger are behind a bearer token in production. They
expose internal structure, so leaving them open is an information-disclosure
risk.
Testing¶
- Unit tests — at the business-logic layer,
- testcontainers integration tests — against a real PostgreSQL/Redis,
- golden-vector tests — for cryptographic compatibility.