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.

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:

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:

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

Core & Project Overview on GENIE.AI

Project Overview

Source Tree Analysis

Table of Contents

Overview

Integration Architecture

Table of Contents

System Overview

Development Guide

GENIE.AI Development Guide

Table of Contents

Prerequisites

Global Requirements

Component-Specific Requirements

Quick Start

1. Clone and Install Dependencies

2. Configure Environment

3. Start Services

4. Access Services

Project Structure

Environment Configuration

Environment Files

Required Secrets

Generating Secure Passwords

Component Development

Frontend (Vue 3)

Prerequisites

Installation

Development Commands

Common Development Tasks