LocalFoodAI_lanfr144/docs/architecture.md

Local Food AI - Architecture Map

This document describes the technical architecture, database schema design, AI RAG data flows, and dual-mode deployment topology for the Local Food AI clinical dietitian platform.

---

🗺️ System Component Architecture

The platform is designed around a strictly local, privacy-first microservice topology. The components integrate seamlessly to provide nutritional search, RAG-augmented clinical diet evaluations, and DevSecOps observability.

graph TD
    subgraph "Client Layer"
        User["User Browser"]
    end

    subgraph "Application & Gateway Layer"
        Nginx["Nginx Reverse Proxy\n(Port 80)"]
        Streamlit["Streamlit Web App\n(Port 8502)"]
    end

    subgraph "Intelligence & RAG Layer"
        Ollama["Ollama Engine\n(Mistral / Llama 3.2)\n(Port 11434)"]
        SearXNG["SearXNG Anonymous Search\n(Port 8080)"]
    end

    subgraph "Database & Storage Layer"
        MySQL["MySQL Database Server\n(Port 3307)"]
        Alembic["Alembic Migrations"]
    end

    subgraph "Observability & Telemetry"
        Zabbix["Zabbix Server & Web Dashboard\n(Ports 8081 / 10051)"]
        SNMP["SNMPv3 Trap Agent"]
    end

    %% Connections
    User -->|HTTP| Nginx
    Nginx -->|Proxy Pass| Streamlit
    Streamlit -->|Vector / Chat Queries| Ollama
    Streamlit -->|Fallback Search| SearXNG
    Streamlit -->|EAV & Core Queries| MySQL
    Alembic -->|Database Schema| MySQL
    Streamlit -->|Encrypted Telemetry Traps| SNMP
    SNMP -->|SNMPv3 Traps| Zabbix
    MySQL -->|Performance telemetry| Zabbix

---

💾 Database Design: Grouped Vertical Partitioning

To optimize massive dataset ingestion (~24GB OpenFoodFacts dataset) and completely bypass InnoDB row size limits while maintaining sub-second RAG response times, the database utilizes a vertically partitioned structure:

                  ┌────────────────────────────────────────┐
                  │           Unified SQL View             │
                  │              "products"                │
                  └───────────────────┬────────────────────┘
                                      │
         ┌────────────────────────────┼────────────────────────────┐
         ▼                            ▼                            ▼
┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│  products_core   │         │products_allergens│         │ products_macros  │
│ (Base Data,      │         │  (Allergens &    │         │ (Double Precision│
│ FULLTEXT index)  │         │  Ingredients)    │         │  Macros)         │
└──────────────────┘         └──────────────────┘         └──────────────────┘

1. products_core: Contains product base information (barcode, name, brand, primary category) optimized with FULLTEXT indexing.
2. products_allergens: Isolates complex ingredient list arrays and allergen keywords.
3. products_macros: Implements double-precision floats (DOUBLE) for protein, carbs, fats, and energy metrics.
4. products_vitamins: Stores micronutrient vitamin profiles.
5. products_minerals: Stores trace mineral concentrations.

[!NOTE] All application search queries, RAG data tools, and ingestion processes interact with a unified database VIEW named products which uses a series of high-performance LEFT JOIN operations across the primary key (barcode), shielding the frontend from database complexity.

---

🌐 Dual-Mode Deployment Topology

To ensure 100% resilience under network restrictions, the Local Food AI system is architected to operate under two distinct networking modes:

1. Mixed Distributed Topology (Production/Staging Mode)

Services are distributed across specialized local hypervisors and Windows subsystems using bridged networking:

• Application Node (WSL 2): Runs the Streamlit frontend and local Ollama model engine.
• Database Node (Hyper-V VM): Dedicated Ubuntu instance hosting the relational MySQL partitions at 192.168.130.170.
• Monitoring Node (VirtualBox VM): Dedicated host running Zabbix Server and receiving SNMPv3 notifications.
• Agile Scrum Tracker (Taiga): Remote agile project server at 192.168.130.161 for syncing deliverables.

2. Resilient Single-Node Local Fallback (Offline Mode)

When the remote VM host network or Taiga server is completely unreachable:

• Zero-Dependency Containers: The entire platform runs entirely locally on the notebook host via Docker Compose (docker-compose.yml).
• Automatic IP Resolution: Application configuration, Alembic, and SNMP notifications automatically adjust their endpoints to target local network interfaces (localhost / custom Docker networks) rather than unreachable remote IPs, avoiding timeout hangs or crashes.
• Dynamic Task Tracking: Agile development logs are dynamically synced into the workspace task.md and walkthrough.md artifacts to track progress until connectivity is restored.

---

Documented by Antigravity.