# margaretmz/ai-fashion-house architecture

> Architecture diagram of the GitHub repository margaretmz/ai-fashion-house, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/margaretmz/ai-fashion-house
- Repository: https://github.com/margaretmz/ai-fashion-house

## Overview

##### Project Type and Purpose
- Full-stack, modular multi-agent AI application for fashion design.
- Backend in Python using Google’s Agent Development Kit (ADK) to orchestrate specialized “agents.”
- Frontend in React (Vite) exposing a real-time UI over HTTP/WebSockets.
- Heavy use of Google Cloud services (Vertex AI, BigQuery, Cloud Storage) plus Generative AI models (Gemini, Imagen, Veo).

##### File Structure
- Top-level:
– CLI & Entrypoints: `main.py`, `run.sh`, `Makefile`
– Configuration: `.env` (via README), `pyproject.toml`
– Scripts: `scripts/setup_rag.sql`, `setup_rag_connection.sh`
- `src/ai_fashion_house/`: Core backend package
– `agents/`: Four domain agents (met_rag_agent, search_agent, fashion_design_agent, marketing_agent), each with its own `agent.py`, `prompts.py`, and `tools.py` or external-API modules.
– `create_rag.py`: RAG environment bootstrapper.
– `cli.py`: CLI command definitions (`start`, `setup-rag`).
– `web/`: FastAPI (or similar) web server modules (`api.py`, `app.py`, `web.py`) plus `static/` assets for serving the built React app.
– `utils/`: Helpers for ADK, GCP, image processing.
- `ui/`: React front end
– `src/contexts/WebSocketContext`: WebSocket connection for real-time agent logs/status.
– `components/`: Log viewer, artifact gallery, stepper, state viewer.
– `pages/`: Home, project overview.
– `package.json`, `vite.config.js`: Frontend build.

##### README for Architectural Insights
- Asynchronous multi-agent orchestration: each agent steps in sequence but runs independently.
- RAG pipeline uses BigQuery + GenAI embeddings + Gemini multimodal analysis.
- Marketing agent calls Imagen 4 (fashion images), Veo 3 (runway videos), Gemini for social copy.
- Web UI communicates via HTTP/WebSocket to the backend.

##### Main Components & Relationships
a. User Interface Layer (React)
– Components subscribe to WebSocket for agent progress/status.
– Sends user input (design concept) via HTTP POST to backend API.
b. Web/API Layer (FastAPI in `web/api.py`)
– Exposes REST & WebSocket endpoints.
– Receives user requests, forwards to the orchestration engine.
– Streams logs/events back to UI.
c. Orchestration Core (ADK + `cli.py`/`main.py`)
– Instantiates and coordinates agents in sequence.
– Manages shared state and data passing between agents.
d. Agents (modules under `src/ai_fashion_house/agents/`)
1. Input Analysis Agent – parses free-form user text into structured prompts.
2. met_rag_agent –
- BigQuery RAG retrieval
- Embedding generation (text-embedding-005)
- Gemini multimodal analysis
3. search_agent – Google Search Grounding for contemporary references
4. fashion_design_agent – Aggregates references into a final GenAI prompt
5. marketing_agent – Calls Imagen, Veo, and Gemini for final artifacts
e. External Services
– Google Cloud BigQuery (datasets, vector index)
– Vertex AI (embedding & caption models, Imagen, Veo)
– Cloud Storage (bucket for images/videos)
– Google Search API (for search_agent)
f. Persistence & Messaging
– BigQuery for RAG
– GCS for media storage
– (Optional) In-memory state or ephemeral local cache during orchestration

