GENIE.AI

Api Contracts Backend

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

For integrators. The backend (BFF) HTTP API contracts — request/response shapes for auth, chat, files, analytics, and admin endpoints.

Component: components/gov-chat-backend/ (Node.js/Express) Base URL: https://<domain>/api (via Kong Gateway) Documentation: Swagger/OpenAPI available at /api-docs

Authentication

All endpoints (except where noted) require Keycloak JWT authentication via Authorization: Bearer <token> header.

Auth middleware: keycloakAuthMiddleware.authenticate (Keycloak OIDC) Admin endpoints: Additional keycloakAuthMiddleware.requireAdmin middleware

Route Domains

1. Authentication Routes (`/api/auth`)

Route File: routes/auth-routes.js Auth Required: None (login/logout endpoints) Base Paths: /api/auth

Architecture

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

Architecture Overview

High-level architecture of the GENIE.AI platform with Keycloak OIDC integration.

1. System Context

graph TB
 subgraph External Actors
 EU[End User]
 SA[IT Admin]
 FA[Functional Admin]
 end

 subgraph External IdPs
 Google[Google Workspace]
 MSFT[Microsoft Entra ID]
 SAML[SAML IdP]
 end

 subgraph GENIE.AI Platform
 GENIE[GENIE.AI<br/>RAG Platform]
 end

 EU -->|Web Browser| GENIE
 SA -->|Admin Console| GENIE
 FA -->|Admin Console| GENIE

 Google -.->|OIDC / OAuth2| GENIE
 MSFT -.->|OIDC / OAuth2| GENIE
 SAML -.->|SAML 2.0| GENIE

GENIE.AI is a sovereign RAG platform for the public sector. It authenticates users via Keycloak, which can broker to external identity providers (Google, Microsoft, SAML). Three actor personas interact with the system:

Backup & Restore

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

The two things you must be able to restore after a failure are the knowledge base (ArangoDB — chunks, embeddings, graph, labels) and the gateway configuration (Kong routes and plugins). GENIE.AI ships scripts for both.

ArangoDB backup

The backup script (components/arangodb/dump.sh) dumps every database using arangodump inside the arangodb/arangodb:3.12 container, into a timestamped directory:

/root/arango_backups/<YYYYMMDDHHMMSS>/

It requires the arango-vector-db container running on the chatqna_default network. Run it from a Swarm node that can reach the database container.

Ingestion

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

Ingestion turns a raw uploaded file into searchable, labelled, embedded chunks in ArangoDB. It runs automatically once a file is uploaded; no manual trigger is needed. The pipeline is designed so that a failure at any stage never loses the file — the upload is stored first, then processed.

The pipeline

1. Upload — file received by the document-repository service
2. Antivirus scan — ClamAV scans the file; infected files are rejected
3. Store — file saved to disk; a file_id is assigned
4. Parse — docling extracts text + structure (headings, tables)
5. Chunk — text split into retrieval-sized chunks
6. Label — each chunk labelled against the service taxonomy
7. Context prefix — (if enabled) an LLM doc-context prefix is prepended
8. Embed — each chunk vectorised with the embedding model
9. Store — chunks, embeddings, labels, and graph nodes written to ArangoDB

Steps 4–9 are owned by the dataprep service (genie-ai-overlay/dataprep/). The whole sequence is observable end-to-end — see Observability for how to watch a specific file’s ingestion in the traces and the ingestion log.

Installation & Configuration Guide

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

Introduction

Welcome to the GENIE.AI framework. This guide will walk you through the necessary steps to set up, configure, and deploy your own Retrieval-Augmented Generation (RAG) solution. The success of any AI-driven knowledge system lies in the quality and structure of its data. Therefore, the first and most critical phase is to define, curate, and structure the data that will form the backbone of your system’s knowledge. This cannot be over-emphasized. It is the most critical aspect. Our suggestion is that you establish an initial MVP with the framework by simply curating the data, defining the knowledge hierarchy, configuring your quickhelp buttons with prompts and then labeling and ingesting your curated data prior to modifying any code. This way, you will get used to how the framework operates, before you delve into deeper issues and extensions. This approach can also be used to deliver a rapid solution to a RAG problem, without any coding at all (just implementing a knowledge base design and the associated configuration). The application title and theme can also be modified by configuration in JSON without changing code. The suggested approach for this is to utilize something like ChatGPT, Gemini Pro or Grok etc. to build a new configuration for color theme and title etc. This can be done in minutes.

Keycloak Admin Guide

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

This guide explains how to manage users, roles, and groups for GENIE.AI entirely through the Keycloak admin console. No GENIE.AI-specific interface is needed for user management.

Overview

GENIE.AI delegates all identity management to Keycloak. When an administrator creates, modifies, disables, or deletes a user in Keycloak, the changes take effect in GENIE.AI on the user’s next authentication. Roles assigned in Keycloak are reflected in the JWT claims and propagated to all GENIE.AI services.

Pipeline Architecture

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

The RAG pipeline is orchestrated by the ChatQnA mega-service (genie-ai-overlay/chatqna/), a Python/FastAPI service built on the OPEA mega-service framework. It wires together five specialist microservices into a directed acyclic graph (DAG) and streams the final answer back to the client.

Service roles

Stage	Service	Stack	Role
Orchestration	ChatQnA	Python / FastAPI	Owns the DAG; calls each stage; enforces abstention and confidence.
Embedding	TEI Embedding	Hugging Face TEI	Vectorises the query (and chunks at ingest time).
Retrieval	Retriever	Python / ArangoDB	Hybrid vector + graph search over indexed chunks.
Reranking	TEI Reranker	Hugging Face TEI	Re-scores retrieved chunks by query relevance.
Generation	vLLM	vLLM (OpenAI-compatible)	Produces the grounded answer.
Translation	Translation (optional)	TranslaTron or vLLM	Translates the stream into the user’s UI language.

