# libaxuan/cursor2api-go architecture

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

- Interactive diagram: https://gitdiagram.com/libaxuan/cursor2api-go
- Repository: https://github.com/libaxuan/cursor2api-go

## Overview

Cursor2API is a Go HTTP service that adapts Cursor Web to an OpenAI-compatible chat API. The main workflow is client request → authenticated chat handler → Cursor request/protocol preparation → Cursor Web → parsed assistant events → API response; model listing, health checks, documentation, streaming, thinking variants, and tool calls are additional product capabilities. The excerpts establish routing, configuration, authentication, and portions of the protocol and JavaScript runtime; some internal calls and response paths are documented or implied but not visible, so those links are marked unverified.

Main entry points: [`services/cursor.go`](https://github.com/libaxuan/cursor2api-go/blob/main/services/cursor.go) (Cursor Service), [`handlers/handler.go`](https://github.com/libaxuan/cursor2api-go/blob/main/handlers/handler.go) (API Handlers), [`main.go`](https://github.com/libaxuan/cursor2api-go/blob/main/main.go) (HTTP Server), [`models/models.go`](https://github.com/libaxuan/cursor2api-go/blob/main/models/models.go) (API Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_server["HTTP Server<br/>[main.go]"]
  node_auth["API Key Auth<br/>[auth.go]"]
  node_handler["API Handlers<br/>[handler.go]"]
  node_error["Error Middleware<br/>[error.go]"]
  node_cors["CORS Middleware<br/>[cors.go]"]
  node_health["Health Check<br/>[handler.go]"]
  node_docs["Docs Endpoint<br/>[handler.go]"]
end

subgraph group_adapter["Cursor Adapter"]
  node_cursor["Cursor Service<br/>[cursor.go]"]
  node_protocol["Request Builder<br/>[cursor_protocol.go]"]
  node_parser["Event Parser<br/>[cursor_protocol.go]"]
  node_headers["Browser Headers<br/>[headers.go]"]
  node_utils["Shared Utilities<br/>[utils.go]"]
end

subgraph group_runtime["Browser Runtime"]
  node_jsmain["JS Harness<br/>[main.js]"]
  node_env["Browser Environment<br/>[env.js]"]
end

subgraph group_domain["Models and Config"]
  node_config["Service Config<br/>[config.go]"]
  node_models["API Models<br/>[models.go]"]
  node_capabilities["Model Capabilities"]
  node_modelconfig["Model Mapping<br/>[model_config.go]"]
end

node_client(("API Client"))
node_cursorweb{{"Cursor Web"}}
node_node{{"Node.js Runtime"}}

node_client -->|"sends requests"| node_server
node_server -->|"loads config"| node_config
node_server -->|"registers routes"| node_handler
node_server -->|"protects chat route"| node_auth
node_server -->|"installs middleware"| node_cors
node_server -->|"installs middleware"| node_error
node_handler -->|"reads models"| node_config
node_handler -->|"creates service"| node_cursor
node_handler -->|"binds chat request"| node_models
node_handler -.->|"submits chat"| node_cursor
node_handler -->|"serves health"| node_health
node_handler -->|"serves docs"| node_docs
node_config -->|"expands model list"| node_capabilities
node_handler -.->|"lists model variants"| node_capabilities
node_cursor -.->|"builds Cursor request"| node_protocol
node_cursor -.->|"sets upstream headers"| node_headers
node_cursor -->|"loads JS harness"| node_jsmain
node_cursor -->|"loads browser environment"| node_env
node_jsmain -.->|"uses environment shim"| node_env
node_cursor -.->|"executes JavaScript"| node_node
node_node -.->|"runs harness"| node_jsmain
node_cursor -->|"calls upstream"| node_cursorweb
node_protocol -->|"builds payload"| node_models
node_protocol -->|"generates request ID"| node_utils
node_cursor -.->|"parses response events"| node_parser
node_parser -->|"emits assistant events"| node_models
node_cursor -->|"collects chat results"| node_models
node_cursor -.->|"returns completions"| node_client
node_modelconfig -.->|"maps model upstream"| node_cursor

click node_server "https://github.com/libaxuan/cursor2api-go/blob/main/main.go"
click node_auth "https://github.com/libaxuan/cursor2api-go/blob/main/middleware/auth.go"
click node_handler "https://github.com/libaxuan/cursor2api-go/blob/main/handlers/handler.go"
click node_error "https://github.com/libaxuan/cursor2api-go/blob/main/middleware/error.go"
click node_cors "https://github.com/libaxuan/cursor2api-go/blob/main/middleware/cors.go"
click node_config "https://github.com/libaxuan/cursor2api-go/blob/main/config/config.go"
click node_models "https://github.com/libaxuan/cursor2api-go/blob/main/models/models.go"
click node_capabilities "https://github.com/libaxuan/cursor2api-go/blob/main/models/model_capabilities.go"
click node_modelconfig "https://github.com/libaxuan/cursor2api-go/blob/main/models/model_config.go"
click node_cursor "https://github.com/libaxuan/cursor2api-go/blob/main/services/cursor.go"
click node_protocol "https://github.com/libaxuan/cursor2api-go/blob/main/services/cursor_protocol.go"
click node_parser "https://github.com/libaxuan/cursor2api-go/blob/main/utils/cursor_protocol.go"
click node_headers "https://github.com/libaxuan/cursor2api-go/blob/main/utils/headers.go"
click node_utils "https://github.com/libaxuan/cursor2api-go/blob/main/utils/utils.go"
click node_jsmain "https://github.com/libaxuan/cursor2api-go/blob/main/jscode/main.js"
click node_env "https://github.com/libaxuan/cursor2api-go/blob/main/jscode/env.js"
click node_health "https://github.com/libaxuan/cursor2api-go/blob/main/handlers/handler.go"
click node_docs "https://github.com/libaxuan/cursor2api-go/blob/main/handlers/handler.go"

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_server,node_auth,node_handler,node_error,node_cors,node_health,node_docs,node_client toneBlue
class node_cursor,node_protocol,node_parser,node_headers,node_utils toneAmber
class node_jsmain,node_env toneMint
class node_config,node_models,node_capabilities,node_modelconfig toneRose
class node_cursorweb,node_node toneIndigo
```

## Components

### HTTP API

- [HTTP Server](https://github.com/libaxuan/cursor2api-go/blob/main/main.go): `main.go`
- [API Key Auth](https://github.com/libaxuan/cursor2api-go/blob/main/middleware/auth.go): `middleware/auth.go`
- [API Handlers](https://github.com/libaxuan/cursor2api-go/blob/main/handlers/handler.go): `handlers/handler.go`
- [Error Middleware](https://github.com/libaxuan/cursor2api-go/blob/main/middleware/error.go): `middleware/error.go`
- [CORS Middleware](https://github.com/libaxuan/cursor2api-go/blob/main/middleware/cors.go): `middleware/cors.go`
- [Health Check](https://github.com/libaxuan/cursor2api-go/blob/main/handlers/handler.go): `handlers/handler.go`
- [Docs Endpoint](https://github.com/libaxuan/cursor2api-go/blob/main/handlers/handler.go): `handlers/handler.go`

### Cursor Adapter

- [Cursor Service](https://github.com/libaxuan/cursor2api-go/blob/main/services/cursor.go): `services/cursor.go`
- [Request Builder](https://github.com/libaxuan/cursor2api-go/blob/main/services/cursor_protocol.go): `services/cursor_protocol.go`
- [Event Parser](https://github.com/libaxuan/cursor2api-go/blob/main/utils/cursor_protocol.go): `utils/cursor_protocol.go`
- [Browser Headers](https://github.com/libaxuan/cursor2api-go/blob/main/utils/headers.go): `utils/headers.go`
- [Shared Utilities](https://github.com/libaxuan/cursor2api-go/blob/main/utils/utils.go): `utils/utils.go`

### Browser Runtime

- [JS Harness](https://github.com/libaxuan/cursor2api-go/blob/main/jscode/main.js): `jscode/main.js`
- [Browser Environment](https://github.com/libaxuan/cursor2api-go/blob/main/jscode/env.js): `jscode/env.js`

### Models and Config

- [Service Config](https://github.com/libaxuan/cursor2api-go/blob/main/config/config.go): `config/config.go`
- [API Models](https://github.com/libaxuan/cursor2api-go/blob/main/models/models.go): `models/models.go`
- [Model Capabilities](https://github.com/libaxuan/cursor2api-go/blob/main/models/model_capabilities.go): `models/model_capabilities.go`
- [Model Mapping](https://github.com/libaxuan/cursor2api-go/blob/main/models/model_config.go): `models/model_config.go`

### Other components

- **API Client**
- **Cursor Web**
- **Node.js Runtime**

## Connections

- API Client → HTTP Server: sends requests (evidence: `README.md`)
- HTTP Server → Service Config: loads config (evidence: `main.go`)
- HTTP Server → API Handlers: registers routes (evidence: `main.go`)
- HTTP Server → API Key Auth: protects chat route (evidence: `main.go`)
- HTTP Server → CORS Middleware: installs middleware (evidence: `main.go`)
- HTTP Server → Error Middleware: installs middleware (evidence: `main.go`)
- API Handlers → Service Config: reads models (evidence: `handlers/handler.go`)
- API Handlers → Cursor Service: creates service (evidence: `handlers/handler.go`)
- API Handlers → API Models: binds chat request (evidence: `handlers/handler.go`)
- API Handlers → Cursor Service: submits chat
- API Handlers → Health Check: serves health (evidence: `handlers/handler.go`)
- API Handlers → Docs Endpoint: serves docs (evidence: `handlers/handler.go`)
- Service Config → Model Capabilities: expands model list (evidence: `config/config.go`)
- API Handlers → Model Capabilities: lists model variants
- Cursor Service → Request Builder: builds Cursor request
- Cursor Service → Browser Headers: sets upstream headers
- Cursor Service → JS Harness: loads JS harness (evidence: `services/cursor.go`)
- Cursor Service → Browser Environment: loads browser environment (evidence: `services/cursor.go`)
- JS Harness → Browser Environment: uses environment shim
- Cursor Service → Node.js Runtime: executes JavaScript
- Node.js Runtime → JS Harness: runs harness
- Cursor Service → Cursor Web: calls upstream (evidence: `services/cursor.go`)
- Request Builder → API Models: builds payload (evidence: `services/cursor_protocol.go`)
- Request Builder → Shared Utilities: generates request ID (evidence: `services/cursor_protocol.go`)
- Cursor Service → Event Parser: parses response events
- Event Parser → API Models: emits assistant events (evidence: `utils/cursor_protocol.go`)
- Cursor Service → API Models: collects chat results (evidence: `services/cursor.go`)
- Cursor Service → API Client: returns completions
- Model Mapping → Cursor Service: maps model upstream
