# badrisnarayanan/antigravity-claude-proxy architecture

> Architecture diagram of the GitHub repository badrisnarayanan/antigravity-claude-proxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/badrisnarayanan/antigravity-claude-proxy
- Repository: https://github.com/badrisnarayanan/antigravity-claude-proxy

## Overview

##### Project Type and Purpose
- This is a full-stack, monolithic Node.js application that acts as an **Anthropic-compatible proxy server**. It exposes an Anthropic-style API (used by Claude Code CLI, OpenClaw, ClawdBot) and translates requests/responses to/from Google Generative AI via Antigravity Cloud Code. It also provides a browser-based Web UI and a CLI for account management.

##### Key Architectural Layers & Components
a. **Clients**
- **Web UI** (public/…): Static HTML/CSS/JS single-page app serving the dashboard, account manager, logs viewer, settings, etc.
- **CLI** (bin/cli.js + src/cli/…): Command-line interface for headless account linking and status queries.
b. **Backend Server** (src/server.js + src/index.js)
- **HTTP/API Layer**: Express (or similar) routes under `/api/*` that handle incoming Anthropic-format requests, account management endpoints, health checks, quota queries.
- **Authentication** (src/auth/…): OAuth token management, token extraction, optional manual‐paste flow.
- **Account Manager** (src/account-manager/…):
- Storage of linked Google accounts (local DB via storage.js).
- Strategy pattern implementations (round-robin, sticky, hybrid) with health/quota trackers for load balancing across multiple accounts.
- **Cloud Code Bridge** (src/cloudcode/…):
- Wraps Google Generative AI requests inside Antigravity Cloud Code API calls.
- Handles SSE streaming parsing and re-emits streaming Anthropic-style events.
- **Formatter** (src/format/…): Converts message payloads between Anthropic API schema and Google Generative AI schema; signature caching, schema sanitization, thinking utilities.
- **Modules** (src/modules/usage-stats.js, etc.): Stats collection, preset loading, helper utilities.
- **Configuration & Constants** (src/config.js, src/constants.js, fallback-config.js): Merges config.json, environment variables, default fallbacks.
- **Logging & Error Handling** (src/utils/logger.js, error-handler utils).

##### External Dependencies / Services
- **Antigravity Cloud Code API** (daily-cloudcode-pa​.sandbox​.googleapis​.com) – endpoint for actual Generative AI calls.
- **Google OAuth Servers** – for user account authorization.
- **Local Storage** – file-based or in-memory store for account credentials.

##### Data Flows & Interactions
1. **Client Request**:
- Web UI or CLI → HTTP POST `/api/v1/chat/completions` (Anthropic format).
2. **Server Processing**:
- Authentication middleware extracts or refreshes OAuth tokens.
- Account Manager selects a Google account based on strategy.
- Formatter converts Anthropic messages → Google Gen AI payload.
- Cloud Code Bridge wraps payload and issues HTTPS call to Antigravity Cloud Code API.
- SSE parser de-chunks streaming responses.
- Formatter converts Google responses → Anthropic message stream.
3. **Server Response**:
- Streams back to client in real time.

