Installation & Configuration Guide

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.

For a high-level understanding of the system architecture before beginning any work, please refer to the Architecture Overview. This will give you an insight into most of the high level components and how they are assembled.

Step 1: Data Curation and Knowledge Hierarchy (Conceptual Design)

Before any data is ingested into GENIE.AI, you must first establish the scope of knowledge for your application and organize it logically. This process involves a strategic design of your knowledge core, the curation and verification of source documents, and the creation of an associated two-level labeling system that serves as the knowledge hierarchy within the framework’s user interface (i.e., the Knowledge Hierarchy displayed on the left sidebar). Ingested data is tagged with these labels, and queries can also select the same labels, which enhances RAG accuracy as we have utilized labeling as part of the hybrid-retrieval strategy for RAG at the backend.

1.1 Designing the Knowledge Core with Domain Analysis

A powerful RAG solution is built on a well-designed data model. We recommend using a conceptual Venn diagram exercise with your subject matter experts to map your information landscape before you even start. This helps you visualize the relationships between different data sets and define the boundaries of your knowledge base. It helps you to identify the specific data sets you need and to ascertain the specific relationships between these data sets.

This process involves identifying three tiers of data:

• Primary Data Sets (Core): This is the essential information that directly addresses the most critical and frequent user queries. It forms the central circles of your diagram - this totally depends on the scope of your solution. You can address as many facets of this central core set of data as required to serve the specific use case that you have in mind.
• Secondary Data Sets (Supporting): This data provides necessary context and is often required to give a more complete answer. It is the second ring of your diagram circles and it overlaps significantly with the primary set. There could also be many bubbles in this secondary tier.
• Tertiary Data Sets (Peripheral): This information is supplementary/peripheral and enhances the user’s understanding, but may not be essential for every query. It has a minor overlap with the primary and secondary sets in specific areas. The Venn diagram is your best allie to get this right up front.

Example Domain Analysis using Venn Diagrams:

1. Agriculture

• Primary: “Corn Crop Management Guide.” This is the core document farmers need.
• Secondary: “Approved Pesticides & Herbicides,” “Chemical Fertilizer Specifications,” “Soil Sample Analysis Protocols.” These are directly referenced by the crop guide.
• Tertiary: “Regional Weather Data,” “Historical Market Prices,” “Local Agricultural Equipment Suppliers.” This data provides valuable context for decision-making.

2. Government Services

• Primary: “Official Passport Application Process & Forms.”
• Secondary: “Schedule of Fees & Payment Options,” “Civil Registry Database (for birth certificate verification).”
• Tertiary: “List of Authorized Photo Studios,” “Post Office Locations & Operating Hours.”

3. Healthcare

• Primary: “Clinical Guidelines for Type 2 Diabetes Management.”
• Secondary: “Pharmaceutical Database (Metformin, Insulin dosages),” “Nutritional & Dietary Plans for Diabetics.”
• Tertiary: “Directory of Endocrinologists,” “Information on Local Support Groups,” “Recommended Fitness Routines.”

1.2 Impact on the Labeling System Design

This domain analysis directly informs the structure of your 2-level labeling system. The clear relationships and boundaries identified in the Venn diagrams translate naturally into a logical hierarchy. We suggest that you also use an AI-driven approach to assemble the labeling system design. You can use any of the common RAG tools like ChatGPT, Gemini or Grok for example to accomplish this in minutes. Once this is done, you will need to verify it with subject matter experts to ensure that it meets the needs of indexing the required data sets.

• Categories (Level 1) often emerge from the overarching themes that group your primary and secondary data sets. For example, in Agriculture, the primary set “Corn Crop Management” and secondary sets like “Pesticides” and “Fertilizers” all fall under the logical Category of Crop Management.
• Services/Topics (Level 2) are the primary, secondary, and even tertiary data sets themselves. They become the specific, actionable knowledge points within a category.

Tier-Based Design Strategy: To translate your data tiers into a functional hierarchy, apply the following strategy:

1. Primary Data MUST have dedicated labels: Every primary data set represents a core user need and must have a distinct, clear Service (Level 2) label.
2. Secondary Data usually needs dedicated labels: These should generally have their own Service (Level 2) labels, typically grouped under the same Category (Level 1) as the primary data they support.
3. Group Tertiary Data to avoid clutter: Avoid creating granular labels for every piece of tertiary data. Instead, group them into broader “Reference” or “General Information” Service labels. This prevents the hierarchy from becoming overwhelming while still making the data accessible.

AVOID USING THE SAME LABELS FOR SERVICES IN MULTIPLE CATEGORIES

Common Sense Design Principles:

• User-Centric Naming: Labels should reflect user intent, not internal organizational structures. A user looking for “Pesticides” does not care which government sub-department manages them.
• Mutually Exclusive, Collectively Exhaustive (MECE): Aim for categories that don’t overlap significantly. While documents can have multiple labels, the hierarchy itself should be clean and logical.
• Strict 2-Level Limit: GENIE.AI uses a shallow hierarchy. Do not try to force a third level by creating overly complex names (e.g., avoid Crops - Corn - Pests - Beetles; instead use Category: Crop Management, Service: Pest Control).

Applying this to the Agriculture example:

This method ensures your knowledge hierarchy is not arbitrary but is a direct reflection of how the information is interrelated, making the system more intuitive for both the AI and the end-user.

1.3 Data Curation and Verification Process

To deliver an accurate, trustworthy, and useful RAG solution, the underlying data must be meticulously curated and verified. Ingesting inaccurate, outdated, or poorly formatted data is the primary cause of poor performance and “hallucinations” in RAG systems. The GENIE.AI framework supports a wide range of file formats for the ingestion process.

Supported Formats:

• Web pages (.html, via URL links) - note that depth of crawling for web sites can be controlled as well as the language accepted.
• Documents (.pdf, .docx) - .doc HAS been removed as it is legacy and problematic (conversion to .docx or .pdf is recommended)
• Spreadsheets (.xlsx) - .xls has been removed for the same problametic legacyt reasons. You can use .xlsx sparingly. We suggest this is done sparingly as there are limitations related to multiple tabs and some of the other salient aspects of spreadsheets (such as calculations and charts etc.) that are problematic.
• Markdown (.md)
• Plain Text (.txt)

Supported Language for Ingestion

• GENIE-AI is set up to support a single language for ingestion purposes.
• The single language is configurable - our default configuration is EN.
• File uploads will be constrained to the single configured language (by language detection).
• Language detection technology is not perfect (especially with URL links)… you can always convert the required information to a supported file type.
• Translations are performed on the fly in and out of the backend by an LLM (also configurable).

Curation Best Practices:

