# szcharlesji/raycast-relay architecture

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

- Interactive diagram: https://gitdiagram.com/szcharlesji/raycast-relay
- Repository: https://github.com/szcharlesji/raycast-relay

## Overview

##### Project Type and Purpose
- This is a serverless relay service (“Raycast Relay for Cloudflare Workers”).
- It exposes an OpenAI-compatible API (endpoints under /v1/models, /v1/chat/completions, /health) and forwards requests to the Raycast AI service using your Raycast Bearer token.
- It’s written in TypeScript, packaged as a Cloudflare Worker (configured by wrangler.jsonc), and tested with Vitest.

##### File Structure
- Top-level: configuration and metadata files (package.json, pnpm-lock, tsconfig.json, wrangler.jsonc, eslint.config.ts).
- src/: core Worker code
- index.ts – the HTTP request handler that routes to /v1/models, /v1/chat/completions, /health.
- test/: Vitest tests (index.spec.ts) and test config (tsconfig.json, env.d.ts).
- img/: documentation screenshots.
- worker-configuration.d.ts: type definitions for the Worker environment (secrets).

##### Main Components
a. Client(s)
- Raycast App or any OpenAI-compatible client (e.g. Cursor).
- HTTP debug tools (Proxyman/Charles) during development.
b. Cloudflare Worker Service
- Deployed via Wrangler CLI → Cloudflare’s edge network.
- Contains the request router in src/index.ts, and accesses environment variables (RAYCAST_BEARER_TOKEN, optional API_KEY, ADVANCED, INCLUDE_DEPRECATED).
c. External Raycast AI API
- Downstream service that actually runs the AI models; the relay proxies requests here.
d. Developer Tooling & CI (optional)
- GitHub repo, Wrangler CLI on local machine, Vitest for tests.

##### Relationships & Data Flow
1. Client makes HTTP request → Worker endpoint (/v1/models or /v1/chat/completions).
2. Worker verifies optional API_KEY (if set), then constructs an HTTP request to the Raycast AI API, injecting RAYCAST_BEARER_TOKEN in Authorization header.
3. Raycast AI responds → Worker does any necessary transformation (e.g. filter advanced or deprecated models) → Worker returns response to Client.
4. /health endpoint returns simple OK for uptime checks.
5. Developer uses Wrangler CLI to push code to Cloudflare, and runs Vitest locally against src/index.ts.

##### Architectural Patterns & Design Principles
- Serverless / Edge-compute
- Single entry-point router (similar to a micro API)
- Configuration via environment variables / secrets (12-factor style)
- Lightweight pass-through with optional filtering logic
- Clear separation:
- src/ for runtime code
- test/ for automated tests
- config files (wrangler.jsonc, tsconfig.json)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Side" 
        direction TB
        C1["Raycast App / OpenAI Client"] 
        C2["HTTP Debug Tools (Proxyman/Charles)"]
    end

    subgraph "Edge Function – Cloudflare Worker" 
        direction TB
        R["Request Router (src/index.ts)"]:::worker
        subgraph "Handlers"
            direction TB
            H1["modelsHandler"] 
            H2["chatHandler"] 
            H3["healthHandler"] 
        end
        T["Shared Types (src/types.ts)"]:::worker
        Env["Env Vars Definitions\n(worker-configuration.d.ts)"]:::worker
    end

    subgraph "External API" 
        direction TB
        API["Raycast AI Service"]:::external
    end

    subgraph "Developer & CI" 
        direction TB
        G["GitHub Repo"] 
        WLC["Wrangler CLI\n(wrangler.jsonc)"] 
        V["Vitest Tests\n(test/index.spec.ts)"] 
        E1["Test Env Types\n(test/env.d.ts)"] 
        E2["Test TS Config\n(test/tsconfig.json)"] 
        E3["Project TS Config\n(tsconfig.json)"] 
        E4["Vitest Config\n(vitest.config.mts)"] 
        E5["ESLint Config\n(eslint.config.ts)"] 
        E6["Package & Lockfiles\n(package.json, package-lock.json, pnpm-lock.yaml)"] 
        E7["Docs & Assets\n(README.md, img/)"]
    end

    C1 -->|"POST /v1/models"| R
    C1 -->|"POST /v1/chat/completions"| R
    C1 -->|"/health"| R
    R -->|"calls modelsHandler"| H1
    R -->|"calls chatHandler"| H2
    R -->|"calls healthHandler"| H3
    H1 -->|"forwards + Bearer Token"| API
    H2 -->|"forwards + Bearer Token"| API
    API -->|"returns AI response"| R
    R -->|"returns response"| C1
    Env --> R

    V -.->|"invokes handlers"| R
    G -.-> WLC
    WLC -.->|"deploy code"| R

    click R "https://github.com/szcharlesji/raycast-relay/blob/master/src/index.ts"
    click T "https://github.com/szcharlesji/raycast-relay/blob/master/src/types.ts"
    click Env "https://github.com/szcharlesji/raycast-relay/blob/master/worker-configuration.d.ts"
    click WLC "https://github.com/szcharlesji/raycast-relay/blob/master/wrangler.jsonc"
    click V "https://github.com/szcharlesji/raycast-relay/blob/master/test/index.spec.ts"
    click E1 "https://github.com/szcharlesji/raycast-relay/blob/master/test/env.d.ts"
    click E2 "https://github.com/szcharlesji/raycast-relay/blob/master/test/tsconfig.json"
    click E3 "https://github.com/szcharlesji/raycast-relay/blob/master/tsconfig.json"
    click E4 "https://github.com/szcharlesji/raycast-relay/blob/master/vitest.config.mts"
    click E5 "https://github.com/szcharlesji/raycast-relay/blob/master/eslint.config.ts"
    click E6 "https://github.com/szcharlesji/raycast-relay/blob/master/package.json"
    click E6 "https://github.com/szcharlesji/raycast-relay/blob/master/package-lock.json"
    click E6 "https://github.com/szcharlesji/raycast-relay/blob/master/pnpm-lock.yaml"
    click E7 "https://github.com/szcharlesji/raycast-relay/blob/master/README.md"
    click E7 "https://github.com/szcharlesji/raycast-relay/tree/master/img/"

    classDef client fill:#add8e6,stroke:#000,stroke-width:1px
    classDef worker fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#ffcc80,stroke:#000,stroke-width:1px
    classDef dev fill:#d3d3d3,stroke:#000,stroke-width:1px

    class C1,C2 client
    class R,H1,H2,H3,T,Env worker
    class API external
    class G,WLC,V,E1,E2,E3,E4,E5,E6,E7 dev
```
