Architecture Overview

System Context (C4 Level 1)

AnyaSelf is a personal fashion assistant platform that coordinates AI reasoning, headless browser automation, and virtual try-on inference across multiple external systems.

graph TB
  subgraph Users
    U["👤 Household Members<br/>(React SPA / Mobile Browser)"]
  end

  subgraph AnyaSelf["AnyaSelf Platform"]
    GW["API Gateway<br/>:8080"]
    SERVICES["8 Microservices"]
  end

  subgraph External["External Systems"]
    VERTEX["Google Cloud<br/>Vertex AI"]
    GEMINI["Gemini Live<br/>Voice API"]
    HYPERBEAM_API["Hyperbeam<br/>Cloud Browsers"]
    OIDC["OIDC / Firebase Auth<br/>Identity Provider"]
    BRANDS["Brand E-Commerce<br/>Stores"]
    GCS["Google Cloud<br/>Storage"]
    UNSPLASH["Unsplash<br/>Photo API"]
  end

  U -- "HTTPS / WSS" --> GW
  GW --> SERVICES
  SERVICES -- "Reasoning Engine" --> VERTEX
  GW -- "WebSocket Proxy" --> GEMINI
  SERVICES -- "Ephemeral Browsers" --> HYPERBEAM_API
  GW -- "JWT Verification" --> OIDC
  SERVICES -- "DOM Automation" --> BRANDS
  SERVICES -- "Image Storage" --> GCS
  GW -- "Discover Feed" --> UNSPLASH

Container Diagram (C4 Level 2)

graph TB
  CLIENT["🖥️ client-web<br/>React + Vite + TypeScript<br/>Port: 3000"]

  subgraph Gateway["Edge Layer"]
    GW["🔐 api-gateway<br/>FastAPI · :8080<br/>Auth, Routing, Voice Proxy,<br/>Purchases, Audit Logs"]
  end

  subgraph Core["Core Services"]
    ORCH["🧠 orchestrator<br/>FastAPI · :8003<br/>Vertex AI Agent, Missions,<br/>Tool Execution Loop"]
    WARD["👗 wardrobe<br/>FastAPI · :8081<br/>Items, Outfits, Feed,<br/>Collections, Image Upload"]
    COMM["🛒 commerce<br/>FastAPI · :8002<br/>Offer Ingestion,<br/>Semantic Search, Scoring"]
    VTO_SVC["🎨 vto<br/>FastAPI · :8004<br/>Try-On Inference,<br/>Diffusion Pipeline"]
  end

  subgraph Automation["Browser Automation"]
    HB["🌐 hyperbeam-bridge<br/>FastAPI · :8006<br/>Cloud Browser Sessions,<br/>DOM Indexing, Agent Actions"]
    CP["🛍️ headless-cartprep<br/>FastAPI · :8005<br/>Cart Automation Jobs,<br/>Playwright Runner"]
  end

  subgraph Observability["Observability"]
    AA["📋 artifacts-audit<br/>FastAPI · :8007<br/>Mission Plans, Transcripts,<br/>Recordings, Audit Events"]
  end

  CLIENT -- "Bearer JWT" --> GW
  GW -- "proxy" --> ORCH
  GW -- "proxy" --> WARD
  GW -- "proxy" --> COMM
  GW -- "proxy" --> VTO_SVC
  GW -- "proxy" --> HB
  GW -- "proxy" --> CP

  ORCH -- "list_wardrobe tool" --> WARD
  ORCH -- "search_commerce tool" --> COMM
  ORCH -- "prepare_cart tool" --> CP
  ORCH -- "create_hyperbeam_session tool" --> HB
  ORCH -- "artifacts" --> AA
  GW -- "audit logs" --> AA
  HB -- "bridge events" --> ORCH
  HB -- "recordings" --> AA
  CP -- "recordings" --> AA

Agentic Data Flow

When a user interacts with the styling agent in a "Mission", the Orchestrator executes a reasoning loop, reaching out to other microservices via internal HTTP APIs (acting as "Tools" for the LLM).

sequenceDiagram
    participant C as Client
    participant GW as API Gateway
    participant O as Orchestrator / Vertex AI Agent
    participant W as Wardrobe Service
    participant CM as Commerce Service
    participant HB as Hyperbeam Bridge
    participant CP as Headless CartPrep
    participant AA as Artifacts Audit

    C->>GW: POST /households/{id}/orchestrator/missions/chat
    GW->>O: Forward JWT + Chat Payload

    rect rgb(24, 24, 27)
        Note over O,CM: Agent Tool Execution Loop
        O->>O: LLM reasoning — determine action
        O->>W: GET /items (list_wardrobe tool)
        W-->>O: Return household items
        O->>CM: POST /search (search_commerce tool)
        CM-->>O: Return scored offers
        O->>HB: POST /sessions (create_hyperbeam_session tool)
        HB-->>O: Return embed URL + session ID
        O->>CP: POST /jobs (prepare_cart tool)
        CP-->>O: Return job ID
    end

    O->>AA: POST /artifacts (persist plan + transcript)
    O-->>GW: Return Assistant Response
    GW-->>C: Stream Response + Embedded Browser URL

    opt Virtual Try-On
        C->>GW: POST /households/{id}/vto/jobs
        GW->>GW: Forward to VTO service
    end

    opt User Browser Takeover
        C->>GW: POST /.../sessions/{id}/takeover
        Note over C,HB: User controls browser, Agent paused
        C->>GW: POST /.../sessions/{id}/release
        HB->>O: Bridge event (takeover changed)
    end

Service Responsibility Matrix

Service	Port	Primary Responsibility	Data Store	External Deps
api-gateway	8080	Auth, routing, purchases, voice proxy	Firestore / in-memory	OIDC, Gemini Live, Unsplash
orchestrator	8003	AI agent, missions, tool execution	Firestore / in-memory	Vertex AI
wardrobe	8081	Items, outfits, feed, image uploads	Firestore / in-memory	GCS
commerce	8002	Offer ingestion, semantic search	Firestore / in-memory	—
vto	8004	Try-on inference pipeline	Firestore / in-memory	GPU cluster
headless-cartprep	8005	Cart automation jobs	Firestore / in-memory	Playwright
hyperbeam-bridge	8006	Cloud browser sessions, DOM indexing	Firestore / in-memory	Hyperbeam API
artifacts-audit	8007	Plans, transcripts, recordings, audit	Firestore / in-memory	—

Backend Abstraction Pattern

Every service follows a consistent hexagonal architecture pattern:

src/
├── main.py              # Uvicorn entrypoint
├── app.py               # FastAPI app factory
├── api/
│   ├── routes.py         # HTTP endpoints
│   └── dependencies.py   # FastAPI Depends (auth, request context)
├── core/
│   ├── config.py         # Pydantic Settings (env vars)
│   ├── security.py       # JWT verification
│   ├── errors.py         # Exception handlers
│   └── request_context.py
├── domain/
│   └── models.py         # Pydantic domain models + enums
├── repositories/
│   ├── types.py          # Abstract repository interface
│   ├── factory.py        # Backend selection (firestore | inmemory)
│   ├── firestore.py      # Google Firestore implementation
│   └── in_memory.py      # Dict-backed stub for local dev
└── services/
    └── *.py              # Business logic + inter-service clients

All services support dual persistence backends (PERSISTENCE_BACKEND=firestore|inmemory), allowing the entire stack to run locally without cloud credentials.