1. Source Vetting: Always prioritize authoritative and official sources. For government services, this means official government websites and publications. For healthcare, use peer-reviewed medical journals, clinical guidelines from recognized health organizations, and regulatory bodies. You will need a team of experts to validate and curate this knowledge and it will need to be agreed and signed-off before ingestion.
2. Data Cleaning: * Standardize Terminology: Ensure consistent use of terms (e.g., “Type 2 Diabetes” vs. “T2D”).
   • Remove Duplicates & Noise: Eliminate redundant documents, boilerplate text (headers, footers, irrelevant ads), and artifacts from the conversion process.
   • Verify OCR Accuracy: When converting scanned PDFs, manually review the resulting text for Optical Character Recognition (OCR) errors, as these can introduce factual inaccuracies.
3. Logical Chunking: Ensure that data is ingested and split into semantically meaningful chunks. A chunk should ideally represent a complete idea or paragraph. A split in the middle of a sentence can cause the system to lose context.

Verification Workflow:

1. Subject Matter Expert (SME) Review: This is the most critical step. Once data is curated, it must be reviewed by experts in the relevant domain. An agronomist should verify the crop data, and a doctor should verify the healthcare guidelines. SMEs check for factual accuracy, completeness, and relevance.
2. Version Control: Your knowledge base is not static. Regulations, guidelines, and data change. Implement a system to track document versions and schedule regular reviews (e.g., annually) to update or retire outdated information. The sources for these documents should be version controlled. Note that documents can be retracted and ingested again as and when they change.
3. Establish a Feedback Loop: The GENIE.AI framework includes capabilities for users to provide feedback on responses. This user feedback is an invaluable, continuous source of verification. A process must be in place to review flagged responses, trace them back to the source document, and make corrections as needed.

By following this rigorous process of designing, curating, and verifying your data, you will build a robust and reliable knowledge base that allows GENIE.AI to perform at its full potential.

Step 2: Prerequisites

Before attempting installation, ensure your infrastructure meets the necessary requirements.

2.1 Hardware Requirements

GENIE.AI requires significant computational resources, particularly for AI model inference (LLMs, embeddings, rerankers). This is critical and the solution will potentially not even run without the required resources.

• Please refer to the T-Shirt Sizing Guide to determine the appropriate hardware for your deployment scale. Even for development and MVP work, you will need to meet the minimum requirements outlined in the small tee shirt size.

2.2 Software Prerequisites

• Ubuntu Linux 22.04: Everything has been tested on Ubuntu 22.04. It is OK to use variant Linux distributions but that is something you need to resolve.
• Docker & Docker Swarm: Required for orchestrating the containerized services. Ensure Swarm is initialized: docker swarm init.
• NVIDIA Drivers & CUDA: Required for GPU acceleration of the AI services (vLLM, TEI).
  • Follow the NVIDIA Driver Installation Guide to ensure your host is ready for GPU workloads.
• Node.js: Required for the JavaScript components

2.3 Install and Verify Docker on Every Host

Note: that the specifics of getting this done on any cloud providers Ubuntu images may differ

Most importantly… get the pre-requisites installed and check them

1. docker
2. node
3. npm

CRITICAL - pay strict attention to the prerequisites — all services deploy on a single host

1. Update and install prerequisites

sudo apt-get update

sudo apt-get install -y ca-certificates curl gnupg

2. Add Docker’s official GPG key

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg –dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

3. Set up the official Docker repository

echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/debian \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4. Install Docker Engine

(This also removes conflicting older versions like docker.io if present)

sudo apt-get update

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

5. Start and enable the Docker daemon

(Necessary if the installer fails to start it automatically)

sudo systemctl start docker

sudo systemctl enable docker

6. Grant your user standard Docker permissions

sudo usermod -aG docker $USER

newgrp docker

7. Verify Docker

docker run hello-world

2.4 Install Node.js on Every Host and Verify

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

sudo apt-get install -y nodejs

node -v

npm -v

Step 3: Base Installation

You must complete the base installation before configuring the application services. The deployment is organized in the repository as follows:

repository-root/ ├── docker-compose.yaml # Swarm-compatible deployment (single source of truth) ├── env # Configuration template (copy to .env) ├── env.t4 # GPU overrides for NVIDIA T4 (16GB VRAM) ├── env.rtx6000 # GPU overrides for RTX 6000 ADA (24GB VRAM) ├── api-gateway-solution/ │ └── new-config/ # Kong API gateway configuration ├── configs/ # Configuration files │ └── opea-config/ # OPEA service configurations ├── secrets/ssl/ # SSL/TLS certificates (NOT committed) └── genie-ai-overlay/ # OPEA microservices build overlays

Single-Node Installation

This method deploys all services onto a single host using Docker Swarm.

1. Clone the Repository

Note: if you plan to commit then you must clone the main UNICC repository at https://opensource.unicc.org/un/itu/genie-ai/ and not the replica. Also not that as a 3rd party, you may be required to checkout a specific branch - check with the administrator.

Clone the appropriate repository to your local machine:

• Public Replica: https://opensource.unicc.org/un/itu/genie-ai.git
• Internal UNICC GitLab: (Check with administrator)

git clone https://opensource.unicc.org/un/itu/genie-ai.git
cd genie-ai

2. Environment Configuration (.env)

The docker-compose.yaml file sources its configuration from an .env file located in the root of the repository (named env in the repo). You must create this file (e.g., by copying the existing env example to .env) and populate it with your specific settings.

There are 3 templates in the repository to start with:

1. env - used for default deployments (copy env .env to kickstart your config)
2. env.t4 - used for NVIDIA T4 GPU (16GB VRAM) — source after .env before deploying
3. env.rtx6000 - used for RTX 6000 ADA GPU (24GB VRAM) — source after .env before deploying

Customizing LLM Prompts

GENIE.AI uses a simple two-tier priority system for LLM prompts:

1. ENV VAR (highest): Override in .env for deployment-specific customization
2. DEFAULT (lowest): Built-in prompts in Python code (works out-of-the-box)

To customize prompts for your deployment, add the variables to your .env file:

# Example: Custom system prompt
CHATQNA_SYSTEM_PROMPT="You are a formal assistant for government inquiries..."

# Example: Disable abstention
CHATQNA_ENFORCE_ABSTENTION="false"

To change built-in defaults, edit the Python code:

• genie-ai-overlay/chatqna/genieai_chatqna.py - CHATQNA_SYSTEM_PROMPT default
• genie-ai-overlay/dataprep/genieai_dataprep_arangodb.py - LABEL_SELECTOR_SYSTEM_PROMPT default

The following tables document all variables found in the .env file, grouped by the service they configure. You can determin the appropriate configuration and use this table to determin the values that you should use. Note that you will need to create access tokens and API keys yourselves for various services. You will also need to establish email infrastructure services and configure the credentials for that. If you are starting with one of the templates, then you can largely skip the settings section other than tailoring some specifics which should be self-evident when you look at the .env file.

General & Proxy Settings
These settings control global logging and proxy configurations for environments behind corporate firewalls.

Kong (API Gateway) & Database
Configuration for the Kong API Gateway and its backing PostgreSQL database.