##### Architectural Patterns & Principles
- **Layered Architecture**: Clear separation between API layer, business logic (account-manager, format, cloudcode), and utility modules.
- **Strategy Pattern**: Pluggable load-balancing strategies for multi-account rotation.
- **Adapter/Facade**: `format` and `cloudcode` modules adapt between two incompatible APIs (Anthropic ↔ Google Gen AI).
- **Single Responsibility**: Each folder under `src/` has a distinct concern (auth, cli, cloudcode, format, account-manager, webui).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    WebUI["Web UI<br/>(Static SPA)"]:::frontend
    CLI["CLI Client"]:::frontend

    %% Proxy Server
    subgraph "Proxy Server" 
        direction TB
        HTTPAPI["HTTP/API Layer<br/>(src/server.js & src/index.js)"]:::core
        Auth["Authentication Module<br/>(src/auth/)"]:::core
        AM["Account Manager<br/>(src/account-manager/)"]:::core
        Strategies["Account Manager Strategies<br/>(src/account-manager/strategies/)"]:::core
        Trackers["Account Manager Trackers<br/>(src/account-manager/strategies/trackers/)"]:::core
        Formatter["Formatter<br/>(src/format/)"]:::core
        Cloud["Cloud Code Bridge<br/>(src/cloudcode/)"]:::core
        Parser["SSE Parser & Streaming<br/>(src/cloudcode/)"]:::core
        Storage[(Credentials DB)]:::storage
        Config["Configuration & Constants"]:::core
        Error["Error Handling"]:::core
        Utils["Modules & Utilities"]:::core
    end

    %% External Services
    OAuth["Google OAuth Servers"]:::external
    CloudAPI["Antigravity Cloud Code API"]:::external

    %% Flows
    WebUI -->|HTTP POST<br/>Anthropic JSON| HTTPAPI
    CLI -->|HTTP POST<br/>Anthropic JSON| HTTPAPI

    HTTPAPI -->|extract/refresh token| Auth
    Auth -->|token| AM

    AM -->|select account| Strategies
    Strategies --> Trackers
    Trackers --> Storage
    AM --> Storage

    HTTPAPI -->|format request| Formatter
    Formatter -->|Google Gen AI JSON| Cloud

    Cloud -->|HTTPS/SSE| CloudAPI
    CloudAPI -->|SSE stream| Parser
    Parser -->|Anthropic events| Formatter

    Formatter -->|stream Anthropic JSON| HTTPAPI
    HTTPAPI -->|HTTP SSE| WebUI
    HTTPAPI -->|HTTP SSE| CLI

    HTTPAPI -.->|health & metrics| Config
    HTTPAPI -.->|error| Error
    HTTPAPI -.->|util calls| Utils

    HTTPAPI -.->|reads| Storage

    HTTPAPI --> OAuth

    %% Click Events
    click WebUI "https://github.com/badrisnarayanan/antigravity-claude-proxy/tree/main/public/"
    click CLI "https://github.com/badrisnarayanan/antigravity-claude-proxy/blob/main/bin/cli.js"
    click HTTPAPI "https://github.com/badrisnarayanan/antigravity-claude-proxy/blob/main/src/server.js"
    click Auth "https://github.com/badrisnarayanan/antigravity-claude-proxy/tree/main/src/auth/"
    click AM "https://github.com/badrisnarayanan/antigravity-claude-proxy/tree/main/src/account-manager/"
    click Strategies "https://github.com/badrisnarayanan/antigravity-claude-proxy/tree/main/src/account-manager/strategies/"
    click Trackers "https://github.com/badrisnarayanan/antigravity-claude-proxy/tree/main/src/account-manager/strategies/trackers/"
    click Cloud "https://github.com/badrisnarayanan/antigravity-claude-proxy/tree/main/src/cloudcode/"
    click Parser "https://github.com/badrisnarayanan/antigravity-claude-proxy/blob/main/src/cloudcode/sse-parser.js"
    click Formatter "https://github.com/badrisnarayanan/antigravity-claude-proxy/tree/main/src/format/"
    click Utils "https://github.com/badrisnarayanan/antigravity-claude-proxy/blob/main/src/modules/usage-stats.js"
    click Config "https://github.com/badrisnarayanan/antigravity-claude-proxy/blob/main/src/config.js"
    click Error "https://github.com/badrisnarayanan/antigravity-claude-proxy/blob/main/src/errors.js"

    %% Styles
    classDef frontend fill:#e0ffe0,stroke:#0a0,stroke-width:1px
    classDef core fill:#e0f0ff,stroke:#00a,stroke-width:1px,stroke-dasharray: 5 2
    classDef external fill:#fff0e0,stroke:#a50,stroke-width:1px,stroke-dasharray: 2 2
    classDef storage fill:#f0f0ff,stroke:#55f,stroke-width:1px,shape:cylinder
```