All services are containerised and communicate over the internal Docker network. Only the backend (BFF) and the public Nginx gateway are reachable from outside the cluster.

Project Overview

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

GENIE.AI is an open-source generative-AI framework for the public sector: a sovereign, Digital Public Good (DPG)-compliant Retrieval-Augmented Generation (RAG) platform with multilingual support. It answers questions strictly from an indexed knowledge base you control, running every model on infrastructure you own. It integrates with OPEA (Open Platform for Enterprise AI) for AI/ML services.

This page is the orientation layer — what GENIE.AI is, how it is built, and where to read deeper. Each area below has a dedicated page; this overview intentionally stays high-level.

Stack Overview

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

The observability stack has four layers: instrumentation (in the apps), collection (the OpenTelemetry Collector), storage (the Victoria trio), and presentation (Grafana).

Layer 1 — Instrumentation

Each application service initialises the OpenTelemetry SDK and emits telemetry through the standard OTLP protocol.

Service	Language	What it emits
Backend (BFF)	Node.js	Express request spans, ArangoDB query spans, custom business spans, Prometheus metrics.
OPEA services	Python	FastAPI spans, per-RAG-stage spans (retrieval, reranking, labelling…), service logs.
Kong gateway	Lua	OTel plugin forwards request traces.

Instrumentation helpers enforce a single way to create spans (so attributes and PII filtering stay consistent):

Ui Component Inventory Frontend

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

For frontend developers. A reference catalogue of the web UI components and their props.

Summary

Total Vue Components: 55
Design System Components: 12
Application Components: 43

Design System Primitives (`src/components/ds/`)

Core Primitives

Component	Description
`Button.vue`	Button primitive with variants (primary, secondary, ghost, danger)
`Card.vue`	Container card with shadow and border radius
`Input.vue`	Text input field with label, validation states, and error messaging
`Modal.vue`	Modal dialog overlay with header, body, footer slots
`Select.vue`	Dropdown select component with options
`Combobox.vue`	Auto-complete text input with dropdown suggestions
`Tabs.vue`	Tab navigation component with panels
`Pill.vue`	Small badge/tag component for status or category display
`Spinner.vue`	Loading spinner animation
`StatusTag.vue`	Status indicator with color coding (success, warning, error, info)
`StateDisplay.vue`	Empty state / error state / loading state display component
`FormGroup.vue`	Form field wrapper with label and error messaging

Layout Components

Component	Description
`App.vue`	Root application component with router-view and global providers
`NavBarComponent.vue`	Top navigation bar with user menu, language selector, logout
`SideBarComponent.vue`	Left sidebar with conversation history and navigation
`SplashScreen.vue`	Initial loading screen with logo and progress indicator

Chat Components

Component	Description
`ChatBotComponent.vue`	Main chat interface with message list and input area
`ChatFolders.vue`	Conversation folder management (create, rename, delete)
`ChatHistoryComponent.vue`	Conversation history list with search and filtering
`ChatResponseFeedbackDialog.vue`	Feedback dialog for rating chat responses (thumbs up/down)
`RightSideBarComponent.vue`	Right sidebar displaying context, documents, or service info
`WeatherPanel.vue`	Weather information display panel (contextual data)

Admin & Analytics Components

Component	Description
`AdminDashboard.vue`	Admin dashboard with system metrics and user management
`AnalyticsDashboard.vue`	Analytics dashboard with charts and usage statistics
`AnalyticsComponent.vue`	Analytics data display with filtering and date ranges
`UnifiedAnalytics.vue`	Unified analytics view combining multiple metrics

Chart Components (`src/components/charts/`)

Component	Description
`UsageTrendChart.vue`	Line chart showing query usage over time
`CategoryDistributionChart.vue`	Pie/donut chart for service category distribution
`SatisfactionGauge.vue`	Gauge chart for user satisfaction scores
`SatisfactionHeatmap.vue`	Heatmap chart for satisfaction by time/category
`TopQueriesChart.vue`	Bar chart showing most frequent queries

Authentication & User Profile

Component	Description
`CallbackView.vue`	OIDC authentication callback handler (view-level component)
`UserProfileComponent.vue`	User profile display and edit form

Settings Components

Component	Description
`SettingsComponent.vue`	Application settings panel (theme, language, preferences)
`LanguageSelector.vue`	Language selection dropdown for i18n

File Management Components

Component	Description
`FileUploadComponent.vue`	File upload widget with drag-and-drop support
`UploadFilesDialog.vue`	Dialog for uploading multiple files to the knowledge base
`AddFromLinkDialog.vue`	Dialog for adding documents via URL/link
`FileDetailsDialog.vue`	File metadata display (name, size, upload date, status)

Service & Context Components

Component	Description
`ServiceTreePanelComponent.vue`	Hierarchical tree view of service categories
`ServiceCategoryPanelComponent.vue`	Service category list/details panel

Shared UI Components

Component	Description
`ConfirmDialog.vue`	Generic confirmation dialog (confirm/cancel actions)
`ModalDialog.vue`	Generic modal dialog wrapper component
`ContextMenu.vue`	Right-click context menu with custom actions
`NotificationSystem.vue`	Toast notification system (success, error, warning messages)
`OperationResultsModal.vue`	Modal displaying results of batch operations
`LogSearchDialog.vue`	Dialog for searching through system logs
`SearchableCountryDropdown.vue`	Country selector with search functionality