Frontend Service (Vue.js)
Configuration for the user-facing web application.

Backend Service (Node.js Logic)
Configuration for core logic, sessions, email, backups, and OPEA integration.

Translation & Caching
Configuration for the translation engine and Redis caching.

ArangoDB (Knowledge Base) Connection settings for the graph and vector database.

Note: All GENIE.AI services (backend, frontend, document-repository, and OPEA services) share a single ArangoDB database. The default name is genie-ai.

Document Repository & Virus Scanning
Configuration for file ingestion, storage, and security scanning.

OPEA & ChatQnA Service Orchestration These variables define the internal wiring and ports for the AI microservices.

Dataprep Configuration
Configuration for how documents are chunked and prepared for the knowledge graph.

Retriever Configuration
Configuration for the retrieval logic (hybrid search, traversals, etc.).

Retriever Overview

The retriever’s primary role is to receive a query embedding, perform a multi-stage search, and output the top K most relevant document chunks to be processed by a reranker.

The GENIE.AI retriever utilizes a hybrid strategy combining vector similarity search, metadata label filtering, and ArangoDB graph traversals to uncover contextually linked information.

1. Vector Search & Candidate Selection

These parameters define the initial “dragnet” that pulls potential matches from the database.

• RETRIEVER_ARANGO_FETCH_K (e.g., 15)

  • Logic: The number of initial candidates fetched for MMR (Maximal Marginal Relevance) or initial filtering.
  • Impact: Higher values increase “recall” (chance of finding the right doc) but also increase database latency and memory usage during the diversity sorting phase.

• RETRIEVER_ARANGO_K (e.g., 5)

  • Logic: The final count of chunks passed from the retriever to the reranker.
  • Impact: This is the primary driver of Reranker Latency. Increasing this provides more variety to the reranker but slows down total response time.

• RETRIEVER_ARANGO_SCORE_THRESHOLD (e.g., 0.5)

  • Logic: The minimum similarity score required for a chunk to be considered.
  • Impact: Controls precision. Setting this too high may result in “no results found,” while setting it too low increases “noise” that can lead to LLM hallucinations.

2. Graph Traversal Strategy

When enabled, the retriever explores relationships in ArangoDB to find relevant neighbors of the initial vector matches.

• RETRIEVER_ARANGO_TRAVERSAL_ENABLED (True/False)

  • Impact: Toggles multi-hop retrieval. When True, it adds “hidden” context but increases compute/latency.

• RETRIEVER_ARANGO_SEARCH_START This determines the strategy of traversal based on provided AQL snippets:

• RETRIEVER_ARANGO_TRAVERSAL_MAX_DEPTH (e.g., 3)

  • Impact: Limits how many “hops” the search goes. Increasing beyond 2 or 3 can cause exponential latency spikes in dense graphs.

• RETRIEVER_ARANGO_TRAVERSAL_MAX_RETURNED (e.g., 3)

  • Impact: Limits volume of related information injected into a single chunk’s context, protecting the LLM’s context window.

3. Additional Modules: Filtering & Summarization

These modules refine data before it leaves the retriever.

Labels-Based Filtering

• How it works: Applies strict AQL FILTER based on categoryLabel or serviceLabels during similarity search.
• Tuning: Using AND ensures high accuracy for domain-specific queries; OR allows broader exploration.

Summarization (SUMMARIZER_ENABLED)

• How it works: Uses an LLM to rewrite each retrieved chunk addressing user query and integrating related info via graph.
• Impact:
  • Accuracy: Dramatically improves context relevance for final answer.
  • Speed: Major bottleneck due to synchronous LLM calls per chunk, adding several seconds.

RERANKER Configuration
Configuration for the reranker logic

The Reranker

The Reranker acts as the final quality filter. It receives the top candidates from the retriever and performs a more computationally intensive “cross-encoder” analysis to re-score the relevance of each chunk against the actual user query.

Key Parameters

RERANKING_STRATEGY

Defines how the final subset of chunks is selected after reranking.

slice (default) Selects the top N chunks based on ranking score. → Controlled by RERANKER_TOP_N.

threshold Selects all chunks whose relevance score exceeds a fixed threshold. → Controlled by RERANKING_THRESHOLD.

knee_threshold Dynamically determines a cutoff point (“knee” or “elbow”) in the score distribution using the kneed algorithm. → Automatically balances recall and precision based on score drop-off.

RERANKER_TOP_N

This parameter controls the final number of high-confidence chunks sent to the LLM as context for response generation.

Increasing the value of RERANKER_TOP_N

• Improves the “Recall” for the LLM. It is more likely to capture the full answer if the information is spread across multiple documents.
• Can introduce “Context Stuffing.” If the extra chunks are only marginally relevant, they can distract the LLM or lead to “lost in the middle” phenomena, where the model ignores the most relevant data.
• Increases the time to generate a response. A larger context window requires the LLM to perform more computation during the “prefill” stage, and increased prompt size can lead to higher token costs and slower output.

Reducing the value of RERANKER_TOP_N

• Creates a higher risk of missing the answer. If reranker’s top results are very similar, or if answering requires four specific pieces of information, a low N will result in incomplete or “I don’t know” responses.
• Significantly speeds up response times. Smaller prompts allow for faster processing by the LLM and reduce memory consumption on inference servers.
• Forces the LLM to focus only on high-confidence matches, which can reduce hallucinations caused by conflicting or noisy information in lower-ranked chunks.

RERANKING_THRESHOLD

Defines the minimum relevance score required for a chunk to be included.

Increasing the value of RERANKING_THRESHOLD

• Produces fewer, higher-confidence chunks;
• Increases the risk of missing information (especially when spread across multiple chunks and mixed with other context);

Reducing the value of RERANKING_THRESHOLD

• Produces more context, potentially leading to more comprehensive responses;
• Increases noise and adds more ‘cost’ to response generation;

Crawler Configuration (implemented in the doc repo)

These variables control the specifics of how crawls are done.

AI Inference Configuration (vLLM, TEI, TextGen)
These variables control the specific AI models used for generation, guardrails, embeddings, and reranking.

Main Inference Model (vLLM)

Translation & Guardrail Model (vLLM)

Embeddings & Reranking Models (TEI)

3. Model Selection and GPU Compatibility

The GENIE.AI framework relies on four distinct AI models working in concert. Configuring these correctly in your .env file is the single most important factor for system stability and performance.

The Four Key Model Parameters:

1. VLLM_LLM_MODEL_ID: The main “brain” of the chatbot (e.g., Granite 3B). It generates the final answer based on retrieved context.
2. VLLM_TRANSLATION_MODEL_ID: A smaller, specialized model (e.g., Gemma 2B) used for guardrails and translation tasks to offload work from the main model.
3. EMBEDDING_MODEL_ID: Converts documents and queries into mathematical vectors. This determines search accuracy.
4. RERANKER_MODEL_ID: A specialized model that double-checks search results for relevance. This is the “quality control” step.

