claude-central-gateway/docs/project-overview-pdr.md

# Claude Central Gateway - Project Overview & PDR

## Project Overview

Claude Central Gateway is a lightweight proxy service that routes Claude API requests to OpenAI's API, enabling cost optimization by using cheaper third-party providers. Built for personal and small-scale use, it emphasizes simplicity, minimal resource consumption, and multi-platform deployment.

**Repository:** https://github.com/tiennm99/claude-central-gateway

## Core Value Proposition

- **Cost Efficiency**: Route Claude API calls through cheaper OpenAI providers
- **Deployment Flexibility**: Run on Vercel, Cloudflare Workers, Node.js, or any Hono-compatible platform
- **Zero Complexity**: Minimal code, easy to understand, easy to fork and customize
- **Full Feature Support**: Streaming, tool use/tool result round-trips, images, system arrays

## Target Users

- Individual developers using Claude Code
- Small teams with tight LLM budgets
- Users seeking provider flexibility without enterprise complexity

## Non-Goals

- **Enterprise features**: GUI management, advanced routing, rate limiting, load balancing
- **GUI-based administration**: Focus remains on environment variable configuration
- **Multi-tenant support**: Designed for single-user or small-team deployment
- **Complex feature request routing**: Simple model mapping only

## Product Development Requirements (PDR)

### Functional Requirements

| ID | Requirement | Status | Priority |
|----|-------------|--------|----------|
| FR-1 | Accept Anthropic Messages API requests at `/v1/messages` | Complete | P0 |
| FR-2 | Transform Anthropic requests to OpenAI Chat Completions format | Complete | P0 |
| FR-3 | Forward requests to OpenAI API and stream responses back | Complete | P0 |
| FR-4 | Support tool_use and tool_result message handling | Complete | P0 |
| FR-5 | Support image content (base64 and URLs) | Complete | P0 |
| FR-6 | Support system messages as string or array of text blocks | Complete | P0 |
| FR-7 | Authenticate requests with x-api-key header | Complete | P0 |
| FR-8 | Map stop_reason correctly (end_turn, max_tokens, tool_use, stop_sequence) | Complete | P0 |
| FR-9 | Forward stop_sequences and map to OpenAI stop parameter | Complete | P0 |
| FR-10 | Return usage token counts in responses | Complete | P0 |

### Non-Functional Requirements

| ID | Requirement | Status | Priority |
|----|-------------|--------|----------|
| NFR-1 | Support streaming with proper SSE Content-Type headers | Complete | P0 |
| NFR-2 | Timing-safe authentication comparison (prevent timing attacks) | Complete | P0 |
| NFR-3 | Cross-platform runtime support (Node.js, Cloudflare Workers, Deno, Bun) | Complete | P0 |
| NFR-4 | Minimal bundle size and resource consumption | Complete | P0 |
| NFR-5 | CORS support for browser-based clients | Complete | P1 |
| NFR-6 | Request logging for debugging | Complete | P1 |

### Architecture Requirements

- Modular structure with separated concerns (auth, transformation, routing)
- Stateless design for horizontal scaling
- No external dependencies beyond Hono and built-in APIs
- Configuration via environment variables only (no config files)

### Acceptance Criteria

- All Claude Code requests successfully proxied through OpenAI without client-side changes
- Tool use workflows complete successfully (request → tool_use → tool_result)
- Streaming responses match Anthropic SSE format exactly
- Authentication prevents unauthorized access
- Service deploys successfully on Vercel and Cloudflare Workers
- Zero security vulnerabilities in authentication

## Technical Constraints

- **Language**: JavaScript/Node.js
- **Framework**: Hono (lightweight, multi-platform)
- **API Standards**: Anthropic Messages API ↔ OpenAI Chat Completions API
- **Deployment**: Serverless platforms (Vercel, Cloudflare Workers, etc.)
- **Auth Model**: Single shared token (GATEWAY_TOKEN), suitable for personal use only

## Feature Roadmap

### Phase 1: Core Gateway (Complete)
- Basic message proxying
- Authentication
- Streaming support
- Model mapping

### Phase 2: Tool Support (Complete)
- Tool definition forwarding
- Tool use/tool result round-trips
- Tool choice mapping

### Phase 3: Content Types (Complete)
- Image support (base64, URLs)
- System message arrays
- Stop sequences

### Phase 4: Observability (Future)
- Detailed request logging
- Error tracking
- Usage analytics

### Phase 5: Advanced Features (Deferred)
- Model fallback/routing
- Rate limiting per token
- Request queuing
- Webhook logging

## Success Metrics

1. **Adoption**: GitHub stars, forks, real-world usage reports
2. **Reliability**: 99.9% uptime on test deployments
3. **Performance**: Response latency within 5% of direct OpenAI API
4. **Correctness**: All Anthropic API features work identically through proxy
5. **Code Quality**: Minimal security vulnerabilities, high readability

## Known Limitations

- **Single token**: No per-user authentication; all requests share one token
- **No rate limiting**: Susceptible to abuse if token is exposed
- **Basic error handling**: Limited error recovery strategies
- **Model mapping only**: Cannot route to different providers based on request properties
- **No request inspection**: Cannot log or analyze request content

## Alternatives & Positioning

### vs. Local Proxies (Claude Code Router)
- **Advantage**: Multi-machine support, instant deployment
- **Disadvantage**: Requires server infrastructure

### vs. Enterprise Solutions (LiteLLM)
- **Advantage**: Minimal resources, easier to understand and fork
- **Disadvantage**: No advanced routing, rate limiting, or team features

### vs. Direct API (No Proxy)
- **Advantage**: Cost savings through provider flexibility
- **Disadvantage**: Adds latency, complexity

## Development Standards

- Code follows modular, single-responsibility design
- All transformations use standard JavaScript APIs (no polyfills)
- Error handling covers common failure modes
- Security practices: timing-safe comparisons, header validation

## References

- **README**: Basic setup and deployment instructions
- **Code Standards**: Architecture, naming conventions, testing practices
- **System Architecture**: Detailed component interactions and data flow