Views (`src/views/`)

Component	Description
`DashboardView.vue`	Main dashboard view (router target)
`CallbackView.vue`	Authentication callback view (OIDC redirect handler)

Component Organization

src/
├── App.vue # Root component
├── views/ # Router-level views
│ ├── DashboardView.vue
│ └── CallbackView.vue
├── components/
│ ├── ds/ # Design system primitives (12)
│ ├── charts/ # Analytics chart components (5)
│ ├── [Layout] # Navigation and layout (4)
│ ├── [Chat] # Chat interface (6)
│ ├── [Admin] # Admin/analytics (4)
│ ├── [Auth] # Authentication (2)
│ ├── [Settings] # Settings (2)
│ ├── [Files] # File management (4)
│ ├── [Services] # Service navigation (2)
│ └── [Shared] # Shared UI components (6)

Notes

All components use Vue 3 Options API (not Composition API)
Design system components in src/components/ds/ are reusable primitives
Chart components use ApexCharts library (via vue3-apexcharts)
Routing via Vue Router with views in src/views/
i18n via vue-i18n with translations in /src/i18n/locales/

Ui Component Inventory Mobile

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

For mobile developers. A reference catalogue of the Flutter app widgets.

Summary

Total Dart Files: 76
UI Components: 14
Design System Components: 6
Design System Tokens: 5
Services: 12
Config: 5
i18n Locales: 13

Design System (`lib/design_system/`)

DS Components (`lib/design_system/components/`)

Component	Description
`ds_button.dart`	Button primitive with variants (primary, secondary, ghost, danger)
`ds_card.dart`	Container card with elevation and border radius
`ds_input.dart`	Text input field with label, validation states, and error messaging
`ds_modal.dart`	Modal dialog overlay with content slot
`ds_spinner.dart`	Loading spinner animation (circular progress indicator)
`ds_state_display.dart`	Empty/error/loading state display component

DS Tokens (`lib/design_system/tokens/`)

Token File	Description
`app_tokens.dart`	Global design tokens (typography, colors, spacing scale)
`color_utils.dart`	Color utilities (lighten, darken, opacity, theme mapping)
`spacing.dart`	Spacing scale constants (xs, sm, md, lg, xl)
`radii.dart`	Border radius tokens (sm, md, lg, xl, full)

DS Theme (`lib/design_system/theme/`)

File	Description
`app_theme.dart`	Material theme configuration (light/dark, color schemes)

Chat Components (`lib/components/chat/`)

Component	Description
`chatbot_component.dart`	Main chat interface with message list and input area
`right_sidebar_component.dart`	Right sidebar displaying context, documents, or service info
`chat_response_feedback_dialog.dart`	Feedback dialog for rating chat responses (thumbs up/down)
`web_file_utils.dart`	File utility functions for web platform
`stub_file_utils.dart`	File utility stubs for non-web platforms
`right_sidebar_stub.dart`	Stub implementation for right sidebar (conditional compilation)

Sidebar Components (`lib/components/sidebar/`)

Component	Description
`sidebar_component.dart`	Left sidebar with conversation history and navigation
`chat_folders_panel.dart`	Conversation folder management (create, rename, delete)
`service_tree_panel.dart`	Hierarchical tree view of service categories

Authentication Components (`lib/components/auth/`)

Component	Description
`oidc_login_screen.dart`	OIDC login screen with Keycloak authentication flow

User Components (`lib/components/user/`)

Component	Description
`user_profile_component.dart`	User profile display and edit form

Settings Components (`lib/components/settings/`)

Component	Description
`settings_component.dart`	Application settings panel (theme, language, preferences)
`about_screen.dart`	About screen with app version, license, and links

Shared Components (`lib/components/shared/`)

Component	Description
`nav_bar_component.dart`	Bottom navigation bar (mobile app navigation)
`confirm_dialog.dart`	Generic confirmation dialog (confirm/cancel actions)
`language_selector.dart`	Language selection dropdown for i18n

Application Structure (`lib/src/`)

File	Description
`app.dart`	Root app widget with router and global providers
`sample_feature/`	Sample feature code (Flutter template, may be unused)
`settings/`	Settings controller and service (legacy, may be unused)
`localization/`	App localization delegates

Services (`lib/services/`)

Authentication Services (`lib/services/auth/`)

Service	Description
`app_auth.dart`	Authentication state management and token handling
`auth_interceptor.dart`	HTTP request interceptor for auth token injection
`auth_logger.dart`	Authentication event logging
`auth_notifier.dart`	Authentication state change notifications
`auth_state.dart`	Authentication state enum and data classes
`auth_providers.dart`	Riverpod providers for auth services
`token_storage.dart`	Secure token storage (Keychain/Keystore)
`connectivity_checker.dart`	Network connectivity status checker
`network_error_classifier.dart`	Network error classification and retry logic
`insecure_http_client.dart`	HTTP client for dev environments (bypasses SSL)

Other Services (`lib/services/`)

Service	Description
`keycloak/keycloak_service.dart`	Keycloak OIDC service wrapper
`connectivity_service.dart`	Network connectivity monitoring
`notification_service.dart`	Push notification handling
`user_service.dart`	User profile and preferences service
`i18n_service.dart`	Internationalization service
`genie_ai_config.dart`	GENIE.AI configuration loader
`fallback_localizations.dart`	Fallback localization delegates
`sse_parser.dart`	Server-Sent Events (SSE) stream parser

Configuration (`lib/config/`)