Hardware Profiles and Recommended Configurations:

Select the profile below that matches your GPU hardware to avoid “Out of Memory” (OOM) crashes or architecture incompatibility errors.

Profile A: The “Entry Level” Profile (NVIDIA Tesla T4 - 16GB VRAM)

• Status: Restricted / Legacy.
• Challenge: The T4 has limited memory (16GB) and older compute architecture (Turing). It does not support bfloat16, requiring float16 (half precision) which impacts stability.
• Recommended Configuration:
  • LLM: meta-llama/Meta-Llama-3.1-8B-Instruct (recommended: ibm-granite/granite-4.1-8b; small enough to fit alongside other services).
  • Embeddings: BAAI/bge-base-en-v1.5.
  • Reranker: cross-encoder/ms-marco-MiniLM-L-6-v2.
    • CRITICAL: Do not run BAAI/bge-reranker-v2-m3 on a T4. It uses an XLM-RoBERTa architecture that may cause compatibility issues with the T4-optimized TEI images, and its memory footprint is too large for a shared 16GB card.
  • Env Settings: Ensure VLLM_DTYPE=half and keep VLLM_MAX_MODEL_LEN at 2048.

After launching services and waiting for the service startup: the following is about how the entry level profile should look in the GPU:

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.163.01 Driver Version: 550.163.01 CUDA Version: 12.4 |
|-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 Tesla T4 Off | 00000000:01:01.0 Off | 0 |
| N/A 33C P0 26W / 70W | 14099MiB / 15360MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| 0 N/A N/A 14319 C VLLM::EngineCore 7774MiB |
| 0 N/A N/A 16411 C /usr/bin/python3 5480MiB |
| 0 N/A N/A 17763 C text-embeddings-router 370MiB |
| 0 N/A N/A 17810 C text-embeddings-router 210MiB |
| 0 N/A N/A 18355 C python 248MiB |
+-----------------------------------------------------------------------------------------+

GPU memory profile: Entry Level

Profile B: The “Enterprise” Profile (RTX 6000 Ada, L40S, A100 - 48GB+ VRAM)

• Status: Production Ready.
• Advantage: These cards support bfloat16 for higher precision and stability. 48GB allows for larger context windows and concurrent processing.
• Recommended Configuration:
  • LLM: meta-llama/Meta-Llama-3.1-8B-Instruct (default) or meta-llama/Meta-Llama-3.1-70B-Instruct-AWQ (quantized; recommended: ibm-granite/granite-4.1-8b).
  • Embeddings: BAAI/bge-base-en-v1.5 or BAAI/bge-m3.
  • Reranker: BAAI/bge-reranker-v2-m3.
  • Env Settings: Use VLLM_DTYPE=bfloat16 and enable VLLM_ATTENTION_BACKEND=FLASH_ATTN (if supported) for maximum throughput.

After launching services and waiting for the service startup: the following is about how the enterprise profile should look in the GPU:

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.95.05 Driver Version: 580.95.05 CUDA Version: 13.0 |
+-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA RTX 6000 Ada Gene... On | 00000000:00:05.0 Off | Off |
| 31% 47C P8 34W / 300W | 43359MiB / 49140MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| 0 N/A N/A 829239 C VLLM::EngineCore 33060MiB |
| 0 N/A N/A 831611 C VLLM::EngineCore 8402MiB |
| 0 N/A N/A 833589 C text-embeddings-router 540MiB |
| 0 N/A N/A 833600 C text-embeddings-router 700MiB |
| 0 N/A N/A 834222 C python 626MiB |
+-----------------------------------------------------------------------------------------+

GPU memory profile: Enterprise

4. Launch Services

Prerequisite: Download OCR Models CRITICAL Because the framework uses EasyOCR during data prep and model downloads inside containers can be slow or unreliable, you must download these files to the root of your project folder first.

wget -O craft_mlt_25k.zip https://github.com/JaidedAI/EasyOCR/releases/download/pre-v1.1.6/craft_mlt_25k.zip
wget -O english_g2.zip https://github.com/JaidedAI/EasyOCR/releases/download/v1.3/english_g2.zip

Launch Option A: Standard Launch (RTX 6000 Ada / A100 / H100 / A40) Use this command if you are running on modern Ampere or Ada generation hardware with sufficient VRAM (24GB+). This uses env.rtx6000 for GPU-specific overrides:

set -a && source .env && source env.rtx6000 && set +a && docker stack deploy -c docker-compose.yaml genieai

Launch Option B: GPU Launch (nVIDIA Tesla T4) Use this command for a Tesla T4 (16GB VRAM). This uses env.t4 for GPU-specific overrides:

• Precision: Forces dtype=half (float16)
• Memory Safety: Reduces GPU utilization and model length limits

set -a && source .env && source env.t4 && set +a && docker stack deploy -c docker-compose.yaml genieai

Important: First create your .env file and generate the required secrets:

cp env .env

Generate Required Secrets

All secrets must be set in .env before launching. There are no defaults — the services will fail to start without them.

Generate strong random values for each secret:

# Generate a random secret (use a different one for each variable)
openssl rand -base64 32

Example — set all secrets in one pass:

sed -i "s/^ARANGO_PASSWORD=.*/ARANGO_PASSWORD=$(openssl rand -base64 32)/" .env
sed -i "s/^TRANSLATION_CACHE_PASSWORD=.*/TRANSLATION_CACHE_PASSWORD=$(openssl rand -base64 32)/" .env
sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$(openssl rand -base64 32)/" .env
sed -i "s/^KONG_DB_PASSWORD=.*/KONG_DB_PASSWORD=$(openssl rand -base64 32)/" .env
sed -i "s/^KEYCLOAK_ADMIN_PASSWORD=.*/KEYCLOAK_ADMIN_PASSWORD=$(openssl rand -base64 32)/" .env
sed -i "s/^KEYCLOAK_DB_PASSWORD=.*/KEYCLOAK_DB_PASSWORD=$(openssl rand -base64 32)/" .env
sed -i "s/^KEYCLOAK_CLIENT_SECRET=.*/KEYCLOAK_CLIENT_SECRET=$(openssl rand -base64 32)/" .env

After running the commands above, review your .env to verify all values are set:

grep -E '^(ARANGO_PASSWORD|TRANSLATION_CACHE_PASSWORD|POSTGRES_PASSWORD|KONG_DB_PASSWORD|KEYCLOAK_ADMIN_PASSWORD|KEYCLOAK_DB_PASSWORD|KEYCLOAK_CLIENT_SECRET)' .env

Additional Required Configuration

The following are not secrets but must also be configured before launch:

Edit your .env to add these values:

nano .env

SSL/TLS Certificates

NGINX terminates TLS and serves the application over HTTPS. Certificates are volume-mounted from ./secrets/ssl/.

