# dwgx/windsurfapi architecture

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

- Interactive diagram: https://gitdiagram.com/dwgx/windsurfapi
- Repository: https://github.com/dwgx/windsurfapi

## Overview

WindsurfAPI is a Node.js gateway that converts OpenAI, Anthropic, and Gemini requests into Windsurf Cascade or Devin requests, then returns compatible responses. The principal flow is client request → HTTP routing and protocol handler → backend selection → upstream execution → response conversion. Account onboarding and pooling, conversation continuity, response storage, and the dashboard are supporting product areas. The README documents major capabilities; sampled excerpts do not expose every handler’s internal calls, so uncertain wiring is omitted.

Main entry points: [`src/server.js`](https://github.com/dwgx/windsurfapi/blob/master/src/server.js) (HTTP Server), [`src/handlers/chat.js`](https://github.com/dwgx/windsurfapi/blob/master/src/handlers/chat.js) (Chat Handler), [`src/backend-router.js`](https://github.com/dwgx/windsurfapi/blob/master/src/backend-router.js) (Backend Router), [`src/dashboard/api.js`](https://github.com/dwgx/windsurfapi/blob/master/src/dashboard/api.js) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API Gateway"]
  node_http_server["HTTP Server<br/>[server.js]"]
  node_chat_handler["Chat Handler<br/>[chat.js]"]
  node_messages_handler["Messages Handler<br/>[messages.js]"]
  node_responses_handler["Responses Handler<br/>[responses.js]"]
  node_completions_handler["Completions Handler<br/>[completions.js]"]
  node_gemini_handler["Gemini Handler<br/>[gemini.js]"]
  node_models["Model Catalog<br/>[models.js]"]
  node_tool_emulation["Tool Emulation<br/>[tool-emulation.js]"]
  node_response_store[("Response Store<br/>[response-store.js]")]
end

subgraph group_backends["Model Backends"]
  node_backend_router["Backend Router<br/>[backend-router.js]"]
  node_cascade_client["Cascade Client<br/>[client.js]"]
  node_grpc["gRPC Transport<br/>[grpc.js]"]
  node_devin_connect["Devin Connect<br/>[devin-connect.js]"]
  node_special_agent["Special Agent<br/>[special-agent.js]"]
end

subgraph group_accounts["Accounts And Sessions"]
  node_auth["Account Authentication<br/>[auth.js]"]
  node_account_pool["Account Pool"]
  node_sticky_session["Sticky Sessions<br/>[sticky-session.js]"]
end

subgraph group_dashboard["Operations Dashboard"]
  node_dashboard_api["Dashboard API<br/>[api.js]"]
  node_account_import["Account Import<br/>[import-parser.js]"]
  node_oauth_sessions["OAuth Sessions<br/>[oauth-sessions.js]"]
end

node_openai_clients(("OpenAI Clients"))
node_anthropic_clients(("Anthropic Clients"))
node_gemini_clients(("Gemini Clients"))
node_language_server["Language Server"]
node_devin_cloud["Devin Cloud"]
node_dashboard_user(("Dashboard Operator"))

node_openai_clients -->|"HTTP requests"| node_http_server
node_anthropic_clients -->|"HTTP requests"| node_http_server
node_gemini_clients -->|"HTTP requests"| node_http_server
node_http_server -->|"dispatches"| node_chat_handler
node_http_server -->|"dispatches"| node_messages_handler
node_http_server -->|"dispatches"| node_responses_handler
node_http_server -->|"dispatches"| node_completions_handler
node_http_server -->|"dispatches"| node_gemini_handler
node_http_server -->|"onboards accounts"| node_auth
node_chat_handler -->|"selects backend"| node_backend_router
node_chat_handler -->|"resolves model"| node_models
node_chat_handler -->|"emulates tools"| node_tool_emulation
node_responses_handler -->|"stores responses"| node_response_store
node_backend_router -->|"routes Cascade"| node_cascade_client
node_backend_router -->|"routes direct"| node_devin_connect
node_backend_router -->|"routes agent"| node_special_agent
node_cascade_client -->|"sends gRPC"| node_grpc
node_grpc -->|"local RPC"| node_language_server
node_devin_connect -->|"HTTPS requests"| node_devin_cloud
node_auth -->|"provides accounts"| node_account_pool
node_account_pool -->|"binds conversations"| node_sticky_session
node_dashboard_user -->|"manages accounts"| node_dashboard_api
node_dashboard_api -->|"parses imports"| node_account_import
node_dashboard_api -->|"manages login"| node_oauth_sessions
node_dashboard_api -->|"adds accounts"| node_auth

click node_http_server "https://github.com/dwgx/windsurfapi/blob/master/src/server.js"
click node_chat_handler "https://github.com/dwgx/windsurfapi/blob/master/src/handlers/chat.js"
click node_messages_handler "https://github.com/dwgx/windsurfapi/blob/master/src/handlers/messages.js"
click node_responses_handler "https://github.com/dwgx/windsurfapi/blob/master/src/handlers/responses.js"
click node_completions_handler "https://github.com/dwgx/windsurfapi/blob/master/src/handlers/completions.js"
click node_gemini_handler "https://github.com/dwgx/windsurfapi/blob/master/src/handlers/gemini.js"
click node_models "https://github.com/dwgx/windsurfapi/blob/master/src/models.js"
click node_tool_emulation "https://github.com/dwgx/windsurfapi/blob/master/src/handlers/tool-emulation.js"
click node_response_store "https://github.com/dwgx/windsurfapi/blob/master/src/response-store.js"
click node_backend_router "https://github.com/dwgx/windsurfapi/blob/master/src/backend-router.js"
click node_cascade_client "https://github.com/dwgx/windsurfapi/blob/master/src/client.js"
click node_grpc "https://github.com/dwgx/windsurfapi/blob/master/src/grpc.js"
click node_devin_connect "https://github.com/dwgx/windsurfapi/blob/master/src/devin-connect.js"
click node_special_agent "https://github.com/dwgx/windsurfapi/blob/master/src/special-agent.js"
click node_auth "https://github.com/dwgx/windsurfapi/blob/master/src/auth.js"
click node_account_pool "https://github.com/dwgx/windsurfapi/blob/master/src/conversation-pool.js"
click node_sticky_session "https://github.com/dwgx/windsurfapi/blob/master/src/account/sticky-session.js"
click node_dashboard_api "https://github.com/dwgx/windsurfapi/blob/master/src/dashboard/api.js"
click node_account_import "https://github.com/dwgx/windsurfapi/blob/master/src/dashboard/import-parser.js"
click node_oauth_sessions "https://github.com/dwgx/windsurfapi/blob/master/src/dashboard/oauth-sessions.js"

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_http_server,node_chat_handler,node_messages_handler,node_responses_handler,node_completions_handler,node_gemini_handler,node_models,node_tool_emulation,node_response_store,node_openai_clients,node_anthropic_clients,node_gemini_clients toneBlue
class node_backend_router,node_cascade_client,node_grpc,node_devin_connect,node_special_agent toneAmber
class node_auth,node_account_pool,node_sticky_session,node_language_server toneMint
class node_dashboard_api,node_account_import,node_oauth_sessions toneRose
class node_devin_cloud,node_dashboard_user toneIndigo
```

## Components

### API Gateway

- [HTTP Server](https://github.com/dwgx/windsurfapi/blob/master/src/server.js): `src/server.js`
- [Chat Handler](https://github.com/dwgx/windsurfapi/blob/master/src/handlers/chat.js): `src/handlers/chat.js`
- [Messages Handler](https://github.com/dwgx/windsurfapi/blob/master/src/handlers/messages.js): `src/handlers/messages.js`
- [Responses Handler](https://github.com/dwgx/windsurfapi/blob/master/src/handlers/responses.js): `src/handlers/responses.js`
- [Completions Handler](https://github.com/dwgx/windsurfapi/blob/master/src/handlers/completions.js): `src/handlers/completions.js`
- [Gemini Handler](https://github.com/dwgx/windsurfapi/blob/master/src/handlers/gemini.js): `src/handlers/gemini.js`
- [Model Catalog](https://github.com/dwgx/windsurfapi/blob/master/src/models.js): `src/models.js`
- [Tool Emulation](https://github.com/dwgx/windsurfapi/blob/master/src/handlers/tool-emulation.js): `src/handlers/tool-emulation.js`
- [Response Store](https://github.com/dwgx/windsurfapi/blob/master/src/response-store.js): `src/response-store.js`

### Model Backends

- [Backend Router](https://github.com/dwgx/windsurfapi/blob/master/src/backend-router.js): `src/backend-router.js`
- [Cascade Client](https://github.com/dwgx/windsurfapi/blob/master/src/client.js): `src/client.js`
- [gRPC Transport](https://github.com/dwgx/windsurfapi/blob/master/src/grpc.js): `src/grpc.js`
- [Devin Connect](https://github.com/dwgx/windsurfapi/blob/master/src/devin-connect.js): `src/devin-connect.js`
- [Special Agent](https://github.com/dwgx/windsurfapi/blob/master/src/special-agent.js): `src/special-agent.js`

### Accounts And Sessions

- [Account Authentication](https://github.com/dwgx/windsurfapi/blob/master/src/auth.js): `src/auth.js`
- [Account Pool](https://github.com/dwgx/windsurfapi/blob/master/src/conversation-pool.js): `src/conversation-pool.js`
- [Sticky Sessions](https://github.com/dwgx/windsurfapi/blob/master/src/account/sticky-session.js): `src/account/sticky-session.js`

### Operations Dashboard

- [Dashboard API](https://github.com/dwgx/windsurfapi/blob/master/src/dashboard/api.js): `src/dashboard/api.js`
- [Account Import](https://github.com/dwgx/windsurfapi/blob/master/src/dashboard/import-parser.js): `src/dashboard/import-parser.js`
- [OAuth Sessions](https://github.com/dwgx/windsurfapi/blob/master/src/dashboard/oauth-sessions.js): `src/dashboard/oauth-sessions.js`

### Other components

- **OpenAI Clients**
- **Anthropic Clients**
- **Gemini Clients**
- **Language Server**
- **Devin Cloud**
- **Dashboard Operator**

## Connections

- OpenAI Clients → HTTP Server: HTTP requests
- Anthropic Clients → HTTP Server: HTTP requests
- Gemini Clients → HTTP Server: HTTP requests
- HTTP Server → Chat Handler: dispatches
- HTTP Server → Messages Handler: dispatches
- HTTP Server → Responses Handler: dispatches
- HTTP Server → Completions Handler: dispatches
- HTTP Server → Gemini Handler: dispatches
- HTTP Server → Account Authentication: onboards accounts
- Chat Handler → Backend Router: selects backend
- Chat Handler → Model Catalog: resolves model
- Chat Handler → Tool Emulation: emulates tools
- Responses Handler → Response Store: stores responses
- Backend Router → Cascade Client: routes Cascade
- Backend Router → Devin Connect: routes direct
- Backend Router → Special Agent: routes agent
- Cascade Client → gRPC Transport: sends gRPC
- gRPC Transport → Language Server: local RPC
- Devin Connect → Devin Cloud: HTTPS requests
- Account Authentication → Account Pool: provides accounts
- Account Pool → Sticky Sessions: binds conversations
- Dashboard Operator → Dashboard API: manages accounts
- Dashboard API → Account Import: parses imports
- Dashboard API → OAuth Sessions: manages login
- Dashboard API → Account Authentication: adds accounts