# alii13/antigravity-cursor-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/alii13/antigravity-cursor-proxy
- Repository: https://github.com/alii13/antigravity-cursor-proxy

## Overview

This repository is a small Node.js/CJS proxy service whose main job is to sit between Cursor and Google’s agentic model APIs. The architecture is intentionally split into a few thin scripts rather than a large application framework.

1. **Client-facing boundary**
   - The consuming client is Cursor, configured as an OpenAI-compatible model provider.
   - Cursor sends standard chat/completions-style traffic to a **base URL** exposed by this repo.

2. **Public ingress layer**
   - `start.cjs` launches a local server on `localhost:3000` and a **Cloudflare Quick Tunnel**.
   - The tunnel is the public HTTPS entrypoint; Cursor talks to the temporary `trycloudflare.com` URL instead of directly to localhost.
   - This is a transport boundary, not business logic: it exists to satisfy HTTPS/networking requirements.

3. **Core proxy / protocol translation layer**
   - `proxy.cjs` is the central application module.
   - Its role is to translate OpenAI-style requests from Cursor into the Google “agentic” protocol expected by Gemini/Claude-backed flows.
   - It also handles response shaping back into the format Cursor expects.
   - The README indicates this layer additionally injects the “thought signature” metadata needed for tool use and agentic reasoning.

4. **Model routing boundary**
   - The proxy maps user-facing model IDs such as `ag-pro`, `ag-flash`, `ag-sonnet`, `ag-opus`, and `ag-haiku` onto underlying Gemini/Claude variants.
   - This is a logical abstraction layer: Cursor only sees the alias, while the proxy chooses the target model family and formatting.

5. **Authentication/session bridge**
   - `db_helper.cjs` is likely the local-session integration point.
   - The README says the proxy extracts Google Cloud Code / Antigravity session tokens from the local IDE environment, rather than requiring manual API keys.
   - Architecturally, this means the proxy depends on a **local trust boundary**: it reads credentials from the developer’s logged-in editor session and forwards them upstream.

6. **Workspace/project discovery**
   - `discover_project.cjs` appears to inspect the current project/workspace context.
   - In an agentic proxy like this, that usually supports richer prompts or tool context by identifying repository structure or project metadata before forwarding requests.
   - This is a support subsystem, not the main request path, but it influences what the proxy sends upstream.

7. **Bootstrap and environment preparation**
   - `scripts/install-cloudflared.cjs` is the setup helper that downloads the correct `cloudflared` binary for the host OS.
   - `package.json` likely wires this into install/start scripts, making the tunnel dependency part of normal setup rather than a manual prerequisite.

8. **Operational flow**
   - The runtime path is: **Cursor → Cloudflare tunnel URL → local proxy on port 3000 → Google agentic service(s)**.
   - In parallel, the proxy also reads **local auth/session state** from the IDE environment and may inspect workspace/project context.
   - The returned model output flows back through the same tunnel to Cursor.

9. **What is and is not in the repo**
   - This is not a full platform or web app; it is a thin proxy bridge plus bootstrap utilities.
   - There is no sign of a database service, queue, or frontend application.
   - The `assets/` directory and `README.md` support packaging/documentation, not core runtime behavior.

10. **Architecture diagram takeaway**
   - The key boxes to draw are:
     - **Cursor IDE** on one side,
     - **Cloudflare Quick Tunnel** as the public HTTPS bridge,
     - **Local Node proxy** as the translator/orchestrator,
     - **Local session/token source** as a side-channel dependency,
     - **Google agentic model endpoints** as the upstream target.
   - The main trust and protocol boundaries are the tunnel edge and the session-token bridge.

