doc/ARCHITECTURE.md

# 🏗️ System Architecture

LifeFlow AI implements a novel **"Dual-Brain"** architecture combined with a **Context-Offloading Protocol** to solve the scalability issues of traditional Agentic workflows. This document details the system design, data flow, and infrastructure.

## 📐 High-Level Design

The system is built on a modular microservices-like architecture using **Agno (Phidata)** for orchestration and **FastMCP** for tool isolation.

```mermaid
graph TD
    User[User Interface] -->|Gradio Websocket| App[Application Core]
    App -->|Input Analysis| Planner[📋 Planner Agent]
    
    subgraph "Core Team (State Machine)"
        Leader[👨‍✈️ Team Leader]
        Leader -->|Delegates| Scout[🗺️ Scout]
        Leader -->|Delegates| Optimizer[⚡ Optimizer]
        Leader -->|Delegates| Navigator[🧭 Navigator]
        Leader -->|Delegates| Weatherman[🌤️ Weatherman]
        Leader -->|Delegates| Presenter[📊 Presenter]
    end

    Planner -->|Task List JSON| Leader
    
    subgraph "The 'Hot Potato' Data Pipeline"
        direction LR
        DB[(POI Repository / SQLite)]
        Scout -.->|Write Raw POIs| DB
        DB -.->|Read Ref ID| Optimizer
        Optimizer -.->|Write Ordered List| DB
        DB -.->|Read Opt ID| Navigator
        Navigator -.->|Write Routes| DB
        DB -.->|Read Nav ID| Weatherman
        Weatherman -.->|Write Final Timeline| DB
    end
```

## 🚀 Key Architectural Patterns
1. Context Offloading Protocol ("Hot Potato")
Traditional agents pass massive JSON blobs (search results, reviews, coordinates) back and forth in the chat context, quickly hitting token limits and causing hallucinations.


### LifeFlow's Solution:
- Data Isolation: Agents NEVER see the full data payload.
- Reference Passing: Agents only exchange Reference IDs (e.g., scout_result_123).
- Mechanism:
  1. Scout finds 50+ locations, saves them to poi_repo, and returns {"scout_ref": "uuid"} to the Leader.
  2. Leader passes this UUID to the Optimizer.
  3. Optimizer loads data from the repo, solves the TSPTW problem, and saves the result.
  * Result: Reduces token consumption by ~75% for complex trips.

2. Exclusive MCP Channels (Tool Isolation)
In standard multi-agent setups, all tools are often dumped into a shared context, confusing the LLM (e.g., the "Optimizer" trying to use "Weather" tools).

### LifeFlow's Solution (in app.py):
We implement a custom Lifecycle Manager that spins up isolated FastMCP connections for each agent.
- Scout Agent $\leftrightarrow$ Channel A (Only search_and_offload)
- Optimizer Agent $\leftrightarrow$ Channel B (Only optimize_from_ref)
- Navigator Agent $\leftrightarrow$ Channel C (Only calculate_traffic_and_timing)
This guarantees 100% Tool Usage Accuracy and prevents agents from hallucinating tool calls.

### 🔗 The Unifying Link: Shared State via Reference IDs

While the **Execution Channels** (A, B, C) are strictly isolated to prevent tool hallucinations, they share a **Unified State Layer**.

The "Glue" connecting these isolated environments is the **Database Reference ID** (e.g., `scout_ref_uuid`).

* **Mechanism:**
    * **Channel A (Scout)** executes a search, writes the heavy JSON payload to the shared **POI Repository (DB)**, and returns *only* the ID `ref_123`.
    * The **Leader Agent** passes `ref_123` to **Channel B (Optimizer)**.
    * **Channel B** uses its tool (`optimize_from_ref`) to "hydrate" the data by reading `ref_123` from the same shared DB, processes it, and saves a new `ref_456`.

This architecture ensures that while **Tools are Private** (security & accuracy), **Data is Global** (accessibility).

```text
+-----------------------------+                  +-------------------------+
|  ⚡ EXECUTION CHANNELS      |                  |  💾 UNIFIED STORAGE     |
+-----------------------------+                  +-------------------------+

           (Write Data)                          +-------------------------+
1. [ Channel A: SCOUT ] ------------------------>|                         |
          |                                      |                         |
          | (Pass Ref ID: "ref_123")             |                         |
          v                                      |                         |
                                                 |     POI REPOSITORY      |
2. [ Channel B: OPTIMIZER ] <----(Read/Write)--->|       (SQLite)          |
          |                                      |                         |
          | (Pass Ref ID: "ref_456")             |                         |
          v                                      |                         |
                                                 |                         |
3. [ Channel C: NAVIGATOR ] <----(Read/Write)--->|                         |
                                                 +------------------------ +



```

## 🛠️ Tech Stack & Compon**ents**

| Component | Technology        | Description |
| :--- |:------------------| :--- |
| **Frontend** | Gradio 5.49.1     | Reactive UI with custom CSS, Stepper, and Map integration. |
| **Orchestration** | Agno (Phidata)    | Manages Agent state, memory, and team coordination. |
| **Tool Protocol** | FastMCP           | Exposes Python functions as standardized AI tools. |
| **Models** | Google Gemini 2.5 | **Flash** for Leader/Planner (Reasoning), **Flash-Lite** for Workers (Speed). |
| **Optimization** | Google OR-Tools   | Solves TSPTW (Traveling Salesperson Problem with Time Windows). |
| **Data Layer** | SQLite / JSON     | Local file-based repository for high-speed context offloading. |


## 🔄 Data Flow Example
1. User Input: "Plan a day in SF, visit Pier 39 and get crab."

2. Planner: Converts to structured JSON Tasks.

3. Leader: Receives Tasks → Delegates to Scout.
    > Scout: Calls Google Places API → Saves 20 candidates → Returns ref_scout.

4. Leader: Delegates to Optimizer.
    > Optimizer: Loads ref_scout → Runs OR-Tools → Returns ref_opt (Sorted).

5. Leader: Delegates to Navigator.
    > Navigator: Loads ref_opt → Calls Google Routes (Traffic) → Returns ref_nav.

6. Leader: Delegates to Weatherman.
    > Weatherman: Loads ref_nav → Checks OpenWeather → Returns ref_final.

7. Leader: Delegates to Presenter.
    > Presenter: Reads ref_final → Generates UI Report.

8. User sees a complete, optimized itinerary with maps and weather.