Architecture

The AI Ingredient Scanner uses a sophisticated multi-agent architecture powered by LangGraph. Specialized agents handle research, analysis, and validation while maintaining quality through automated retry loops.

System Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              FRONTEND LAYER                                  │
│  ┌─────────────────────┐            ┌─────────────────────────────────────┐ │
│  │   Streamlit Web UI  │            │   React Native Mobile (Expo)        │ │
│  │   :8501             │            │   Camera • OCR • Firebase Auth      │ │
│  └──────────┬──────────┘            └──────────────────┬──────────────────┘ │
└─────────────┼──────────────────────────────────────────┼────────────────────┘
              │                                          │
              ▼                                          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              BACKEND LAYER                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         FastAPI REST API (:8000)                     │   │
│  │                    POST /ocr  •  POST /analyze                       │   │
│  └────────────────────────────────────┬────────────────────────────────┘   │
│                                       │                                     │
│  ┌────────────────────────────────────▼────────────────────────────────┐   │
│  │                      LangGraph Workflow Engine                       │   │
│  │  ┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐  │   │
│  │  │ Supervisor │ → │  Research  │ → │  Analysis  │ → │   Critic   │  │   │
│  │  │   Agent    │   │   Agent    │   │   Agent    │   │   Agent    │  │   │
│  │  └────────────┘   └─────┬──────┘   └────────────┘   └─────┬──────┘  │   │
│  │                         │                                  │         │   │
│  │                         ▼                                  ▼         │   │
│  │              ┌──────────────────┐              ┌──────────────────┐  │   │
│  │              │ Parallel Lookup  │              │  5-Gate Validate │  │   │
│  │              │ (3 workers)      │              │  APPROVED/REJECT │  │   │
│  │              └──────────────────┘              └──────────────────┘  │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              ▼                    ▼                    ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   Qdrant Cloud   │  │   Redis Cloud    │  │   LangSmith      │
│   Vector Search  │  │   Session Cache  │  │   Observability  │
└──────────────────┘  └──────────────────┘  └──────────────────┘
              │
              ▼
┌──────────────────────────────────────────────────────────────┐
│                    AI SERVICES                                │
│  ┌─────────────────────┐    ┌─────────────────────────────┐  │
│  │ Gemini 2.0 Flash    │    │ Google Search Grounding     │  │
│  │ Analysis + OCR      │    │ Real-time web fallback      │  │
│  └─────────────────────┘    └─────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

Multi-Agent Workflow

The workflow orchestrates four specialized agents in sequence, with the Supervisor managing routing and retry logic.

Agent Responsibilities

🎯Supervisor Agent

Workflow orchestrator that determines which agent processes next based on current state.

Routes to Research if ingredient data is missing
Routes to Analysis if report needs generation
Routes to Critic for quality validation
Handles retry logic (max 2 attempts)

🔬Research Agent

Fetches ingredient safety data from multiple sources with parallel processing.

Parallel Processing: Handles 3+ ingredients concurrently
Dual-Source Strategy: Qdrant first, Google Search fallback
Confidence Threshold: 0.7 minimum for Qdrant results
Auto-Learning: Saves search results back to Qdrant

📊Analysis Agent

Generates personalized safety reports using Gemini 2.0 Flash.

Personalization: Considers allergies, skin type, expertise level
Output: Verdict, summary, warnings, recommendations, ingredient table
Modes: Beginner (simple) vs Expert (technical) explanations

✅Critic Agent

Validates report quality using a 5-gate validation system.

Gate	Check	Criteria
1. Completeness	All ingredients addressed	8/9 ingredients = PASS
2. Format	Markdown structure	Valid table exists
3. Allergen Match	User allergies flagged	Matching highlighted
4. Consistency	Ratings match concerns	Ratings 1-10 valid
5. Tone	Appropriate for expertise	Readable, informative

Validation Outcomes

APPROVED

All gates pass → deliver report

REJECTED

Critical failures → retry (max 2)

ESCALATED

Max retries → deliver with warning

State Management

The workflow uses a typed state dictionary to maintain context across agents:

class WorkflowState(TypedDict):
    session_id: str
    product_name: str
    raw_ingredients: list[str]
    user_profile: UserProfile
    ingredient_data: list[IngredientData]
    analysis_report: AnalysisReport | None
    critic_feedback: CriticFeedback | None
    retry_count: int
    routing_history: list[str]
    stage_timings: StageTiming
    error: str | None

Research Data Schema

Each ingredient lookup returns structured safety data:

Field	Type	Description
safety_rating	int (1-10)	Safety score (10 = safest)
concerns	string	Known safety issues
recommendation	enum	SAFE / CAUTION / AVOID
allergy_risk_flag	enum	HIGH / LOW
origin	string	Natural / Synthetic
regulatory_status	string	US FDA and EU status

Technology Stack

Core AI

Technology	Purpose	Details
Google Gemini 2.0 Flash	LLM	Analysis, validation, translation, OCR
LangGraph	Orchestration	Multi-agent workflow management
LangSmith	Tracing	LLM call logging and debugging

Backend

Technology	Purpose	Details
Python 3.11+	Language	Type hints, async support
FastAPI	REST API	Mobile app integration
Streamlit	Web UI	Interactive dashboard
Pydantic	Validation	Request/response schemas

Data Layer

Technology	Purpose	Details
Qdrant Cloud	Vector DB	Semantic ingredient search
Redis Cloud	Caching	Session persistence (24h TTL)
Google Embeddings	Vectors	gemini-embedding-001 model

Mobile

Technology	Purpose	Details
React Native	Framework	Cross-platform mobile
Expo	Toolchain	Development and builds
TypeScript	Language	Type-safe mobile code
Firebase Auth	Authentication	Google Sign-In
Firestore	Database	User profiles & settings

Performance Characteristics

3-5s

Research Time

5-8s

Analysis Time

2-3s

Critic Time

10-15s

Total (First Run)

Caching Strategy

Qdrant: Ingredient data persisted permanently
Redis: Session state cached for 24 hours
LRU Cache: In-memory settings caching

Parallel Processing

# Research agent processes 3 ingredients per worker
BATCH_SIZE = 3

with ThreadPoolExecutor(max_workers=num_workers) as executor:
    futures = {
        executor.submit(_research_batch, idx, batch): idx
        for idx, batch in enumerate(batches)
    }

Deployment Options

Environment	Stack
Local Development	Streamlit + uvicorn
Production API	Railway
Production Web	Cloudflare Pages
Mobile Testing	Expo Go
Production Mobile	EAS Build