AI Reverse Proxy

A Node.js command-line tool that intercepts HTTP requests from a coding agent (e.g., Cline), forwards them to an AI platform API (e.g., DeepSeek) over HTTPS, and logs both request metadata and full response data (including Server-Sent Event streams) into a local SQLite database.

Usage

Run the proxy directly without cloning:

npx ai-proxy --target https://api.deepseek.com --port 8080

The proxy will start listening on http://localhost:8080 and forward requests to the specified target. All request and response data is logged to ./ai-proxy.db by default.

Configuration

Flag	Default	Description
--target <url>	(required)	Upstream AI API base URL (e.g., https://api.deepseek.com). Trailing slashes are stripped automatically.
--port <number>	(required)	Local port to listen on.
--db <path>	./ai-proxy.db	Path to the SQLite database file.
--insecure	false	Accept self-signed or invalid upstream TLS certificates.
--max-request-body <bytes>	1048576	Maximum bytes of request body to accept.
--max-log-body <bytes>	5242880	Maximum bytes of a non-streaming response body to log.
--shutdown-grace-ms <ms>	10000	Milliseconds to wait for active connections during shutdown.
--session-idle-timeout-ms <ms>	300000	Idle time (ms) after which a session is considered closed (5 minutes).

No environment variables are used. All configuration is provided via CLI arguments.

Development

Clone and set up the project for local development:

git clone <repository-url>
cd ai-proxy
npm install
npm run build

Development Workflow

Command	Description
npm install	Install all dependencies
npm run build	Compile TypeScript to JavaScript (tsc -p tsconfig.build.json)
npm test	Run the test suite with Jest
npm run coverage	Run tests with coverage reporting
npm run lint	Lint source files with ESLint
npm run format	Format code with Prettier
npm run prepare	Build the project (runs automatically on npm install via prepare lifecycle hook)

Testing Guidelines

Test Framework

Tests use Jest with ts-jest for TypeScript support in ESM mode. The configuration is defined in jest.config.ts.

Database Testing

All DatabaseStore tests use an in-memory database (:memory:) created in beforeEach to ensure isolation between test cases.

Mocking Strategy

• Mock AI API Server: A lightweight HTTP server implementing /v1/chat/completions and other endpoints, supporting both streaming and non-streaming responses.
• Mock Agent Client: A script that sends HTTP requests to the proxy as if it were the AI API.
• Proxy Under Test: Started as a separate process (or in-process with a random port) using the mock API server as its --target and a temporary SQLite database file.

Coverage Thresholds

The project enforces the following global coverage thresholds (configured in jest.config.ts):

Metric	Threshold
Branches	90%
Functions	90%
Lines	90%
Statements	90%

Run npm run coverage to generate coverage reports in coverage/ (JSON summary and text summary formats).

AI Usage in Development

This project was developed using an AI-assisted workflow that combines system design and code generation.

Tools

• Visual Studio Code — primary editor with Cline (and its fork Dirac) as the coding agent interface.
• DeepSeek — used via API and through open-weights models hosted by providers such as NVIDIA and HuggingFace.

Key Files

• technical-specification.md — the complete system design specification that drives all implementation. It contains component interfaces, database schema, data flow diagrams, and a full testing plan.
• instantiate.md — the prompt that instructs the coding agent to produce the full npm package from the specification, including project setup, linting, formatting, testing, and coverage requirements.

Specification Creation

The technical-specification.md was generated iteratively using an "Interactive System Design Agent" prompt (reproduced in system-design-agent.md). This prompt enables a conversational design loop where the agent asks clarifying questions, proposes improvements, and produces the specification, architecture diagrams, sequence diagrams, and testing plan in a structured format.

Development Loop

The workflow follows a two-phase cycle: first, the specification is refined with the design agent until all details are aligned. Then the final specification is handed to a coding agent (via Cline/Dirac) which generates the full package, runs tests, and ensures the 90% coverage thresholds are met.

Model Hosting

Open-weights DeepSeek models can be run via US-based inference endpoints (e.g., NVIDIA NIM, HuggingFace Inference Endpoints) for lower latency or data residency requirements.

Contributing

1. Stick to the technical specification — the project has a detailed specification in technical-specification.md. All implementations must conform to the documented interfaces, schemas, and behaviors.
2. Follow the linting and formatting setup — run npm run lint and npm run format before committing. The project uses ESLint with @typescript-eslint rules and Prettier with semi: true, singleQuote: true, and trailingComma: "all".
3. Ensure tests pass and coverage thresholds are met — run npm run coverage and verify that all tests pass and the 90% coverage thresholds (branches, functions, lines, statements) are satisfied before committing.