Development (auto-generated): No action needed — a self-signed certificate is generated automatically on first start. Your browser will show a security warning, which is expected.

Production (your own certificates):

1. Create the secrets directory and place your certificates:

mkdir -p secrets/ssl
cp /path/to/your/certificate.crt secrets/ssl/server.crt
cp /path/to/your/private-key.key secrets/ssl/server.key

2. Obtain a certificate from one of these sources:
   • Let’s Encrypt (free): certbot certonly --standalone -d your-domain.gov
   • Your organization’s PKI (internal CA)
   • Cloud provider: AWS ACM, GCP Certificate Manager, Azure Key Vault

Important: These files are listed in .gitignore and must never be committed. The docker-compose.yaml mounts them as volumes into the NGINX container.

set -a && source .env && set +a docker stack deploy -c docker-compose.yaml genieai

5. Initial Verification
After the containers launch, check their status. It may take several minutes for the large AI models (vLLM) to download and initialize.

# Check service status docker service ls

# Monitor the vLLM initialization (wait for “Application startup complete”) docker service logs genieai_vllm -f

⚠️ IMPORTANT: EXPECTED ERRORS
At this stage, while the containers are running, they are not yet configured. If you inspect the backend logs now, you will see errors related to missing databases (ArangoDB) and unconfigured routes (Kong). This is normal. Do NOT attempt to debug these errors yet. Proceed immediately to Step 4 to complete the necessary infrastructure configuration. The primary purpose of booting the containers now is to allow us to continur configuring Kong, NGINX and ArangoDB infrastructure. ERRORS ARE NORMAL. Do NOT attempt to debug these errors.

Proceed immediately to Step 4 to complete the necessary infrastructure configuration.

Step 4: Infrastructure Configuration

Once the base services are running (Step 3), you must configure the core infrastructure components before the system is usable.

4.1 ArangoDB Database Initialization

While the arango-vector-db service is running, the application database must be created.

1. Create the database using the ArangoDB shell inside the container (the port is not exposed in Swarm). Run the following command, replacing genie-ai with your ARANGO_DB value if different:

docker exec -it $(docker ps --filter "name=arango-vector-db" --format "{{.ID}}") arangosh --server.password "$ARANGO_PASSWORD" --javascript.execute-stdout "db._createDatabase('genie-ai')"

Alternatively, you can access the ArangoDB web interface by temporarily exposing the port:

docker service update --publish-add 8529:8529 genieai_arango-vector-db

Then open http://localhost:8529 in your browser (login with root and the password defined in your .env). Afterward, remove the port publish for security:

docker service update --publish-rm 8529:8529 genieai_arango-vector-db

2. Create the database defined in your ARANGO_DB environment variable (default: genie-ai).

Note: All services share this single database. Only one variable to configure: ARANGO_DB.

4.2 API Gateway Configuration (NGINX + Kong)

The API gateway layer consists of two components: NGINX (TLS termination, reverse proxy, security headers) and Kong (API routing, rate limiting).

4.2.1 NGINX — Fully Automated

NGINX configuration is template-based and auto-rendered at container startup via entrypoint.sh. No manual config editing is needed.

Set these variables in your root .env file:

After changing .env, redeploy the stack: docker stack deploy -c docker-compose.yaml genieai

SSL certificates are auto-generated (self-signed) in development. For production, mount your own certificates into secrets/ssl/.

4.2.2 Kong — Database Migrations (Automated)

Kong database migrations are handled automatically by the kong-migrations init container defined in docker-compose.yaml. This container runs on every deployment and performs:

• kong migrations bootstrap — on first deployment (fresh database)
• kong migrations up && finish — on subsequent deployments (existing schema)

No manual database initialization is required.

4.2.3 Kong — Routes and Plugins (Automated)

Kong routes and plugins are applied automatically via the kong-config one-shot Swarm service after the stack is deployed. No manual configuration is required. The service waits for Kong to be healthy, then applies kong_config.json via the Admin API.

Note: Kong routes persist in the Kong database across container restarts. The post-deploy script is idempotent — it is safe to re-run.

DNS cache: Kong is configured with KONG_DNS_STALE_TTL=5 by default. If you recreate a backend container and see 502 errors, wait up to 5 seconds for DNS re-resolution, or run docker exec <kong-container> kong reload for immediate flush.

See site/content/en/docs/deployment/docker-swarm-setup.md Step 9 for the post-deploy Kong configuration procedure.

4.3 Domain & Security Configuration (CSP & CORS)

When deploying GENIE.AI to a specific host domain (e.g., genie.agency.gov) or a public IP address other than localhost, you must configure the Content Security Policy (CSP) and Cross-Origin Resource Sharing (CORS) settings. Failure to do this will result in the browser blocking the application from connecting to the backend API or WebSocket services.

This configuration involves updates in two locations: the central .env file and the Nginx configuration file.

1. Update Environment Variables (.env)

The frontend and backend services rely on specific environment variables to construct their security headers. Locate the following variables in your root .env file and update them to include your target domain/IP.

Critical Formatting Note: When defining CSP sources that contain single quotes (like ‘self’), you must wrap the entire value in double quotes. Failure to do so may cause the backend configuration to strip the quotes, resulting in browser errors.

Example Configuration for genie.agency.gov:

# ========= FRONTEND SERVICE CONFIG =========

# 1. VUE_APP_CSP_CONNECT_SRC: Used by the Vue build process.
# Ensure you include both http/https for API and ws/wss for WebSockets.
VUE_APP_CSP_CONNECT_SRC="‘self’ https://genie.agency.gov wss://genie.agency.gov https://genie-ai.itu.int"

# 2. CSP_CONNECT_SRC: Used by the Node.js Backend (Helmet Middleware).
# Must match the frontend allowed sources.
CSP_CONNECT_SRC="‘self’ https://genie.agency.gov wss://genie.agency.gov https://genie-ai.itu.int"

# 3. CORS_ALLOWED_ORIGINS: A comma-separated list of origins allowed to access the backend.
CORS_ALLOWED_ORIGINS=https://genie.agency.gov,https://genie-ai.itu.int

Checklist for Variables:

