graph TD
    Client["🖥️ Client (Mobile / Web)"]
    Main["main.py — FastAPI App"]
    
    Client --> Main

    Main --> NutritionRouter["/api/v1/nutrition"]
    Main --> ChatRouter["/api/v1/users"]
    Main --> AgentRouter["/api/v1/chat"]
    Main --> DietRouter["/api/v1/diet"]

    NutritionRouter --> NutritionServiceV2
    AgentRouter --> LangChainAgent["🤖 LangChain Agent"]
    LangChainAgent --> AgentTools["Tools: analyse_image\nanalyse_food_description"]
    AgentTools --> NutritionServiceV2
    ChatRouter --> ChatFirestore
    DietRouter --> DietService

    NutritionServiceV2 --> FoodExtractor["FoodExtractorService"]
    NutritionServiceV2 --> SearchService
    NutritionServiceV2 --> LLMProvider["LLM Provider\n(Gemini / OpenRouter)"]
    DietService --> LLMProvider
    DietService --> DietFirestoreDB["DietFirestore"]

    FoodExtractor --> LLMProvider
    SearchService --> ExaAPI["🔍 Exa / DuckDuckGo"]

    ChatFirestore --> Firestore["🔥 Firestore DB"]
    DietFirestoreDB --> Firestore

graph TD
    User["👤 User Input\n(Chat/Image)"] --> Context["📋 Context Builder\n(Preferences + Allergies + Goals)"]
    Context --> Brain["🧠 LLM Controller\n(ReAct State Graph)"]
    
    Brain --> Decision{"Is this food-related?"}
    
    Decision -- "No / Simple Q&A" --> Direct["💬 Direct Friendly Answer"]
    Decision -- "Yes / Needs Analysis" --> ToolSelection["🛠️ Tool Selection"]
    
    ToolSelection -- "Image Provided" --> ToolA["📸 analyse_image"]
    ToolSelection -- "Text Description" --> ToolB["📝 analyse_food_description"]
    
    ToolA --> Pipe["🧪 Nutrition Pipeline"]
    ToolB --> Pipe
    
    Pipe --> Observation["🔍 Tool Observation\n(Structured Nutrition Data)"]
    Observation --> Brain
    
    Brain --> Final["🎁 Final Personalized Response\n(Friendly Answer + Data)"]
    Final --> Firestore["🔥 Sync to Firestore"]

graph LR
    Dev["💻 Developer\nPush to GitHub"] --> CB["⚙️ Google Cloud Build"]

    subgraph "CI/CD Pipeline"
        CB --> Build["🐳 Docker Build\n(Dockerfile.api)"]
        Build --> AR["📦 Artifact Registry\n(Docker Image)"]
        AR --> Deploy["🚀 Cloud Run\n(Managed Serverless)"]
    end

    Deploy --> Public["🌐 Public API Endpoints\n(https://nomai-service-...)"]

    subgraph "Infrastructure"
        Firebase["🔥 Firestore\n(NoSQL DB)"]
        Secret["🔒 Secret Manager\n(API Keys)"]
    end

    Deploy -.-> Firebase
    Deploy -.-> Secret

graph LR
    A["📸 Multi-modal Input\n(Image + Prompt)"] --> B["Step 1\nFood Identification"]
    B --> C["Step 2\nWeb Grounding"]
    C --> D["Step 3\nMultimodal Synthesis"]
    D --> E["📊 Structured\nNutrition Response"]
    
    B -.- B1["Lightweight LLM identifies\nfood items & generates\nenriched search queries"]
    C -.- C1["Exa / DuckDuckGo\nfinds USDA, FDA, or\nbrand-specific data"]
    D -.- D1["Powerful Multimodal LLM\ncombines Actual Image +\nWeb Data + User Prompt"]

graph TD
    Input["📥 DietInput Payload\n(Macros + Preferences + Goals)"] --> Calc["⚖️ Target Calculator"]
    
    Calc --> Patterns["🔄 Carb Cycling Logic\n(Mon-Sun Pattern: 0, -15, -10, -15, +10, -10, +15)"]
    
    Patterns --> Loop["🔁 7-Day Generation Loop"]
    
    subgraph "Per-Day Iteration"
        DayPrompt["📝 Prompt Builder\n(Day Context + Used Foods)"] --> LLMCall["🤖 LLM Provider\n(Gemini / OpenRouter)"]
        LLMCall --> DailyClean["🧹 Data Cleaning\n(Remove concerns/alternatives)"]
        DailyClean --> Variety["🥗 Update Used Foods\n(Track variety for next days)"]
    end
    
    Loop --> DayPrompt
    Variety -- "Next Day" --> Loop
    
    Variety -- "End Loop" --> Aggregator["📊 Weekly Aggregator\n(Sum Macros & Totals)"]
    Aggregator --> Firestore["🔥 Firestore Storage\n(users/{userId}/diet/{dietId})"]
    Firestore --> Final["✅ WeeklyDietOutput\n(Sent to Client)"]

graph TD
    Pipeline["🧪 Nutrition Pipeline"] --> Router["🔍 SearchService (Router)"]
    
    Router --> Env{"SEARCH_PROVIDER\nEnv Var"}
    
    Env -- "exa" --> Exa["🚀 ExaSearchProvider"]
    Env -- "duckduckgo" --> DDG["🦆 DuckDuckGoSearchProvider"]
    
    Exa --> ExaAPI["Exa AI API\n(Authoritative / Linked Data)"]
    DDG --> DDG_Library["DDGS Library\n(Global Web Search)"]
    
    ExaAPI --> Results["📊 Normalized SearchResults\n(Title, URL, Snippet, Score)"]
    DDG_Library --> Results
    
    Results --> Pipeline

classDiagram
    class LLMProvider {
        <<abstract>>
        +generate_from_text(prompt, schema)
        +generate_from_image(prompt, image_bytes, schema)
    }
    class GeminiProvider {
        +Google Gemini API
        +Structured output support
        +Native vision capabilities
    }
    class OpenRouterProvider {
        +OpenRouter API
        +Claude, GPT, etc.
        +JSON schema validation
    }
    LLMProvider <|-- GeminiProvider
    LLMProvider <|-- OpenRouterProvider

graph TD
    Base["BaseNomAIException"]
    Base --> V["ValidationException (400)"]
    Base --> I["ImageProcessingException (400/413)"]
    Base --> N["NutritionAnalysisException (400/422)"]
    Base --> E["ExternalServiceException (502)"]
    Base --> C["ConfigurationException (503)"]
    Base --> R["RateLimitException (429)"]
    Base --> B["BusinessLogicException (400)"]