File	Description
`keycloak_config.dart`	Keycloak OIDC client configuration
`dev_config.dart`	Development environment configuration
`staging_config.dart`	Staging environment configuration
`e2e_config.dart`	E2E testing configuration
`flavors/itu.dart`	ITU flavor-specific configuration
`flavors/template.dart`	Flavor configuration template

Providers (`lib/providers/`)

File	Description
`api_providers.dart`	Riverpod providers for API clients

Utilities (`lib/utils/`)

File	Description
`theme_manager.dart`	Theme switching and persistence
`chart_theme_utils.dart`	Chart theme utilities (for analytics charts)
`dialog_theme_utils.dart`	Dialog theme utilities

Internationalization (`lib/i18n/locales/`)

Supported languages (14 locales):

Docker Compose Setup

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

This guide covers local single-node deployment using docker compose up. For multi-node production deployments with Docker Swarm, see Docker Swarm Deployment Guide.

GENIE.AI uses a single dual-mode docker-compose.yaml at the project root that works with both docker compose up and docker stack deploy.

Prerequisites

Docker Engine 23+ with Compose v2 (docker compose subcommand)
NVIDIA Container Toolkit (only if using OPEA/GPU services)
Hugging Face API token (only if using OPEA/GPU services)

Architecture Overview

For the full system architecture with diagrams (C4 context/container, authentication flows, service auth matrix, token lifecycle, RAG pipeline), see Architecture Overview.

Document Lifecycle

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

Every document in the knowledge base has a lifecycle: it is uploaded, processed, made retrievable, and eventually updated or removed. Each document is tracked by a stable file_id, so its status, chunks, and graph footprint are all addressable.

States

A document moves through these states (recorded as dataprep.status):

State	Meaning
uploaded	File received and virus-scanned; stored on disk. Not yet searchable.
processing	Dataprep is parsing, chunking, labelling, and embedding.
completed	All chunks indexed; the document is retrievable.
failed	Processing failed; the document is not searchable. Check the ingestion log for the reason.

Only documents in the completed state contribute to answers. A document stuck in processing or in failed is invisible to retrieval.

External Idp Integration Guide

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

This guide explains how to connect an external identity provider (IdP) to GENIE.AI through Keycloak. Once configured, users can authenticate via the external IdP without any GENIE.AI code or configuration changes.

How It Works

GENIE.AI uses Keycloak as its sole identity boundary. When an external IdP is configured in Keycloak, the authentication flow is:

Browser -> GENIE.AI Frontend -> Keycloak Login Page
 |
 +-- [Local Credentials] -> Keycloak Token -> GENIE.AI
 |
 +-- [External IdP Button] -> External IdP Login
 |
 Keycloak Broker
 (issues own token)
 |
 Keycloak Token -> GENIE.AI

GENIE.AI always receives a standard Keycloak-issued OIDC token, regardless of which external IdP was used. The backend middleware, JIT provisioning, and frontend auth flow are completely unaware of the external IdP.

Mobile Architecture

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

For mobile developers and integrators. The Flutter app’s architecture — layers, state, and platform integration.

Overview

The Flutter mobile app (genie_ai_mobile) is a sophisticated AI chat application with OIDC authentication, multi-language support, and responsive design patterns.

1. API Layer

Service & Provider Layer

The app does not use a proxy pattern. API access is structured around Riverpod providers and a thin set of domain services:

Riverpod providers (lib/providers/api_providers.dart) — define the API calls (chat/query, feedback, user profile, analytics, admin) as providers consumed by the UI.
Domain services (lib/services/):
- user_service.dart — user profile operations.
- connectivity_service.dart — network connectivity state.
- i18n_service.dart — locale and translation orchestration.
- notification_service.dart, sse_parser.dart, genie_ai_config.dart, fallback_localizations.dart.
- auth/ and keycloak/ subdirectories — OIDC auth state, token storage, and Keycloak integration.

The flavor-specific base URL comes from the flavor config (see §2).

Mobile Deployment Guide

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

Overview

This guide walks deployment technicians through creating a new institutional deployment of the GENIE.AI mobile app. Each deployment produces a dedicated build with its own app ID, Keycloak client, backend URL, and deep link scheme — all compiled at build-time via Flutter flavors.

Target audience: Deployment technicians familiar with Flutter, Gradle, Xcode, and Docker.

Estimated time: Under a day for a single deployment.

Prerequisites

Requirement	Purpose
Flutter SDK 3.10+	Build the mobile app
Android Studio (with SDK)	Android builds, Gradle, emulator
Xcode 14+ (macOS only)	iOS builds, signing, IPA creation
Docker + Docker Compose	Run Keycloak locally for testing
Device or emulator	End-to-end validation
Access to deployment `.env`	Configure Keycloak client and redirect scheme
Keystore for Android signing	Release builds (see Step 5: Android Signing)

Step 1: Environment Variables

Add two required variables to the deployment .env file:

Retrieval

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

Retrieval is the stage that decides which chunks of the knowledge base the LLM is allowed to see. GENIE.AI does not rely on a single signal: it fuses dense-vector search with lexical (BM25) search, and can additionally walk the knowledge graph to surface related chunks. The result is high recall (semantic matches the exact-keyword search would miss) without losing precision on proper nouns, codes, and rare terms that dense models handle poorly.

Source Tree Analysis

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

For developers. A walk-through of the repository layout — use it to find where a component lives and what it depends on. Operators and content managers do not need this page.

Overview

GENIE.AI is a sovereign, DPG-compliant RAG (Retrieval-Augmented Generation) system with multilingual support. The monorepo is organized into 6 main parts:

State Management Frontend

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