• Protocols: Ensure you list wss:// (Secure WebSockets) if you are using https://. If you are testing on http://, use ws://.
• Ports: If your application runs on a non-standard port (e.g., :8443), that port must be appended to the domain in the CSP (e.g., https://genie.agency.gov:8443).
• Quoting: Verify that ‘self’ is enclosed in single quotes, and the whole string is enclosed in double quotes.
• System Prompts: These must be single line strings in the environment or docker will not like them.

2. Nginx Configuration (Auto-Rendered)

The Nginx configuration is now auto-rendered from default.conf.template at container startup using environment variables. No manual editing of nginx config files is needed.

Set CSP_CONNECT_SRC in your .env file to include your domain. The template will automatically use this value for the CSP connect-src directive.

Example .env update:

CSP_CONNECT_SRC='self' https://genie.agency.gov wss://genie.agency.gov

Then redeploy the stack to pick up the changes: set -a && source .env && set +a && docker stack deploy -c docker-compose.yaml genieai

Alternatively, to force-restart just the NGINX service: docker service update --force genieai_nginx

3. Update Frontend Configuration (No Rebuild Needed)

The frontend image is generic. It reads its configuration at runtime via window.APP_CONFIG (generated from environment variables at container startup by docker-entrypoint.sh).

If you change the CSP or Domain settings, simply update .env and redeploy — no image rebuild required:

# Update variables in .env (or edit with nano)
# Then redeploy the stack
set -a && source .env && set +a && docker stack deploy -c docker-compose.yaml genieai

The frontend container will generate /config.js with the new values on startup. If you want to force an immediate restart of the frontend service:

docker service update --force genieai_frontend

Step 5: Knowledge Base Population & User Setup

You have a choice at this juncture. Assuming you have done all your data analysis and you have a defined knowledge hierarchy, you can move forward with knowledge hierarchy configuration by script, UI or a combination of both. If you want to start with the UI then skip forward to step 6. If you decide to configure with scripts, with the infrastructure now configured, you can now instantiate the knowledge hierarchy designed in Step 1 and create the required system accounts as follows:

Method 1: Automated Script Approach (Recommended for Initial Setup)

This method is ideal for initial deployments, migrating an existing instance, or automated CI/CD workflows.

5.1 Prepare Script Environment You must source the environment configuration before running schema scripts to set necessary variables like database URLs and credentials: i.e. modify the set_env.sh script for the correct database environment

cd components/gov-chat-backend/scripts/new-schema-scripts

chmod +x set-env.sh

source set-env.sh

5.2 Create Database Schema

Use the arango-schema-creator.js script to generate the collections, indexes, and graphs.

# Ensure you are still in the new-schema-scripts directory and environment is set
npm install arangojs

node arango-schema-creator.js ./arango-schema.json

5.3 Create Initial User Accounts

You must create the default Admin and Manager accounts. These are required for the application to load correctly and for full integration with the Document Repository.

# Create the Admin account
node create-genie-ai-admin-account.js

# Create the Manager account
node create-genie-ai-manager-account.js

Note: These scripts create accounts with default credentials. It is highly recommended to change these passwords immediately after first login via the Admin Dashboard. At this point you can bounce the services and login if you want to test the config without establishing any knowledge heirarchy. The UI allows an Admin to establish the hierarchy with a GUI.

Skip to Step 6 if you like

5.4 Populate Hierarchy

Use the create-knowledge-hierarchy.js script to import your Category/Service structure.

• Note: Ensure schema validation is temporarily disabled on serviceCategories, services, and categoryServices collections if using an older schema version.

# Return to the parent scripts directory if the hierarchy file is there, or adjust the path.
cd ..
node create-knowledge-hierarchy.js –file ./my-hierarchy.json

5.5 Generate Translations

(Optional) Use create-translations.js to auto-generate labels for other supported languages. You will need to read the README.md in the scripts folder. The script supports two translation engines:

Option A: Internal Translation Service (Recommended)

Uses the built-in NLLB-200 translation model running in the GENIE.AI stack. No external API keys required.

Prerequisites:

• GENIE.AI services must be running (docker service ls to verify)
• Valid user account with login credentials

Usage:

# Navigate to the scripts directory
cd components/gov-chat-backend/scripts/new-schema-scripts

# Run the script with the internal translation engine
node create-translations.js <LANG> --translation-engine=internal

Example commands:

# Generate French translations
node create-translations.js FR --translation-engine=internal

# Generate Bengali translations
node create-translations.js BN --translation-engine=internal

# Generate Mandinka translations for Vue 3 frontend
node create-translations.js MAN --translation-engine=internal

# Generate Mandinka translations for mobile app (uses different code)
node create-translations.js MNK --translation-engine=internal

# Generate Sesotho translations
node create-translations.js ST --translation-engine=internal

Authentication: When using --translation-engine=internal, the script will prompt for:

• Username (e.g., your admin account)
• Password (entered securely, not echoed to terminal)

The script authenticates with the backend at http://localhost:3000/api/auth/login and uses the JWT token to call the internal translation service.

Supported Language Codes:

• ar - Arabic
• bn - Bengali
• de - German
• en - English (source language, cannot create translations)
• es - Spanish
• fr - French
• id - Indonesian
• man - Mandinka (Vue 3 frontend)
• mnk - Mandinka (Mobile app - both codes map to same translation)
• pt - Portuguese
• ru - Russian
• st - Sesotho
• sw - Kiswahili
• th - Thai
• zh - Chinese

Option B: Google Cloud Translation API

Uses Google Cloud Translate API. Requires Google Cloud credentials and API key.

Prerequisites:

• Google Cloud project with Translation API enabled
• Service account credentials JSON file
• Set GOOGLE_APPLICATION_CREDENTIALS environment variable

Usage:

# Navigate to the scripts directory
cd components/gov-chat-backend/scripts/new-schema-scripts

# Set your Google Cloud credentials (Linux/Mac)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"

# Run the script with Google Translate (default engine)
node create-translations.js <LANG>
# OR explicitly specify:
node create-translations.js <LANG> --translation-engine=google

Example:

# Generate French translations using Google Cloud
node create-translations.js FR --translation-engine=google

Script Behavior

• Existing Translations: If translations already exist for a language, the script will prompt to overwrite them.
• Database Storage: Language codes are stored in UPPERCASE in the database (e.g., FR, BN, MNK).
• Translation Content: Both engines translate service categories and services from English to the target language.
• Internal Service Details: The internal service uses the NLLB-200 distilled model with Dyula as a linguistic proxy for Mandinka (Mande language family).

Troubleshooting

Internal Translation Service Errors:

Google Cloud Errors:

Method 2: Manual Admin Dashboard Approach

This method is ideal for users who prefer a visual interface, or for making incremental changes after an initial setup. This can be done after you have completed Step 6 and logged into the application.

Step 6: Final Verification and Launch

After all configuration steps are complete, you must restart the services to ensure they pick up the new configurations and verify the system is healthy.

1. Restart Services: ```bash docker stack rm genieai sleep 30 set -a && source .env && set +a docker stack deploy -c docker-compose.yaml genieai

2. Verify Service Health:
   Check that all containers are running and healthy.

** WAIT FOR ALL THE SERVICES TO FINALIZE WITH ALL 5 MODELS LOADED**

watch nvidia-smi

docker service ls

Look for (healthy) replicas next to critical services like kong, postgres, vllm, and arango-vector-db. 3. Check Logs for Errors:

Inspect the logs again to ensure no new critical errors have appeared after the restart.

docker service logs genieai_backend -f

4. Initial Login:
   Access the application in your browser (e.g., https://localhost or your configured domain). Log in using the default Admin credentials created in Step 5.3:
   • Username: genie-admin
   • Password: the value of GENIE_ADMIN_PASSWORD from your .env

Step 7: Post-Launch Configuration (Manual Dashboard)

Once you have logged in as Admin, you can use the visual dashboard to manage your knowledge base.

7.1 Manage the Knowledge Hierarchy

Navigate to the Knowledge Hierarchy tab in the Admin Dashboard.

• Add Categories: Click “+ Add New Category” for top-level entries.
• Add Services: Hover over a category and click the plus icon for nested services.
• Edit/Delete: Use hover icons to modify entries.
• Translations: Use the form to add display translations for different languages.

7.2 Upload and Ingest Documents

Navigate to the Document Management tab.

1. Upload: Click “+ Upload Files” or “+ Add from Link”. Status will be “Pending”.
2. Apply Labels: Click the document, and use the “Labels” multi-select dropdown to apply relevant categories/services from your hierarchy.
3. Ingest: Click “Ingest” to trigger chunking, embedding, and storage. Status will update to “Ingested”.

Step 8: Labeling Strategies and Taxonomy Refinement

The GENIE-AI Dataprep module supports three distinct strategies for labeling document chunks during ingestion. Choosing the right strategy is critical for balancing ingestion speed, labeling accuracy, and the maturity of your Knowledge Hierarchy (Taxonomy).

The system is designed to support a Taxonomy Refinement Lifecycle, moving from discovery (using LLMs) to stable production (using Embeddings).

1. Labeling Strategy Comparison

2. Recommended Workflow: The Taxonomy Refinement Cycle

We recommend following this three-phase approach to build and mature your Knowledge Hierarchy.

Phase 1: Discovery & Gap Analysis (Current Phase)

Objective: Identify gaps in the Knowledge Hierarchy using the LLM’s reasoning capabilities.

1. Configuration: Set LABELING_STRATEGY=llm.
2. Action: Ingest a representative set of documents (e.g., 5-10 key files).
3. Review: Check the Ingestion Logs in the Admin Dashboard. Look for WARN entries stating: “LLM suggested NEW label…”.
4. Refine:
   • If the suggested label is valid (e.g., “Safari”), add it to the Knowledge Hierarchy via the Admin Dashboard.
   • If the suggested label is a synonym for an existing one (e.g., “Safaris” vs “Safari”), keep your hierarchy clean; do not add duplicates.
5. Repeat: Continue until the logs show mostly “Existing label added” messages and very few “NEW label” suggestions.

Phase 2: Production Stabilization

Objective: Speed up ingestion and ensure consistent tagging once the hierarchy is established.

1. Configuration: Switch to LABELING_STRATEGY=embedding.
2. Action: Re-ingest a document.
3. Review: Check the resulting graph or search results.
4. Tuning:
   • Too many irrelevant tags? Increase EMBEDDING_LABEL_THRESHOLD (e.g., to 0.80 or 0.85).
   • Missing obvious tags? Decrease EMBEDDING_LABEL_THRESHOLD (e.g., to 0.70 or 0.65).

Phase 3: Specialized/Strict Matching (Optional)

Objective: Enforce strict keyword presence for technical domains.

1. Configuration: Switch to LABELING_STRATEGY=bm25.
2. Usage: Only recommended if embedding is too “loose” and is tagging concepts that are semantically related but factually incorrect for your specific use case.

3. Configuration Reference

Add or modify the following variables in your .env file to control the behavior. You must force-update the dataprep service for changes to take effect: docker service update --force genieai_dataprep-arango-service

Option A: LLM Strategy (Default / Discovery)

# Discovery Mode
LABELING_STRATEGY=llm

# Optional: Tune the system prompt if the LLM hallucinates formats
# LABEL_SELECTOR_SYSTEM_PROMPT=“You are a label selector…”

Option B: Embedding Strategy (Production / Semantic)

# Semantic Match Mode
LABELING_STRATEGY=embedding

# Similarity Threshold (0.0 to 1.0)
# Start at 0.75. Increase for stricter matching.
EMBEDDING_LABEL_THRESHOLD=0.75

Option C: BM25 Strategy (Strict Keyword)

# Keyword Match Mode LABELING_STRATEGY=bm25

# Relevance Score Threshold # Start at 2.0. This is a raw score, not a percentage. BM25_LABEL_THRESHOLD=2.0

Step 9: Mobile Application Configuration

9.1 Overview

The GENIE.AI mobile application is a cross-platform Flutter application that provides users with access to the GENIE.AI chatbot functionality on Android, iOS, Web, and Desktop platforms. This section covers the configuration steps required to deploy and customize the mobile application for your specific GENIE.AI deployment.

Key Features:

• Cross-platform support (Android, iOS, Web, Desktop)
• Multi-language support (11 languages)
• Configuration-driven theming (JSON-based)
• Complete authentication flow (login, register, password reset)
• PDF export functionality
• Online/offline detection
• Material Design 3 UI

9.2 Prerequisites

Required Software

Optional Software

• Xcode (macOS only) - Required for iOS builds
• Chrome/Edge - For web development testing

IDE Setup (VS Code)

Install these extensions:

• Flutter
• Dart
• Flutter Widget Snippets

Recommended VS Code Settings (to minimize file locking on Windows):

{
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/build/**": true,
    "**/.dart_tool/**": true
  },
  "files.hotExit": "off"
}

9.3 Mobile Application Structure

The mobile application is located in the mobile/genie_ai_mobile/ directory:

mobile/genie_ai_mobile/
├── lib/
│   ├── main.dart                          # App entry point
│   ├── i18n/                              # Internationalization
│   │   └── locales/                       # Language files
│   ├── components/                        # UI Components
│   │   ├── auth/                          # Authentication screens
│   │   ├── chat/                          # Chat functionality
│   │   ├── settings/                      # Settings screens
│   │   └── shared/                        # Shared UI elements
│   ├── services/                          # Business logic & API
│   │   ├── api_service.dart               # Base API client
│   │   ├── auth_proxy.dart                # Authentication API
│   │   ├── chatbot_proxy.dart             # Chatbot API
│   │   └── genie_ai_config.dart           # Configuration loader
│   └── utils/                             # Utilities
│       └── theme_manager.dart             # Theme management
├── assets/
│   ├── config/
│   │   └── genie-ai-config.json          # App configuration
│   ├── images/                           # Images and icons
│   ├── fonts/                            # Custom fonts
│   └── FAQ.md                            # FAQ content
└── pubspec.yaml                          # Dependencies

9.4 API Configuration

Setting the Backend API Endpoint

The mobile application connects to your GENIE.AI backend API. Configure the API endpoint in lib/services/api_service.dart:

File: mobile/genie_ai_mobile/lib/services/api_service.dart

class ApiService {
  // Production API endpoint - UPDATE THIS TO YOUR BACKEND URL
  String get baseUrl => 'https://your-domain.com/api';

  // For local development:
  // String get baseUrl => 'http://localhost:3000/api';
}

Configuration Steps:

1. Open the file: mobile/genie_ai_mobile/lib/services/api_service.dart
2. Locate line 10 (approximately): String get baseUrl => 'https://genie-ai.itu.int/api';
3. Replace the URL with your actual backend API endpoint
4. Save the file

Example configurations:

// Production environment
String get baseUrl => 'https://genie-ai.your-org.com/api';

// Staging environment
String get baseUrl => 'https://staging.genie-ai.your-org.com/api';

// Local development
String get baseUrl => 'http://localhost:3000/api';

// Local network testing (use your actual IP)
String get baseUrl => 'http://192.168.1.100:3000/api';

9.5 App Configuration (genie-ai-config.json)

The mobile application uses a comprehensive JSON configuration file for theming and feature customization. This file is located at mobile/genie_ai_mobile/assets/config/genie-ai-config.json.

Configuration Structure

{
  "app": {
    "title": "Genie AI",
    "icon": {
      "type": "file",
      "value": "assets/config/genie-ai-icon-light.svg"
    }
  },
  "theme": {
    "primaryColor": "#4682B4",
    "secondaryColor": "#5F9EA0",
    "backgroundColor": "#D3E0EA",
    "textColor": "#1C2526",
    "navbar": {
      "gradientStart": "#4682B4",
      "gradientEnd": "#5F9EA0",
      "textColor": "#F0F8FF"
    }
  },
  "features": {
    "chat": {
      "welcomeMessage": "Welcome to Genie AI",
      "botName": "Genie AI",
      "quickHelp": {
        "layout": {
          "columns": 2,
          "gapX": "8px",
          "gapY": "8px",
          "childAspectRatio": 4.2
        },
        "buttons": [
          {
            "id": "just-chat",
            "category": null,
            "action": {
              "visibleText": "quickhelp.justChatUserPrompt",
              "hiddenPrompt": "quickhelp.justChatPrompt"
            },
            "appearance": {
              "label": {
                "text": "quickhelp.justChat",
                "color": "#1C2526"
              },
              "icon": {
                "value": "/config/quickhelp/just-chat.svg",
                "color": "#4682B4"
              }
            }
          }
        ]
      }
    }
  }
}

Customization Options

1. App Title and Icon

"app": {
  "title": "Your App Name",
  "icon": {
    "type": "file",
    "value": "assets/config/your-icon.svg"
  }
}

2. Theme Colors

"theme": {
  "primaryColor": "#4682B4",        // Main brand color
  "secondaryColor": "#5F9EA0",      // Accent color
  "backgroundColor": "#D3E0EA",     // Background color
  "textColor": "#1C2526",           // Primary text color
  "navbar": {
    "gradientStart": "#4682B4",     // Navbar gradient start
    "gradientEnd": "#5F9EA0",       // Navbar gradient end
    "textColor": "#F0F8FF"          // Navbar text color
  }
}

3. Chat Configuration

"features": {
  "chat": {
    "welcomeMessage": "Welcome to Your App",
    "botName": "Your Bot Name"
  }
}

4. Quick Help Buttons

Quick Help buttons provide pre-configured prompts for common tasks. Each button is associated with a category from your Knowledge Hierarchy:

"buttons": [
  {
    "id": "unique-button-id",
    "category": "1",  // Category ID from your Knowledge Hierarchy
    "action": {
      "visibleText": "quickhelp.userPrompt",
      "hiddenPrompt": "quickhelp.systemPrompt"
    },
    "appearance": {
      "label": {
        "text": "Button Label",
        "color": "#1C2526"
      },
      "icon": {
        "value": "/config/quickhelp/your-icon.svg",
        "color": "#4682B4"
      },
      "style": {
        "background": {
          "gradient": {
            "start": "#D3E0EA",
            "end": "#A3BFFA",
            "direction": "horizontal"
          }
        }
      }
    }
  }
]

Quick Help Button Configuration:

1. id: Unique identifier for the button
2. category: Category ID from your Knowledge Hierarchy (or null for general chat)
3. action.visibleText: Text displayed to users in the chat
4. action.hiddenPrompt: Actual prompt sent to the LLM
5. appearance: Visual styling (colors, icons, gradients)
6. darkMode: Optional dark mode overrides

9.6 Asset Configuration

Declaring Assets (pubspec.yaml)

All assets must be declared in mobile/genie_ai_mobile/pubspec.yaml:

flutter:
  uses-material-design: true
  generate: true

  assets:
    - assets/images/
    - assets/config/
    - assets/config/genie-ai-config.json
    - assets/config/quickhelp/
    - assets/FAQ.md
    - assets/icons/

  fonts:
    - family: Roboto
      fonts:
        - asset: assets/fonts/Roboto-Regular.ttf

Important:

• After modifying pubspec.yaml, run flutter pub get to update dependencies
• Ensure all asset files exist in the specified paths
• Icons referenced in genie-ai-config.json must be present in assets/config/quickhelp/

9.7 Building the Mobile Application

1. Install Dependencies

cd mobile/genie_ai_mobile
flutter pub get

2. Verify Flutter Setup

flutter doctor

Fix any issues reported before proceeding.

3. Running on Different Platforms

Web Development (Fastest Iteration)

flutter run -d chrome

Android Debug

# Enable USB debugging on device
flutter run

iOS Debug (macOS only)

flutter run -d iphone

4. Building for Release

Android Release Build

# Clean the project
flutter clean

# Build APK (for direct installation)
flutter build apk --no-tree-shake-icons

# Build App Bundle (for Play Store)
flutter build appbundle --no-tree-shake-icons

Output locations:

• APK: build/app/outputs/flutter-apk/app-release.apk
• AAB: build/app/outputs/bundle/release/app-release.aab

iOS Release Build (macOS only)

# Build the iOS app
flutter build ios --no-tree-shake-icons

# Open in Xcode
open ios/Runner.xcworkspace

# In Xcode:
# - Select your team
# - Update signing certificates
# - Archive the app
# - Distribute to App Store Connect

Web Build

flutter build web

9.8 Configuration Summary

9.9 Troubleshooting

Issue: Mobile app can’t connect to API

Solution:

1. Verify the API endpoint in lib/services/api_service.dart
2. Check network permissions (Android requires INTERNET permission)
3. Ensure SSL certificates are valid (development: certificate override available in main.dart)

Issue: Assets not loading

Solution:

1. Verify all assets are declared in pubspec.yaml
2. Run flutter pub get after modifying pubspec.yaml
3. Check file paths are correct (case-sensitive)

Issue: Build fails on Windows

Solution:

1. Close VS Code before building
2. Move project out of OneDrive/Dropbox folders
3. Use the PowerShell build script if available: .\build-release.ps1

Issue: Theme not loading

Solution:

1. Verify genie-ai-config.json is valid JSON
2. Check that the config file is declared in pubspec.yaml
3. Ensure the config loader is initialized in main.dart