How wisdgod/cursor-api works
Project type and purpose
• From the file tree and README, cursor-api is a Rust-based backend HTTP server exposing a set of AI/chat-oriented REST and HTML endpoints. It wraps the Cursor/Claude/GPT AI services, manages API tokens and proxies, and serves static HTML/JS pages for token/proxy/config management. It also includes small CLI tools under tools/ and Docker/Cross-compile support.
File structure
• Top-level:
• src/ – Rust source code broken into three layers:
• core/ – HTTP server framework (routes, middleware, streaming, config, adapters to AI server)
• app/ – Business logic (models, proxy pool, usage checks, prompts, key builder)
• common/ – Shared utilities (client for external AI, models, error handling, utils)
• static/ + serve.ts, worker.js – Static HTML/CSS/JS pages and a minimal TypeScript/JS server for UI pages.
• tools/ – standalone Rust CLI utilities (get-token, reset-telemetry, set-token).
• Dockerfile*, cross.toml, scripts/ – build and deployment automation (Docker, cross-compilation, CI workflows).
README for additional insights
• The service uses environment variables (AUTH_TOKEN, PORT, ROUTE_PREFIX), optional token file storage (.tokens), dynamic AI model lists, streaming vs non-streaming chat completions, token/proxy/config management APIs, and static UI pages for administration. No external database—state is held in memory or file-backed token files.
a. Main components
• Client Layers:
• Public HTTP Clients – any HTTP client, Web UI in browser (static pages + worker.js), CLI tools.
• API Gateway / HTTP Server – the Rust binary built from src/main.rs orchestrating core, app, and common.
• Business Logic Layer (app/) – token management, proxy pool, key builder, usage checks, prompts.
• Framework Layer (core/) – routing, middleware (auth, logging, checksum), streaming, config loader.
• External AI Services – Cursor.com/Claude/GPT endpoints (via common/client.rs).
• File System – .tokens or in-memory state, static assets under static/.
• CI/CD & Deployment – Docker images, cross-compile via .cargo/config.toml, GitHub Actions.
b. Relationships and data flow
• Clients send HTTP requests → HTTP Server (core/router) → Middleware (auth, checksum) → Business Logic (app/*) → External AI Client (common/client.rs) → AI Service → back through layers → HTTP response to client.
• Static UI requests → serve.ts/worker.js serves static/ assets.
• Token/proxy management requests → business logic updates in-memory state or .tokens file.
• CI pipelines build Docker artifacts, push to registry, deploy.
c. Architectural patterns & design principles
• Layered architecture (Presentation: static UI; Application: app/; Service/Framework: core/; Infrastructure: common/ & file system).
• Adapter pattern for AI service interaction (core/adapter.rs, common/client.rs).
• Middleware pipeline for auth, logging, checksum.
• Single binary micro-service with in-process state, no external DB.
• Modular separation of concerns: routing vs business logic vs utilities.
d. Key technologies and frameworks
• Rust, Cargo, build.rs
• hyper/warp or similar HTTP server (implied by core/route modules)
• Protocol Buffers & gRPC stubs (*.proto in core/aiserver/v1)
• Docker, cross compilation (cross, Dockerfile.cross*)
• TypeScript/Node (static asset server, serve.ts, worker.js)
• Shell & PowerShell scripts for build and setup
• Blue for server layers (core, app, common)
• Green for external systems (Cursor AI, Docker registry)
• Orange for file system & static assets
• Gray for CLI tools & CI/CD pipelines