==================
Installation Guide
==================

This guide covers a development / staging installation of the full platform.
For production hosting, see :doc:`deployment`.

Prerequisites
=============

The AI recommendation engine requires:

* Python 3.10+
* PostgreSQL 13+
* Qdrant server 1.7+
* Ollama with the ``bge-m3:latest`` embedding model
* An OpenRouter API key (for Gemini access)
* 8 GB RAM minimum (16 GB recommended)
* 50 GB free disk for Qdrant storage

The web and mobile clients additionally require:

* Node.js 20+ and a package manager (npm / pnpm)
* For mobile builds: the Expo CLI and an Android / iOS toolchain or Expo Go

PostgreSQL
==========

.. code-block:: bash

   sudo apt update
   sudo apt install postgresql postgresql-contrib
   sudo -u postgres psql

.. code-block:: sql

   CREATE DATABASE agent_memory;
   CREATE USER oim_user WITH PASSWORD 'password';
   GRANT ALL PRIVILEGES ON DATABASE agent_memory TO oim_user;

The full platform schema (users, beneficiaries, opportunities, recommendations,
applications, audit logs, and more) can be loaded from
``OIM Postgres Data Model.sql``. See :doc:`data-model`.

Qdrant
======

.. code-block:: bash

   docker pull qdrant/qdrant
   docker run -p 6333:6333 -v ./qdrant_storage:/qdrant/storage qdrant/qdrant

Ollama
======

.. code-block:: bash

   curl -fsSL https://ollama.com/install.sh | sh
   ollama pull bge-m3:latest

AI Recommendation Engine
========================

.. code-block:: bash

   cd oim-ai-recommandation-engine-staging
   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   cp .env.example .env      # then edit values (see Configuration)
   uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Once running, the interactive Swagger UI is available at
``http://localhost:8000/docs``.

Web Frontend and Partners Portal
================================

Both web applications are Next.js projects with the same workflow:

.. code-block:: bash

   cd oim-frontend-staging          # or oim-partners-front-staging
   npm install
   cp .env.example .env.local       # set NEXT_PUBLIC_API_URL etc.
   npm run dev                      # development server on http://localhost:3000

Mobile Application
==================

.. code-block:: bash

   cd oim-mobile-main
   npm install
   # configure the API base URL in .env
   npx expo start                   # opens the Expo dev tools

Use the Expo Go app or a configured emulator to run the application. Production
builds are produced with EAS (see ``eas.json`` and :doc:`deployment`).

Docker
======

The AI engine, frontend, and partners portal each ship a ``Dockerfile`` for
containerised deployment. Build each image from its repository root, for
example:

.. code-block:: bash

   docker build -t oim/ai-engine ./oim-ai-recommandation-engine-staging
   docker build -t oim/frontend ./oim-frontend-staging
   docker build -t oim/partners ./oim-partners-front-staging