For frontend developers. How the Vue 3 web app manages state — Vuex store, modules, and data flow.

Overview

The frontend application uses Vuex 4.x for centralized state management, with a modular architecture that separates concerns between authentication, chat history, and application state. The implementation follows modern Vue.js 3 patterns with namespaced modules.

Store Architecture

Main Store (`/src/store/index.js`)

export default createStore({
 modules: {
 chatHistory: chatHistoryStore,
 auth: auth
 },
 plugins: [
 // localStorage persistence plugin for chatHistory
 ]
});

Key Features:

Tracing

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

Tracing is what makes a GENIE.AI user query legible. Because every service propagates a single W3C traceparent header and every RAG stage emits a span, one user question produces one contiguous trace that can be read end-to-end in Grafana — revealing exactly where time went and which chunks were retrieved.

Trace propagation

The trace starts at the edge. Kong creates the root span and injects a traceparent header into the request. Each downstream hop reads that header, joins the trace as a child span, and re-injects the header for the next hop:

Updates

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

GENIE.AI has three kinds of update, with different blast radii. The critical thing to know is which updates force a knowledge-base re-ingestion.

The re-ingestion rule

Change	Re-ingest required?	Why
LLM (`VLLM_LLM_MODEL_ID`)	No	The LLM reads chunks at query time; it does not change stored data. Restart vLLM.
Reranker (`RERANKER_MODEL_ID`)	No	Reranking is a query-time re-score. Restart the reranker / TEI.
Translation (`VLLM_TRANSLATION_MODEL_ID`)	No	Translation is query-time. Restart the translation service.
Embedding model (`EMBEDDING_MODEL_ID`)	Yes	Existing chunk vectors are in the old model’s space. Re-ingest everything.
Labelling taxonomy	Recommended	Labels are stored on chunks at ingest time; a changed taxonomy needs re-labelling.
Chunking / dataprep logic	Yes	Chunk boundaries and content change.

Changing the embedding model is the expensive update. Plan a full re-ingest (see Knowledge base) when you change EMBEDDING_MODEL_ID. Everything else is a service restart.

Dashboards

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

Grafana dashboards are auto-provisioned from configs/grafana/provisioning/, so a deployment gets a working set of dashboards the moment the stack starts — no manual import. They are grouped into two folders.

Application folder

Operational views of the GENIE.AI services themselves.

Dashboard	What it shows
Service health	Per-service up/down, replica count, error rate, request rate. The landing view for “is anything broken?”.
Application metrics	Business and HTTP metrics: request rates, latency distributions, error rates, custom counters.
Service logs	Centralised log search across all services (VictoriaLogs). Pivot from a metric spike to the matching logs.
Trace explorer	Distributed-trace search (VictoriaTraces via the Jaeger datasource): filter by service, operation, duration, attribute.
RAG pipeline trace waterfall	A waterfall charting per-service latency across the RAG pipeline (backend, chatqna, retriever, reranker, dataprep), so the slow stage is immediately visible.

Observability folder

Health of the observability stack itself — so the monitoring does not fail silently.

Docker Swarm Setup

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

This guide covers Docker Swarm deployments (single-node and multi-node). For local single-node development with docker compose up, see Docker Compose Setup Guide.

GENIE.AI uses a single Swarm-compatible docker-compose.yaml at the project root. All services are deployed via docker stack deploy.

Prerequisites

Docker Engine 23+ on all nodes (Compose v2 support required)
NVIDIA Container Toolkit on GPU nodes
Same Docker version on all nodes (recommended)
SSH access to all nodes
Network connectivity between all nodes (ports 2377/tcp, 7946/tcp+udp, 4789/udp)

Architecture Overview

For the full system architecture with diagrams (C4 context/container, authentication flows, service auth matrix, token lifecycle, RAG pipeline), see Architecture Overview.

Integration Architecture

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

For integrators and developers. How the components fit together: service boundaries, dependencies, and the inter-service contract surface.

This document describes the integration points, communication patterns, and data flows between all components of the GENIE.AI platform.

System Overview

GENIE.AI is a monorepo consisting of 6 main parts that communicate through REST APIs, SSE (Server-Sent Events), and direct database connections:

Labelling & Taxonomy

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

Labelling is what keeps a multi-domain knowledge base from bleeding across topics. Every chunk is assigned one or more labels drawn from the service-category taxonomy, and at query time the retriever uses those labels to return only on-topic chunks. Without labels, a question about one service could pull in unrelated chunks from another.

The taxonomy

The taxonomy is the service-category hierarchy — the set of categories and services the deployment answers about. It is managed in the backend (serviceCategories, services) and is the same structure the application uses to organise its service catalogue.

Reranking

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

Retrieval hands the reranker a candidate set of chunks; the reranker’s job is to re-order them by true relevance to the query and decide how many (if any) are good enough to send to the LLM. A cross-encoder reranker is more accurate than the bi-encoder used for retrieval because it reads the query and each chunk together, but it is also slower — which is why it runs only on the small candidate set, not the whole corpus.

Scaling

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

GENIE.AI runs on Docker Swarm, so horizontal scaling is a docker service scale command. Vertical scaling — especially GPU memory — is a configuration change per service. The two are independent and solve different problems.

Horizontal scaling (replicas)

Scale a stateless service to more replicas:

docker service scale genieai_<service>=<replicas>

Services that scale well (stateless, query-time):