##### Architectural Patterns & Principles
- Modular, plug-and-play agents – each agent self-contained; easy to add or replace.
- Event-driven / asynchronous workflow – allows parallelism and non-blocking calls.
- Clear separation of concerns – UI, API, orchestration, agent logic, external services.
- RAG pattern for retrieval‐augmented generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer" 
        direction TB
        UI["React UI (Vite)"]:::ui
        Components["Components\n(ui/src/components/)"]:::ui
        Pages["Pages\n(ui/src/pages/)"]:::ui
        WS["WebSocketContext\n(ui/src/contexts/WebSocketContext/)"]:::ui
    end

    %% Web/API Layer
    subgraph "Web/API Layer" 
        direction TB
        API["FastAPI API Endpoints\n(api.py)"]:::api
        App["App Initialization\n(app.py)"]:::api
        WebSrv["Web Server Runner\n(web.py)"]:::api
        Static["Static Assets\n(static/)"]:::api
    end

    %% Orchestration Core & CLI
    subgraph "Orchestration Core" 
        direction TB
        Orch["Orchestrator Engine\n(ADK)"]:::core
        Main["main.py"]:::core
        CLI["CLI Definitions\n(cli.py)"]:::core
        RunSh["run.sh"]:::core
        Makefile["Makefile"]:::core
    end

    %% RAG Setup
    subgraph "RAG Environment Setup" 
        direction TB
        SetupSQL["setup_rag.sql"]:::util
        SetupConn["setup_rag_connection.sh"]:::util
        Bootstrap["create_rag.py"]:::util
    end

    %% Multi-Agent Orchestrator
    subgraph "Multi-Agent Orchestrator" 
        direction TB
        subgraph "Agents"
            direction TB
            MRA["met_rag_agent\n(BigQuery RAG + Gemini)"]:::agent
            SA["search_agent\n(Google Search)"]:::agent
            FDA["fashion_design_agent\n(Prompt Aggregation)"]:::agent
            MA["marketing_agent\n(Imagen, Veo, Gemini)"]:::agent
        end
        Utils["Utilities\n(adk_utils.py,\ngcp_utils.py,\nimage_utils.py)"]:::util
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        BigQuery["BigQuery"]:::infra
        Vertex["Vertex AI\n(Gemini, Imagen, Veo)"]:::infra
        GCS["Cloud Storage"]:::infra
        SearchAPI["Google Search API"]:::infra
    end

    %% Connections
    UI -->|HTTP POST| API
    UI -->|WebSocket| API
    API -->|Invoke| Orch
    Orch -->|orchestrates| MRA
    Orch -->|orchestrates| SA
    Orch -->|orchestrates| FDA
    Orch -->|orchestrates| MA
    MRA -->|BigQuery SQL| BigQuery
    MRA -->|Embedding & Analysis| Vertex
    SA -->|Search Calls| SearchAPI
    FDA -->|Aggregate Prompts| Vertex
    MA -->|Generate Media & Copy| Vertex
    MA -->|Store Media| GCS
    SetupSQL -->|Initialize Dataset| BigQuery
    SetupConn -->|Configure Connection| BigQuery
    Bootstrap -->|Bootstrap RAG| BigQuery
    Bootstrap -->|Bootstrap RAG| GCS

    %% Click Events
    click UI "https://github.com/margaretmz/ai-fashion-house/tree/main/ui/"
    click Components "https://github.com/margaretmz/ai-fashion-house/tree/main/ui/src/components/"
    click Pages "https://github.com/margaretmz/ai-fashion-house/tree/main/ui/src/pages/"
    click WS "https://github.com/margaretmz/ai-fashion-house/tree/main/ui/src/contexts/WebSocketContext/"
    click API "https://github.com/margaretmz/ai-fashion-house/blob/main/src/ai_fashion_house/web/api.py"
    click App "https://github.com/margaretmz/ai-fashion-house/blob/main/src/ai_fashion_house/web/app.py"
    click WebSrv "https://github.com/margaretmz/ai-fashion-house/blob/main/src/ai_fashion_house/web/web.py"
    click Static "https://github.com/margaretmz/ai-fashion-house/tree/main/src/ai_fashion_house/web/static/"
    click Main "https://github.com/margaretmz/ai-fashion-house/blob/main/main.py"
    click CLI "https://github.com/margaretmz/ai-fashion-house/blob/main/src/ai_fashion_house/cli.py"
    click RunSh "https://github.com/margaretmz/ai-fashion-house/blob/main/run.sh"
    click Makefile "https://github.com/margaretmz/ai-fashion-house/tree/main/Makefile"
    click SetupSQL "https://github.com/margaretmz/ai-fashion-house/blob/main/scripts/setup_rag.sql"
    click SetupConn "https://github.com/margaretmz/ai-fashion-house/blob/main/scripts/setup_rag_connection.sh"
    click Bootstrap "https://github.com/margaretmz/ai-fashion-house/blob/main/src/ai_fashion_house/create_rag.py"
    click MRA "https://github.com/margaretmz/ai-fashion-house/tree/main/src/ai_fashion_house/agents/met_rag_agent/"
    click SA "https://github.com/margaretmz/ai-fashion-house/tree/main/src/ai_fashion_house/agents/search_agent/"
    click FDA "https://github.com/margaretmz/ai-fashion-house/tree/main/src/ai_fashion_house/agents/fashion_design_agent/"
    click MA "https://github.com/margaretmz/ai-fashion-house/tree/main/src/ai_fashion_house/agents/marketing_agent/"

    %% Styles
    classDef ui fill:#D6EAF8,stroke:#3498DB
    classDef api fill:#D5F5E3,stroke:#27AE60
    classDef core fill:#FCF3CF,stroke:#F1C40F
    classDef agent fill:#FADBD8,stroke:#C0392B
    classDef util fill:#EAFAF1,stroke:#1ABC9C
    classDef infra fill:#F2F3F4,stroke:#BDC3C7
```
