Contribute on GENIE.AI

How to open a MR

Mon, 01 Jan 0001 00:00:00 +0000

Goal

Open a merge request (MR) against the upstream un/itu/genie-ai project on GitLab that passes CI on the first push and lands within a single review cycle.

Branch policy

Rule	Reason
One MR per logical change	Easier to revert, easier to bisect
Branch name: `<type>/<scope>-<summary>` (e.g. `feat/admin-logs-tags`, `fix/mobile-i18n-crash`, `docs/clarify-rag-overrides`)	Consistent, greppable history
Base branch: `main` for features; `release/X.Y` for PATCHes	Trunk-based for features; cherry-pick for fixes
Rebase before review	No `Merge branch 'main' into ...` noise in the diff
Squash-merge at landing	One commit per MR in `main`

Never push directly to main or release/*. Branch protection rejects the push.

Repo layout & module map

Mon, 01 Jan 0001 00:00:00 +0000

Top-level layout

genie-ai/
├── api-gateway-solution/ # Kong configuration scripts
├── components/
│ ├── gov-chat-backend/ # Node.js / Express BFF
│ ├── gov-chat-frontend/ # Vue 3 SPA
│ └── document-repository/# Upload + ClamAV + dataprep proxy
├── configs/ # LLM prompts, OTel collector, Grafana dashboards
├── deploy/
│ └── ansible/ # Production Swarm deploy playbook
├── docs/ # Internal dev docs (NOT published)
├── genie-ai-overlay/ # OPEA Python microservices
│ ├── chatqna/ # Mega-service that orchestrates the RAG DAG
│ ├── retriever/ # ArangoDB hybrid search
│ ├── reranker/ # Cross-encoder reranker wrapper
│ ├── embedding/ # TEI embedding wrapper
│ ├── textgen/ # vLLM text-generation wrapper
│ ├── dataprep/ # Document ingestion + labeling + contextual retrieval
│ ├── core/ # Shared types, protocols, constants
│ ├── tests/ # Pytest suite (mocks comps + ArangoDB)
│ └── contracts/ # In-image contract tests (real vendored comps)
├── mobile/
│ └── genie_ai_mobile/ # Flutter app (Android + iOS)
├── secrets/ # SSL certs (NOT committed)
├── site/ # Hugo + Docsy user-facing docs site
├── tests/ # E2E tests, config validator, log assertions
├── docker-compose.yaml # Single dual-mode compose (compose + swarm)
└── env # Configuration template (committed; cp env .env)

Components

`components/gov-chat-backend/`

Node.js 22 / Express backend-for-frontend. Owns authentication delegation to Keycloak, the chat proxy to ChatQnA, the analytics store, and the admin surface. Tests in __tests__/ (Jest). Uses createApp() pattern for supertest isolation.

Dev workflow

Mon, 01 Jan 0001 00:00:00 +0000

Goal

Set up a local GENIE.AI dev environment so lint, test, and a backend hot reload all work.

Prerequisites

Tool	Version	Why
Node.js	22.x	Backend, frontend, doc-repo
npm	10.x	Bundled with Node 22
Python	3.11	OPEA overlay development
Docker Engine	23+ with Compose v2	Dependency stack (ArangoDB, Redis, Keycloak)
Flutter	3.10+	Mobile dev (optional)
git	2.40+	Branch / rebase
glab	latest	GitLab MR / CI

Backend (`components/gov-chat-backend/`)

cd components/gov-chat-backend
npm install
npm run dev # nodemon index.js (hot-reloads on save)
npm test # full Jest suite
npm run test:contract # route handlers only

Lint / format:

Add a new doc to this site

Mon, 01 Jan 0001 00:00:00 +0000

Goal

Add a new page to this site without breaking the sidebar order or the cross-link audit, and have it picked up by the next Hugo build.

Where docs live

User-facing docs go under site/content/en/docs/<section>/<slug>.md. The 15 sections are listed on the root landing:

Section	When to add here
`get-started/`	Quickstarts, concepts, glossary, FAQ
`architecture/`	System design, trust boundaries, OPEA contract
`core/`	Foundational concepts shared across components
`deploy/`	Install recipes (Compose, Swarm, GPU, A40)
`operate/`	Day-to-day ops (backup, scaling, updates, troubleshooting)
`observe/`	Metrics, logs, traces, dashboards, alerting
`configure/`	Realm, IdP, banners, CORS / CSP, locale whitelist
`rag-pipeline/`	RAG stages: embedding, retrieval, reranking, generation, translation
`knowledge-base/`	Ingestion, taxonomy, document lifecycle, content quality
`backend/`	HTTP API contracts
`frontend/`	Vue SPA: auth, chat, sidebar, admin, theming
`mobile/`	Flutter app
`reference/`	Canonical tables (env-vars, API, OPEA extensions, glossary)
`contribute/`	Repo, workflow, MR, i18n, security triage, style
`audit/`	Internal docs-audit artifacts (weight 999, last section in nav)

Dev-internal docs go under docs/ — they are not published.

Build and run locally

Mon, 01 Jan 0001 00:00:00 +0000

This guide gets you from a fresh clone to a working local stack across every GENIE.AI component — frontend, backend, document-repository, mobile, OPEA microservices, Kong/Nginx. It also covers the daily commands you need while developing.

For high-level orientation, see Project Overview. For code layout, see Source Tree Analysis. For service-to-service contracts, see Integration Architecture.

CI/CD pipeline, Ansible deployment, and observability dashboards live in their own sections. This page focuses on local dev. Links at the bottom of each section point to the canonical home of each topic.

Release process

Mon, 01 Jan 0001 00:00:00 +0000

Goal

Cut a release of GENIE.AI — tag, changelog, publish — without breaking the deploy pipeline or the version-gated docs.

Versioning

GENIE.AI follows Semantic Versioning:

MAJOR (vX.0.0) — breaking changes (API contract change, env-var rename with no fallback, schema migration).
MINOR (v0.X.0) — new features (new microservice, new admin endpoint, new language). Backwards-compatible.
PATCH (v0.0.X) — bug fixes, security patches, doc improvements.
Pre-release (v0.0.0-alpha.N, v0.0.0-rc.N) — opt-in builds.

Standard release (MAJOR / MINOR)

Gather changes since last release.

i18n contribution

Mon, 01 Jan 0001 00:00:00 +0000

Goal

Add or fix a translation in the GENIE.AI web UI, mobile app, or Keycloak login pages without breaking the locale whitelist or the no-duplicate-keys invariant.

Three translation surfaces

Surface	Where	File pattern
Web (Vue 3 SPA)	`components/gov-chat-frontend/src/i18n/locales/<lang>.js`	one file per locale
Mobile (Flutter)	`mobile/genie_ai_mobile/lib/src/localization/app_en.arb` (source) + Flutter-generated `app_localizations_<lang>.dart`	ARB (English only) + generated Dart
Keycloak email theme	`configs/keycloak/themes/genie/email/messages/messages_<lang>.properties`	Java properties

English is the source of truth. The nameEN field of every translatable resource (service categories, services) is what the RAG pipeline retrieves against. Do not translate nameEN.

Locale availability (whitelist)

Surface	Knob	Default
Web	`VUE_APP_AVAILABLE_LOCALES` (comma-separated codes, e.g. `en,es`)	All locales shipped
Mobile	`KeycloakConfig.supportedLocaleCodes` per flavor	All locales shipped
Keycloak	`KEYCLOAK_SUPPORTED_LOCALES` (JSON array, e.g. `["en","es"]`)	Curated default

Setting a whitelist hides locales from the picker but does not delete the source files.

Security triage (CVE playbook)

Mon, 01 Jan 0001 00:00:00 +0000

Goal

Triage a CVE finding (container scanning, dependency scanning, or SAST) and decide fix vs. dismiss with cited evidence.

Triple-source verification

For every distinct CVE, verify with three independent sources before any decision — a scanner or a single web page is not proof.

Installed == latest candidate. Run apt-cache policy <pkg> inside the same base image. If the installed version equals the repo candidate, no package bump helps.
Trivy fix[] empty? Extract from the promote-stage gl-container-scanning-report.json artifact.
Debian Security Tracker (security-tracker.debian.org/tracker/<CVE>): vulnerable / postponed vs fixed in <version> per suite (bookworm vs trixie differ).

Classification buckets

Bucket	Meaning	GitLab reason	Action
`affected-no-fix`	We ARE affected; no upstream patch exists	`ACCEPTABLE_RISK`	Dismiss with a comment that says so plainly
`not_affected`	Package present but unreachable at runtime (e.g. `linux-libc-dev` kernel headers — the container uses the host kernel)	`NOT_APPLICABLE`	Dismiss
`false_positive`	Scanner misattribution / test-only data	`FALSE_POSITIVE`	Dismiss
`fixable`	A fix exists in the distro repo or an upstream release we can pull	—	Fix, do not dismiss (base-image bump, `apt-get upgrade` layer, dependency bump)

The buckets above are the container-scanning reading. For a SAST finding whose code ships but whose dangerous path is gated (a vendored dependency compiled into a binary, behind a config flag the deployment flavors keep off), NOT_APPLICABLE would claim the code is unreachable — it is reachable in the dev flavors and in any build made without the flag. Use MITIGATING_CONTROL there, and say in the comment where the code ships, where it is reachable, and which control keeps it out of the deployment.

Style guide

Mon, 01 Jan 0001 00:00:00 +0000

Language policy

English only for all documentation, comments, code, variable names, and user-facing text. Exceptions:

i18n translation files under components/gov-chat-frontend/src/i18n/locales/*.js and mobile/genie_ai_mobile/lib/src/localization/app_*.arb are intentionally multilingual.
Translators’ commit messages may use any language.
Conversation with the user may be in their preferred language — this is meta-documentation, not site content.

Voice

Imperative for steps (“Run npm test”, not “You should run the tests”).
Active voice preferred (“the operator scales the service”, not “the service is scaled by the operator”).
Second person sparingly (“you” only when the reader is the subject of the action).
Avoid hype (“blazing fast”, “next-gen”) — describe what it does and what it enables.
No emoji in technical docs.

Headings

Title case for H1–H2. Sentence case for H3+.
One H1 per page (Docsy auto-derives from title:).
Avoid “Introduction”, “Overview”, “Conclusion” — describe what the section does.

Code blocks

Always include the language tag (bash, python, yaml, json, typescript, vue, dart, sql).

For shell blocks, always show expected output on the next line in a comment:

docker compose ps
# NAME SERVICE STATUS PORTS
# genieai-nginx-1 nginx running (healthy) 0.0.0.0:443->443/tcp

Use Docsy shortcodes ({{< callout >}}, {{< tabs >}}, {{< cards >}}) instead of hand-rolled HTML where possible.

Callouts

type="info" — prerequisites, neutral context.
type="tip" — non-obvious shortcut.
type="warning" — operationally dangerous trap (do not ignore).

Tables

Use tables for parallel data (env vars, error codes, model names).
Avoid tables for narrative content — use a list.
Always include a header row.

Frontmatter

See Add a new doc. Mandatory fields:

Contribute on GENIE.AI

How to open a MR

Goal

Branch policy

Repo layout & module map

Top-level layout

Components

components/gov-chat-backend/

Dev workflow

Goal

Prerequisites

Backend (components/gov-chat-backend/)

Add a new doc to this site

Goal

Where docs live

Build and run locally

Release process

Goal

Versioning

Standard release (MAJOR / MINOR)

i18n contribution

Goal

Three translation surfaces

Locale availability (whitelist)

Security triage (CVE playbook)

Goal

Triple-source verification

Classification buckets

Style guide

Language policy

Voice

Headings

Code blocks

Callouts

Tables

Links

Frontmatter

`components/gov-chat-backend/`

Backend (`components/gov-chat-backend/`)