Service	Scales?	Notes
Backend (BFF)	Yes	Stateless behind Kong.
ChatQnA	Yes	Stateless orchestrator.
Retriever	Yes	Stateless; shares the same ArangoDB.
Reranker / TEI	Yes	Stateless.
vLLM	With care	Each replica needs its own GPU memory budget; see below.
Dataprep	Yes (ingest)	More replicas = more parallel ingestion throughput.
ArangoDB	No (single-node)	The bundled ArangoDB is single-node; do not scale it. Add resources, not replicas.

ArangoDB is the bottleneck you cannot replica your way out of. The single-node database handles the whole retrieval load. If retrieval latency climbs under load, first check the database’s resources and query performance (see the VictoriaMetrics dashboard), not the retriever count.

Theme System

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

For frontend developers. The web app’s theme system — design tokens, SCSS variables, and customisation points.

Theme System

GENIE.AI uses a CSS-native theming architecture. A single brand color drives the entire accent palette, including dark mode — no JavaScript color manipulation.

How It Works

JSON config (genie-ai-config.json)
 │
 ▼
main.js — injects base CSS variables via inline style
 │
 ▼
theme-variables.css — derives full palette using OKLch relative syntax
 │
 ▼
Components consume tokens via var(--token)

1. JSON Config

The config file (public/config/genie-ai-config.json) defines the base theme:

Alerting

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

Alerting is auto-provisioned alongside the dashboards, so a fresh deployment already watches the failures that matter most: the stack going silent, storage filling up, the log pipeline breaking, and trace export failing.

Three files under configs/grafana/provisioning/alerting/ define the setup:

File	Purpose
`alert-rules.yml`	The alert definitions (condition + for-duration).
`notification-policies.yml`	Which alerts route to which contact points, and grouping/escalation.
`contact-points.yml`	Where notifications are sent. The shipped default is a single webhook contact point; Slack/SMTP/PagerDuty are added per environment.

Built-in alert rules

The rules target the failure modes that would otherwise make the observability stack itself lie to you.

Content Guidance

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

The single biggest factor in GENIE.AI answer quality is the quality of the documents in the knowledge base. No amount of retrieval tuning fixes documents that are poorly structured, ambiguous, or full of content the parser cannot read. This page is practical guidance for the people choosing and preparing source documents.

What retrieves well

Clean, text-based documents — real text the parser can extract, not scanned images.
Clear structure — headings, sections, lists. Structure helps both chunking (cleaner chunk boundaries) and the knowledge graph.
Self-contained sections — a chunk that makes sense on its own retrieves far better than one full of “see above” or dangling pronouns.
One topic per section — focused sections produce precise labels.
Explicit language — the words a user would actually type. A document that calls it “the Programme” everywhere will not retrieve for “permit renewal”.

What retrieves poorly

Scanned / image-only PDFs — there is little or no extractable text; the chunk is near-empty. OCR these into real text first.
Table-heavy documents — most chunks become padded table rows with low information density and poor labels. This is a known, expected pattern, not a labelling bug.
Documents that are all boilerplate — headers/footers repeated on every page pollute chunks.
Enormous, undifferentiated documents — without structure, chunks are arbitrary windows of text.

Chunking

The dataprep splits parsed text into retrieval-sized chunks. You do not control chunk boundaries directly, but you influence their quality through document structure: well-headed documents chunk cleanly; wall-of-text documents chunk arbitrarily. If a specific document retrieves badly, the first fix is almost always the document’s structure, not a pipeline knob.

Development Guide

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

GENIE.AI Development Guide

This guide covers all aspects of developing GENIE.AI, a sovereign RAG system for public sector services.

Prerequisites

Global Requirements

Node.js: 22.x LTS (for all JS components)
npm: 9.x or later
Python: 3.10 or later (for AI/ML services)
Docker: 24.x or later
Docker Compose: v2.x
Git: 2.x or later

Component-Specific Requirements

Component	Requirements
Frontend	Node.js 22+, npm 9+
Backend	Node.js 22+, npm 9+
Document Repository	Node.js 22+, npm 9+
Mobile	Flutter 3.10+, Dart 3.10.8+, Android Studio / Xcode
AI/ML Services	Python 3.10+, pip, GPU (NVIDIA) for OPEA services
API Gateway	Docker, OpenSSL (for certificates)

Quick Start

1. Clone and Install Dependencies

# Clone the repository
git clone <repository-url>
cd genie-ai

# Install root dependencies
npm install

# Install component dependencies
npm install --prefix components/gov-chat-frontend
npm install --prefix components/gov-chat-backend
npm install --prefix components/document-repository
npm install --prefix components/shared/lib

2. Configure Environment

# Copy environment template
cp env .env

# Edit .env with your local values
# Required: ARANGO_PASSWORD, POSTGRES_PASSWORD, KONG_DB_PASSWORD,
# KEYCLOAK_ADMIN_PASSWORD, KEYCLOAK_CLIENT_SECRET,
# KEYCLOAK_PROXY_CLIENT_SECRET, KC_DATAPREP_CLIENT_SECRET,
# EMAIL_* (SMTP configuration)

3. Start Services

# Option 1: Core services only (no AI/ML)
docker compose up -d

# Option 2: Full stack with AI/ML services
docker compose --profile opea up -d

# Option 3: With GPU-specific configuration
docker compose --env-file .env --env-file env.t4 --profile opea up -d

4. Access Services

Frontend: http://localhost:8090 (or https://localhost via nginx)
Backend API: http://localhost:3000/api
Document Repository: http://localhost:3001/api
Keycloak Admin: https://localhost/auth/admin
API Documentation: http://localhost:3000/api-docs

Project Structure