Main entry points: [`proxy.cjs`](https://github.com/alii13/antigravity-cursor-proxy/blob/main/proxy.cjs) (Proxy Core), [`start.cjs`](https://github.com/alii13/antigravity-cursor-proxy/blob/main/start.cjs) (Start Server), [`package.json`](https://github.com/alii13/antigravity-cursor-proxy/blob/main/package.json) (Package Scripts), [`db_helper.cjs`](https://github.com/alii13/antigravity-cursor-proxy/blob/main/db_helper.cjs) (Session Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_start["Start Server<br/>entrypoint<br/>[start.cjs]"]
  node_proxy["Proxy Core<br/>translator<br/>[proxy.cjs]"]
  node_routing["Model Routing<br/>alias map<br/>[proxy.cjs]"]
  node_thoughts["Thought Signatures<br/>metadata injector<br/>[proxy.cjs]"]
end

subgraph group_support["Support"]
  node_db_helper["Session Bridge<br/>auth bridge<br/>[db_helper.cjs]"]
  node_discover_project["Project Discovery<br/>context builder"]
  node_install_cloudflared["Install Cloudflared<br/>setup script"]
end

subgraph group_packaging["Packaging"]
  node_package_json["Package Scripts<br/>npm manifest<br/>[package.json]"]
  node_assets["Assets<br/>packaged files"]
end

node_cursor(("Cursor IDE<br/>client"))
node_tunnel{{"Cloudflare Tunnel<br/>https bridge"}}
node_google_api(("Google Agentic API<br/>upstream model"))
node_session_source(("Local Session<br/>auth source"))
node_workspace(("Workspace Context<br/>project context"))

node_cursor -->|"HTTPS traffic"| node_tunnel
node_tunnel -->|"forward"| node_start
node_start -->|"serve"| node_proxy
node_start -->|"bootstrap"| node_install_cloudflared
node_proxy -->|"select model"| node_routing
node_proxy -->|"inject metadata"| node_thoughts
node_proxy -->|"auth"| node_db_helper
node_proxy -->|"context"| node_discover_project
node_db_helper -->|"read tokens"| node_session_source
node_discover_project -->|"inspect"| node_workspace
node_proxy -->|"agentic calls"| node_google_api
node_google_api -->|"responses"| node_proxy
node_package_json -->|"start script"| node_start
node_package_json -->|"install hook"| node_install_cloudflared
node_assets -.->|"bundle support"| node_package_json

click node_start "https://github.com/alii13/antigravity-cursor-proxy/blob/main/start.cjs"
click node_proxy "https://github.com/alii13/antigravity-cursor-proxy/blob/main/proxy.cjs"
click node_routing "https://github.com/alii13/antigravity-cursor-proxy/blob/main/proxy.cjs"
click node_thoughts "https://github.com/alii13/antigravity-cursor-proxy/blob/main/proxy.cjs"
click node_db_helper "https://github.com/alii13/antigravity-cursor-proxy/blob/main/db_helper.cjs"
click node_discover_project "https://github.com/alii13/antigravity-cursor-proxy/blob/main/discover_project.cjs"
click node_install_cloudflared "https://github.com/alii13/antigravity-cursor-proxy/blob/main/scripts/install-cloudflared.cjs"
click node_package_json "https://github.com/alii13/antigravity-cursor-proxy/blob/main/package.json"
click node_assets "https://github.com/alii13/antigravity-cursor-proxy/tree/main/assets"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_start,node_proxy,node_routing,node_thoughts toneBlue
class node_db_helper,node_discover_project,node_install_cloudflared toneAmber
class node_package_json,node_assets toneMint
class node_cursor,node_tunnel,node_google_api,node_session_source,node_workspace toneNeutral
```

## Components

### Runtime

Main request path and server entrypoints.

- [Start Server](https://github.com/alii13/antigravity-cursor-proxy/blob/main/start.cjs): entrypoint · Launches the local server on port 3000 and brings up the Quick Tunnel. · `start.cjs`
- [Proxy Core](https://github.com/alii13/antigravity-cursor-proxy/blob/main/proxy.cjs): translator · Converts Cursor OpenAI-style requests into the Google agentic protocol and shapes responses back for Cursor. · `proxy.cjs`
- [Model Routing](https://github.com/alii13/antigravity-cursor-proxy/blob/main/proxy.cjs): alias map · Maps user-facing aliases like ag-pro and ag-sonnet to underlying Gemini/Claude variants. · `proxy.cjs`
- [Thought Signatures](https://github.com/alii13/antigravity-cursor-proxy/blob/main/proxy.cjs): metadata injector · Adds agentic reasoning and tool-use metadata required by upstream flows. · `proxy.cjs`

### Support

Authentication, workspace discovery, and setup helpers.

- [Session Bridge](https://github.com/alii13/antigravity-cursor-proxy/blob/main/db_helper.cjs): auth bridge · Extracts local IDE session tokens and forwards them upstream as credentials. · `db_helper.cjs`
- [Project Discovery](https://github.com/alii13/antigravity-cursor-proxy/blob/main/discover_project.cjs): context builder · Inspects the current workspace to supply project-aware context to the proxy. · `discover_project.cjs`
- [Install Cloudflared](https://github.com/alii13/antigravity-cursor-proxy/blob/main/scripts/install-cloudflared.cjs): setup script · Downloads the host-appropriate cloudflared binary for tunnel setup. · `scripts/install-cloudflared.cjs`

### Packaging

Repo metadata and bundled assets.

- [Package Scripts](https://github.com/alii13/antigravity-cursor-proxy/blob/main/package.json): npm manifest · Defines install and start wiring for the proxy and tunnel bootstrap. · `package.json`
- [Assets](https://github.com/alii13/antigravity-cursor-proxy/tree/main/assets): packaged files · Bundled non-runtime assets used for distribution and repository support. · `assets`

### Other components

- **Cursor IDE**: client · OpenAI-compatible chat/completions client configured to use the proxy as its base URL.
- **Cloudflare Tunnel**: https bridge · Public HTTPS ingress that forwards traffic to the local server.
- **Google Agentic API**: upstream model · Target model endpoints used by the proxy after protocol translation.
- **Local Session**: auth source · IDE-bound Google Cloud Code / Antigravity session state used for upstream authentication.
- **Workspace Context**: project context · Current repository or project metadata discovered for richer agentic requests.

## Connections

- Cursor IDE → Cloudflare Tunnel: HTTPS traffic · Cursor sends OpenAI-style requests to the public tunnel URL.
- Cloudflare Tunnel → Start Server: forward · Quick Tunnel forwards public requests to the local Node server.
- Start Server → Proxy Core: serve · The entrypoint boots the local proxy service.
- Start Server → Install Cloudflared: bootstrap · Startup/setup depends on the cloudflared installer helper.
- Proxy Core → Model Routing: select model · Resolves user-facing aliases to the correct upstream model family.
- Proxy Core → Thought Signatures: inject metadata · Adds thought-signature and tool-use metadata before forwarding upstream.
- Proxy Core → Session Bridge: auth · Pulls local session credentials through the session bridge.
- Proxy Core → Project Discovery: context · Uses workspace discovery to enrich upstream requests.
- Session Bridge → Local Session: read tokens · Reads credentials from the local IDE/session environment.
- Project Discovery → Workspace Context: inspect · Derives repository or project context from the current workspace.
- Proxy Core → Google Agentic API: agentic calls · Forwards translated requests to Google-backed model endpoints.
- Google Agentic API → Proxy Core: responses · Upstream model output returns to the proxy for shaping back to Cursor.
- Package Scripts → Start Server: start script · NPM scripts wire the normal runtime startup path.
- Package Scripts → Install Cloudflared: install hook · Package setup includes cloudflared installation support.
- Assets → Package Scripts: bundle support · Packaged assets accompany the repo distribution and metadata.
