# wisdgod/cursor-api architecture

> Architecture diagram of the GitHub repository wisdgod/cursor-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wisdgod/cursor-api
- Repository: https://github.com/wisdgod/cursor-api

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Clients & UI"
        direction TB
        HTTPClient["Public HTTP Clients"]:::external
        WebUI["Web UI (Browser)"]:::external
        Worker["Worker.js"]:::external
        StaticAssets["Static Assets"]:::storage
        ServeTS["Static Server (serve.ts)"]:::server
    end

    %% CLI Tools
    subgraph "CLI Tools"
        direction TB
        GetToken["get-token"]:::cli
        ResetTelemetry["reset-telemetry"]:::cli
        SetToken["set-token"]:::cli
    end

    %% Main Service
    HTTPClient -->|HTTP Request| HTTPServer
    WebUI -->|Loads Assets| ServeTS
    ServeTS -->|Serves| StaticAssets
    StaticAssets -->|Used by| WebUI

    GetToken --> CommonLayer
    ResetTelemetry --> CommonLayer
    SetToken --> CommonLayer

    subgraph "API Gateway / HTTP Server"
        direction TB
        HTTPServer["Main Binary"]:::server
    end

    click HTTPServer "https://github.com/wisdgod/cursor-api/blob/main/src/main.rs"
    click HTTPServer "https://github.com/wisdgod/cursor-api/blob/main/src/app.rs"

    HTTPServer --> CoreLayer

    %% Core Framework Layer
    subgraph "Framework Layer (core)" 
        direction TB
        Router["HTTP Router\n(core/route.rs)"]:::server
        Middleware["Middleware\n(core/middleware.rs)"]:::server
        Auth["Auth Middleware\n(auth.rs)"]:::server
        Stream["Streaming\n(core/stream.rs)"]:::server
        Decoder["Stream Decoder\n(decoder.rs)"]:::server
        ConfigCore["Config Loader\n(core/config.rs)"]:::server
        Adapter["AI Adapter\n(core/adapter.rs)"]:::server
        AIServer["AIServer Stubs\n(core/aiserver.rs)"]:::server
    end

    click Router "https://github.com/wisdgod/cursor-api/blob/main/src/core/route.rs"
    click Middleware "https://github.com/wisdgod/cursor-api/blob/main/src/core/middleware.rs"
    click Auth "https://github.com/wisdgod/cursor-api/blob/main/src/core/middleware/auth.rs"
    click Stream "https://github.com/wisdgod/cursor-api/blob/main/src/core/stream.rs"
    click Decoder "https://github.com/wisdgod/cursor-api/blob/main/src/core/stream/decoder.rs"
    click ConfigCore "https://github.com/wisdgod/cursor-api/blob/main/src/core/config.rs"
    click Adapter "https://github.com/wisdgod/cursor-api/blob/main/src/core/adapter.rs"
    click AIServer "https://github.com/wisdgod/cursor-api/blob/main/src/core/aiserver.rs"

    CoreLayer --> Router
    Router --> Middleware
    Middleware --> Auth
    Middleware -->|passes| Stream
    Stream --> Decoder
    Middleware --> AppLayer
    CoreLayer --> ConfigCore
    CoreLayer --> Adapter
    Adapter --> AIServer

    %% Business Logic Layer
    subgraph "Business Logic (app)" 
        direction TB
        AppDir["app/ (entire)"]:::server
        AppConfig["Config\n(config.rs)"]:::server
        Constant["Constants\n(constant.rs)"]:::server
        Lazy["Lazy Init\n(lazy.rs)"]:::server
        ModelCore["Model Core\n(model.rs)"]:::server
        ModelSub["Model Subpackages"]:::server
        Prompts["Prompts\n(app/prompts/)"]:::server
    end

    click AppDir "https://github.com/wisdgod/cursor-api/tree/main/src/app/"
    click AppConfig "https://github.com/wisdgod/cursor-api/blob/main/src/app/config.rs"
    click Constant "https://github.com/wisdgod/cursor-api/blob/main/src/app/constant.rs"
    click Lazy "https://github.com/wisdgod/cursor-api/blob/main/src/app/lazy.rs"
    click ModelCore "https://github.com/wisdgod/cursor-api/blob/main/src/app/model.rs"
    click ModelSub "https://github.com/wisdgod/cursor-api/tree/main/src/app/model/"
    click Prompts "https://github.com/wisdgod/cursor-api/tree/main/src/app/prompts/"

    Middleware --> AppLayer
    AppLayer --> AppConfig
    AppLayer --> ModelCore
    AppLayer --> ModelSub
    AppLayer --> Prompts

    %% Shared Utilities Layer
    subgraph "Shared Utilities (common)"
        direction TB
        CommonClient["AI Client\n(common/client.rs)"]:::server
        CommonCore["common.rs\n(common/)"]:::server
        ModelCommon["Models\n(common/model.rs)"]:::server
        UtilsCommon["Utils\n(common/utils.rs)"]:::server
    end

    click CommonClient "https://github.com/wisdgod/cursor-api/blob/main/src/common/client.rs"
    click CommonCore "https://github.com/wisdgod/cursor-api/blob/main/src/common.rs"
    click ModelCommon "https://github.com/wisdgod/cursor-api/blob/main/src/common/model.rs"
    click UtilsCommon "https://github.com/wisdgod/cursor-api/blob/main/src/common/utils.rs"

    AppLayer --> CommonLayer
    CommonLayer --> CommonClient
    CommonLayer --> ModelCommon
    CommonLayer --> UtilsCommon

    %% External AI Services
    ExternalAI["Cursor/Claude/GPT AI"]:::external
    AIServer --> ExternalAI
    CommonClient --> ExternalAI

    %% File System
    FileSystem["File System\n(.tokens, in-memory)"]:::storage
    AppLayer --> FileSystem
    StaticAssets --> FileSystem

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        Workflows["GitHub Workflows\n(.github/workflows/)"]:::ci
        Dockerfiles["Dockerfiles & Cross.toml"]:::ci
        Scripts["Build Scripts\n(scripts/)"]:::ci
    end

    click Workflows "https://github.com/wisdgod/cursor-api/tree/main/.github/workflows/"
    click Dockerfiles "https://github.com/wisdgod/cursor-api/tree/main/Dockerfile"
    click Dockerfiles "https://github.com/wisdgod/cursor-api/blob/main/Dockerfile.cross"
    click Dockerfiles "https://github.com/wisdgod/cursor-api/blob/main/Dockerfile.cross.arm64"
    click Dockerfiles "https://github.com/wisdgod/cursor-api/blob/main/Cross.toml"
    click Scripts "https://github.com/wisdgod/cursor-api/tree/main/scripts/"

    CI["CI Pipeline"]:::ci
    Workflows --> CI
    CI --> Dockerfiles
    CI --> Scripts
    Dockerfiles --> HTTPServer

    %% Classes
    classDef server fill:#D6EAF8,stroke:#1F618D,color:#1B4F72;
    classDef external fill:#D5F5E3,stroke:#229954,color:#196F3D;
    classDef storage fill:#FAD7A0,stroke:#CA6F1E,color:#784212;
    classDef cli fill:#E5E7E9,stroke:#616A6B,color:#1C2833;
    classDef ci fill:#F2F3F4,stroke:#979A9A,color:#424949;
```