genie-ai/
├── components/
│ ├── gov-chat-frontend/ # Vue 3 web application
│ ├── gov-chat-backend/ # Node.js/Express API
│ ├── document-repository/ # File upload/processing service
│ └── shared/lib/ # Shared utilities (logger, ArangoDB)
├── mobile/
│ └── genie_ai_mobile/ # Flutter mobile application
├── genie-ai-overlay/ # OPEA AI/ML microservices
│ ├── chatqna/ # Main chat service
│ ├── retriever/ # Hybrid vector-graph retrieval
│ ├── reranker/ # Result reranking
│ ├── dataprep/ # Document ingestion pipeline
│ └── core/ # Shared types and utilities
├── api-gateway-solution/ # Kong/NGINX configuration
├── deploy/ansible/ # Ansible deployment playbooks
├── configs/ # Configuration files (Keycloak, prompts)
├── scripts/ # Utility scripts
└── docs/ # Documentation

Environment Configuration

Environment Files

env (no extension): Template file, committed to git
.env (with dot): Local overrides, NEVER committed

Required Secrets

# Database passwords
ARANGO_PASSWORD=<strong-password>
POSTGRES_PASSWORD=<strong-password>
KONG_DB_PASSWORD=<different-strong-password>
KEYCLOAK_DB_PASSWORD=<different-strong-password>
TRANSLATION_CACHE_PASSWORD=<strong-password>

# Keycloak secrets
KEYCLOAK_ADMIN_PASSWORD=<strong-admin-password>
KEYCLOAK_CLIENT_SECRET=<generate-with-openssl-rand-base64-32>
KEYCLOAK_PROXY_CLIENT_SECRET=<generate-with-openssl-rand-base64-32>
GENIE_ADMIN_PASSWORD=<strong-password>
KC_DATAPREP_CLIENT_SECRET=<generate-with-openssl-rand-base64-32>

# Email configuration (required for user verification)
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_USER=your-email@example.com
EMAIL_PASSWORD=your-email-password
EMAIL_FROM=noreply@example.com

# Optional: AI model access
HUGGING_FACE_HUB_TOKEN=<your-huggingface-token>

Generating Secure Passwords

# Using OpenSSL
openssl rand -base64 32

# Using Python
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Component Development

Frontend (Vue 3)

Prerequisites

Node.js 22.x LTS
npm 9.x or later

Installation

cd components/gov-chat-frontend
npm install

Development Commands

# Run development server
npm run serve

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Auto-fix lint issues
npm run lint:fix

# Format code
npm run format

# Check formatting without modifying
npm run format:check

Common Development Tasks

Adding a New Component

Generation

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

Generation is the final RAG stage: the kept chunks are assembled into a prompt and sent to the LLM, which produces a grounded answer streamed back to the user. The default LLM is meta-llama/Meta-Llama-3.1-8B-Instruct (the docker-compose default). ibm-granite/granite-4.1-8b is the recommended and validated model; ibm-granite/granite-3.3-2b-instruct is the in-code fallback. All are served by vLLM (OpenAI-compatible API).

The generation behaviour is shaped by three things: the system prompt, the abstention rule, and an optional self-confidence token. Each is an environment variable with a built-in default.

GPU Deployment

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

This guide explains how to deploy GENIE.AI on different NVIDIA GPUs.

Prerequisites

NVIDIA Driver installed
NVIDIA Container Toolkit installed
Docker with NVIDIA support
Docker Swarm initialized: docker swarm init
GPU node labeled: docker node update --label-add gpu=true $(hostname)
Created .env file from env template with your secrets

Environment File Loading

Docker Swarm (docker stack deploy) does NOT support --env-file. Instead, source the files before deploying:

# CORRECT - loads both .env and GPU overrides
set -a && source .env && source env.t4 && set +a && docker stack deploy -c docker-compose.yaml genieai

# WRONG - docker stack deploy ignores --env-file
docker stack deploy --env-file .env -c docker-compose.yaml genieai

Available GPU Deployments

1. GPU T4 (16GB VRAM) - Conservative Configuration

Profile: Development and testing GPU: NVIDIA T4 (16GB VRAM)

Troubleshooting

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

This page lists the problems operators hit most often, the first place to look, and where the deeper notes live. For install-time problems, see the troubleshooting sections of the deployment guides.

General principle: trace, then logs, then code

For any “why did this answer come out wrong / slow / empty” question, the fastest path is the trace, not the logs:

Find the query’s trace in the Trace explorer.
Walk the RAG stage spans to see which stage is slow or returns nothing.
Pivot to the service logs for that stage’s error detail.

See Observability for how.

Configuration

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

The observability stack is disabled by default. Enabling it is a single environment variable, but a handful of related variables control access, retention, and sampling.

Enabling

Variable	Default	Notes
`ENABLE_OBSERVABILITY`	`0`	Must be `0` or `1` (not `true`/`false`). Swarm mode reads this to place the stack.
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://otel-collector:4318`	OTLP base URL all instrumented services export to. Override only for an external collector.

How it is enabled per deployment mode:

Docker Compose — docker compose --profile observability up -d
Docker Swarm — ENABLE_OBSERVABILITY=1 in .env
Ansible — enable_observability: "1" in group_vars/all.yml

Sampling

Variable	Default	Notes
`OTEL_TRACES_SAMPLER_RATE`	100.0	Trace sampling percentage. Lower for high-volume prod; raise when diagnosing. Metrics and logs are not sampled.
`KONG_TRACING_SAMPLING_RATE`	1.0	Kong trace sampling rate (0–1), aligned with `OTEL_TRACES_SAMPLER_RATE`.
`KONG_TRACING_INSTRUMENTATIONS`	`request`	Kong tracing instrumentations. Negligible overhead when the OTel plugin is disabled.

