======================
Technical Architecture
======================

Technology Stack
================

The platform combines a Python AI backend, two Next.js web applications, a
React Native mobile application, and a set of data and AI services.

.. list-table::
   :header-rows: 1
   :widths: 25 25 15 35

   * - Component
     - Technology
     - Version
     - Role
   * - API backend
     - FastAPI
     - 0.109+
     - REST server and orchestration
   * - Generative AI
     - Google Gemini (via OpenRouter)
     - 2.0 Flash
     - Recommendation generation
   * - OCR
     - GLM-4.5V
     - 4.5
     - Text extraction from scanned documents
   * - Vector database
     - Qdrant
     - 1.7+
     - Semantic search
   * - Embeddings
     - Ollama ``bge-m3``
     - latest
     - Vectorization (1024 dimensions)
   * - Relational DB
     - PostgreSQL
     - 13+
     - Memory, history, and platform data
   * - Web frontend / partners
     - Next.js + React
     - 15 / 19
     - Web user interfaces
   * - Mobile app
     - React Native + Expo
     - 0.81 / SDK 54
     - Mobile user interface
   * - Language (backend)
     - Python
     - 3.10+
     - Engine development

High-Level Architecture
=======================

.. mermaid::
   :caption: Figure 2. High-level architecture — clients, API layer, AI services, and data stores.

   graph TB
       subgraph Clients["CLIENTS"]
           Web["Web Frontend<br/>(Next.js)"]
           Mobile["Mobile App<br/>(React Native / Expo)"]
           Partners["Partners Portal<br/>(Next.js)"]
       end

       subgraph Backend["BACKEND"]
           API["FastAPI<br/>REST API"]
           Engine["AI Recommendation Engine<br/>(gemini_agent)"]
           Memory["Agent Memory<br/>(connection pool v2.0)"]
       end

       subgraph AISvc["AI SERVICES"]
           Ollama["Ollama bge-m3<br/>Embeddings (1024D)"]
           Qdrant["Qdrant<br/>Vector DB"]
           Gemini["Gemini 2.0 Flash<br/>via OpenRouter"]
       end

       subgraph Data["DATA STORES"]
           PG["PostgreSQL<br/>profiles, history, audit"]
       end

       Web -->|HTTPS / JSON| API
       Mobile -->|HTTPS / JSON| API
       Partners -->|HTTPS / JSON| API
       API --> Engine
       Engine --> Ollama
       Engine --> Qdrant
       Engine --> Gemini
       Engine --> Memory
       Memory --> PG

       classDef client fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#000
       classDef backend fill:#FFF3E0,stroke:#F57C00,stroke-width:2px,color:#000
       classDef ai fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px,color:#000
       classDef data fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#000
       class Web,Mobile,Partners client
       class API,Engine,Memory backend
       class Ollama,Qdrant,Gemini ai
       class PG data

Clients (web, mobile, and partner portal) talk to the backend API over HTTPS.
The API orchestrates the AI recommendation engine, which in turn calls the
embedding service (Ollama), the vector store (Qdrant), the generative model
(Gemini via OpenRouter), and the relational database (PostgreSQL) for
persistence and history.

Domain Model
============

The core domain entities and their relationships are captured in the class
diagram below. The central entities are ``User`` / ``Beneficiary``,
``SkillProfile``, ``EconomicOpportunity`` / ``TrainingProgram``,
``Recommendation``, and ``Application``.

.. mermaid:: _diagrams/class.mmd
   :caption: Figure 3. Class diagram — main entities and relationships.

Data Flow
=========

A document or opportunity travels through the platform as follows:

#. **Document upload** (PDF, DOCX, PPTX, TXT).
#. **Text extraction** (OCR via GLM-4.5V where needed).
#. **Security classification** (:green:`GREEN` / :yellow:`YELLOW` / :red:`RED`).
#. **Intelligent chunking** (maximum 350 tokens per chunk).
#. **Vectorization** with Ollama ``bge-m3`` (1024 dimensions).
#. **Indexing** in Qdrant.
#. **Vector search** against the user query / profile.
#. **Recommendation generation** with Gemini.
#. **Persistence** to PostgreSQL.
#. **JSON response** returned to the client.

.. mermaid::
   :caption: Figure 4. Data flow — indexing pipeline and recommendation pipeline.

   flowchart LR
       subgraph Indexing["INDEXING PIPELINE"]
           direction TB
           U["Document upload<br/>(PDF/DOCX/PPTX/TXT)"] --> X["Text extraction<br/>(OCR if needed)"]
           X --> C["Security classification<br/>(GREEN/YELLOW/RED)"]
           C --> CH["Chunking<br/>(max 350 tokens)"]
           CH --> V["Vectorization<br/>(Ollama bge-m3, 1024D)"]
           V --> IDX["Index in Qdrant"]
       end

       subgraph Recommend["RECOMMENDATION PIPELINE"]
           direction TB
           Q["User profile / query"] --> S["Vector search<br/>(Qdrant)"]
           S --> G["Recommendation generation<br/>(Gemini)"]
           G --> P["Persist to PostgreSQL"]
           P --> R["JSON response to client"]
       end

       IDX -.indexed opportunities.-> S

       classDef idx fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#000
       classDef rec fill:#FFF3E0,stroke:#F57C00,stroke-width:2px,color:#000
       class U,X,C,CH,V,IDX idx
       class Q,S,G,P,R rec

Recommendation Sequence
=======================

The end-to-end sequence from beneficiary registration to external application —
covering profile creation, recommendation generation, and redirection to a
partner site — is shown below.

.. mermaid:: _diagrams/sequence-recommendation.mmd
   :caption: Figure 5. Sequence diagram — AI-powered recommendation and external redirection.

The participants are the Beneficiary, the Web/Mobile interface, the Backend API,
PostgreSQL, the AI-Powered Recommendation Engine, the Qdrant Vector DB, the ETL
pipeline, external partner sites, and the SMS / notification services.

Application Lifecycle
=====================

An external application moves through a well-defined state machine, from
``DRAFT`` to terminal states such as ``SUBMITTED``, ``UNDER_REVIEW``,
``EXPIRED``, ``WITHDRAWN``, ``ABANDONED``, or ``DELETED``.

.. mermaid:: _diagrams/state-lifecycle.mmd
   :caption: Figure 6. State diagram — application status lifecycle.