Retention

Each Victoria store keeps data for a configurable window; lower it to save disk, raise it for longer historical analysis.

Data Labelling Strategy

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

This repository implements a data labeling and enrichment pipeline designed to maximize the accuracy and explainability of Retrieval-Augmented Generation (RAG) systems.
Unlike conventional data labeling systems that prepare training sets for supervised learning, this process focuses on labelling document chunks for ingestion into a RAG pipeline, creating both semantic and structural signals that boost retrieval performance.

Why This Approach?

Most RAG pipelines rely solely on vector embeddings for semantic similarity. While powerful, vector-only retrieval often suffers from:

NVIDIA A40 Install Guide

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

Guide: NVIDIA Driver Installation on Ubuntu 22.04

This guide covers the process of installing the server-grade NVIDIA drivers on E2E and resolving DKMS build failures caused by manually installed kernel headers. It outlines the specific steps needed to install NVIDIA drivers for an NVIDIA A40 GPU on Ubuntu 22.04, including how to bypass the common “Exit Status 10” error caused by rogue kernel headers. This is provided to help challenge participants install and configure on the specific images provided for the challenge on E2E Neetworks with A40 GPU

Contextual Retrieval

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

Standard retrieval embeds each chunk in isolation. A chunk removed from its section can be hard to match: a paragraph about “renewing it” will not retrieve well for a query about “permit renewal” because the chunk alone does not say what “it” is. Contextual Retrieval (an Anthropic-style technique) fixes this by prepending a short, LLM-generated doc-context prefix to each chunk before it is embedded and labelled, so the chunk’s vector carries its surrounding meaning.

Choosing and Configuring Models

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

Overview

GENIE.AI uses a multi-model architecture where different AI models serve distinct purposes across the entire framework — from document ingestion and knowledge graph construction through to retrieval, reranking, and response generation. Not every model is suitable for every role. Choosing the wrong model for a given purpose will cause silent failures — ingestion batches being skipped, labels returning garbage, or graph data not being created.

This guide explains what each model does, what capabilities it must have, what license it is released under, and provides specific recommendations for both open-source and commercial models across different hardware tiers.

About GENIE.AI

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

About GENIE.AI

GENIE.AI is an open-source generative-AI framework for the public sector: a sovereign, Digital Public Good (DPG)-compliant Retrieval-Augmented Generation (RAG) platform with multilingual support. It answers questions strictly from a knowledge base you control, running every model on infrastructure you own. It integrates with OPEA (Open Platform for Enterprise AI) for AI/ML services.

Why it matters

Public-sector institutions have constraints that generic AI services cannot meet. GENIE.AI is built around them:

GENIE.AI

Api Contracts Backend

Authentication

Route Domains

1. Authentication Routes (/api/auth)

Architecture

Architecture Overview

1. System Context

Backup & Restore

ArangoDB backup

Ingestion

The pipeline

Installation & Configuration Guide

Introduction

Keycloak Admin Guide

Overview

Pipeline Architecture

Service roles

Project Overview

Stack Overview

Layer 1 — Instrumentation

Ui Component Inventory Frontend

Summary

Design System Primitives (src/components/ds/)

Core Primitives

Layout Components

Chat Components

Admin & Analytics Components

Chart Components (src/components/charts/)

Authentication & User Profile

Settings Components

File Management Components

Service & Context Components

Shared UI Components

Views (src/views/)

Component Organization

Notes

Ui Component Inventory Mobile

Summary

Design System (lib/design_system/)

DS Components (lib/design_system/components/)

DS Tokens (lib/design_system/tokens/)

DS Theme (lib/design_system/theme/)

Chat Components (lib/components/chat/)

Sidebar Components (lib/components/sidebar/)

Authentication Components (lib/components/auth/)

User Components (lib/components/user/)

Settings Components (lib/components/settings/)

Shared Components (lib/components/shared/)

Application Structure (lib/src/)

Services (lib/services/)

Authentication Services (lib/services/auth/)

Other Services (lib/services/)

Configuration (lib/config/)

Providers (lib/providers/)

Utilities (lib/utils/)

Internationalization (lib/i18n/locales/)

Docker Compose Setup

Prerequisites

Architecture Overview

Document Lifecycle

States

External Idp Integration Guide

How It Works

Mobile Architecture

Overview

1. API Layer

Service & Provider Layer

Mobile Deployment Guide

Overview

Prerequisites

Step 1: Environment Variables

Retrieval

Source Tree Analysis

Table of Contents

Overview

State Management Frontend

Overview

Store Architecture

Main Store (/src/store/index.js)

1. Authentication Routes (`/api/auth`)

Design System Primitives (`src/components/ds/`)

Chart Components (`src/components/charts/`)

Views (`src/views/`)

Design System (`lib/design_system/`)

DS Components (`lib/design_system/components/`)

DS Tokens (`lib/design_system/tokens/`)

DS Theme (`lib/design_system/theme/`)

Chat Components (`lib/components/chat/`)

Sidebar Components (`lib/components/sidebar/`)

Authentication Components (`lib/components/auth/`)

User Components (`lib/components/user/`)

Settings Components (`lib/components/settings/`)

Shared Components (`lib/components/shared/`)

Application Structure (`lib/src/`)

Services (`lib/services/`)

Authentication Services (`lib/services/auth/`)

Other Services (`lib/services/`)

Configuration (`lib/config/`)

Providers (`lib/providers/`)

Utilities (`lib/utils/`)

Internationalization (`lib/i18n/locales/`)

Main Store (`/src/store/index.js`)