claude-central-gateway/docs/code-standards.md

# Code Standards & Architecture

## Codebase Structure

```
src/
├── index.js                    # Hono app entry point, middleware setup
├── auth-middleware.js          # Authentication logic, timing-safe comparison
├── openai-client.js            # Cached OpenAI client, model mapping
├── transform-request.js        # Anthropic → OpenAI request transformation
├── transform-response.js       # OpenAI → Anthropic response streaming
└── routes/
    └── messages.js             # POST /v1/messages handler
```

## Module Responsibilities

### index.js
- Creates Hono application instance
- Registers middleware (logging, CORS)
- Mounts auth middleware for `/v1/*` routes
- Registers message routes
- Handles 404 and error cases

### auth-middleware.js
- **timingSafeEqual()**: Constant-time string comparison using byte-level XOR
  - Works cross-platform: Node.js 18+, Cloudflare Workers, Deno, Bun
  - No dependency on native crypto module (cross-platform safe)
  - Takes two strings, returns boolean

- **authMiddleware()**: Hono middleware factory
  - Extracts token from `x-api-key` header or `Authorization: Bearer`
  - Compares against `GATEWAY_TOKEN` env var using timing-safe comparison
  - Returns 401 if missing or invalid
  - Returns 500 if GATEWAY_TOKEN not configured

### openai-client.js
- Creates and caches OpenAI client instance
- Handles model name mapping via `MODEL_MAP` env var
- Format: `claude-sonnet-4:gpt-4o,claude-3-opus:gpt-4-turbo`
- Falls back to model name from request if no mapping found

### transform-request.js
Converts Anthropic Messages API request format → OpenAI Chat Completions format.

**Main export: buildOpenAIRequest(anthropicRequest, model)**
- Input: Anthropic request object + mapped model name
- Output: OpenAI request payload (plain object, not yet stringified)

**Key transformations:**
- `max_tokens`, `temperature`, `top_p`: Pass through unchanged
- `stream`: If true, sets `stream: true` and `stream_options: { include_usage: true }`
- `stop_sequences`: Maps to OpenAI `stop` array parameter
- `tools`: Converts Anthropic tool definitions to OpenAI `tools` array with `type: 'function'`
- `tool_choice`: Maps Anthropic tool_choice enum to OpenAI tool_choice format
- `system`: Handles both string and array of text blocks
- `messages`: Transforms message array with special handling for content types

**Message transformation details:**
- **User messages**: Handles text, images, and tool_result blocks
  - Images: base64 and URL sources supported, converted to `image_url` format
  - tool_result blocks: Split into separate tool messages (OpenAI format)
  - Text content: Preserved in order

- **Assistant messages**: Handles text and tool_use blocks
  - tool_use blocks: Converted to OpenAI tool_calls format
  - Text content: Merged into `content` field
  - Result: Single message with optional `tool_calls` array

**Implementation notes:**
- System message: Joins array blocks with `\n\n` separator
- tool_result content: Supports string or array of text blocks; prepends `[ERROR]` if `is_error: true`
- Filters out unsupported blocks (thinking, cache_control, etc.)

### transform-response.js
Converts OpenAI Chat Completions responses → Anthropic Messages API format.

**Exports:**
- **transformResponse(openaiResponse, anthropicRequest)**: Non-streaming response conversion
  - Input: OpenAI response object, original Anthropic request
  - Output: Anthropic message response object with `id`, `type`, `role`, `content`, `stop_reason`, `usage`

- **streamAnthropicResponse(c, openaiStream, anthropicRequest)**: Streaming response handler
  - Input: Hono context, async iterable of OpenAI chunks, original Anthropic request
  - Outputs: Server-sent events in Anthropic SSE format
  - Emits: `message_start` → content blocks → `message_delta` → `message_stop`

**Response building:**
- **Content blocks**: Anthropic format uses array of content objects with `type` field
  - `text`: Standard text content
  - `tool_use`: Tool calls with `id`, `name`, `input` (parsed JSON object)

**Stop reason mapping:**
- `finish_reason: 'stop'` → `'end_turn'` (or `'stop_sequence'` if stop_sequences were used)
- `finish_reason: 'length'` → `'max_tokens'`
- `finish_reason: 'tool_calls'` → `'tool_use'`
- `finish_reason: 'content_filter'` → `'end_turn'`

**Streaming behavior:**
1. Sends `message_start` event with empty content array
2. For text delta: Sends `content_block_start`, then `content_block_delta` events
3. For tool_calls delta: Sends `content_block_start`, then `content_block_delta` with `input_json_delta`
4. Tracks text and tool blocks separately to avoid mixing in output
5. Closes blocks before transitioning between text and tool content
6. Captures usage from final chunk (requires `stream_options.include_usage`)
7. Sends `message_delta` with stop_reason and output tokens
8. Sends `message_stop` to mark stream end

**Implementation notes:**
- Tool call buffering: Accumulates arguments across multiple chunks before outputting deltas
- Block indexing: Separate indices for text blocks (0-n) and tool blocks (offset by text count)
- Tool result content extraction: Handles string or text-block-array formats

### routes/messages.js
HTTP handler for `POST /v1/messages`.

**Request flow:**
1. Extract `model` from body
2. Map model name via `openai-client`
3. Build OpenAI request via `transform-request`
4. If streaming: Use `streamAnthropicResponse()`, set `Content-Type: text/event-stream`
5. If non-streaming: Transform response via `transformResponse()`

**Error handling:**
- Catches OpenAI API errors, returns formatted Anthropic error response
- Catches transform errors, returns 400 Bad Request

## Naming Conventions

### Functions
- **camelCase**: `buildOpenAIRequest`, `timingSafeEqual`, `transformMessages`
- **Descriptive verbs**: build, transform, map, extract, handle
- **Prefixes for private functions**: None (all functions are internal to modules)

### Variables
- **camelCase**: `messageId`, `toolCallBuffers`, `inputTokens`
- **Constants**: UPPERCASE with underscores for env vars only (`GATEWAY_TOKEN`, `OPENAI_API_KEY`, `MODEL_MAP`)
- **Booleans**: Prefix with `is`, `had`, `should`: `isError`, `hadStopSequences`, `textBlockStarted`

### Files
- **kebab-case with descriptive names**: `auth-middleware.js`, `transform-request.js`, `transform-response.js`
- **Purpose clear from name**: No abbreviations

## Error Handling

### Authentication Failures
- 401 Unauthorized: Invalid or missing token
- 500 Internal Server Error: GATEWAY_TOKEN not configured

### API Errors
- Forward OpenAI errors to client in Anthropic error format
- Log error details for debugging
- Return 500 for unexpected errors

### Transform Errors
- Catch JSON parsing errors (tool arguments)
- Provide fallback values (empty objects, empty strings)
- Log parsing failures with context

## Security Practices

1. **Timing-Safe Authentication**: `timingSafeEqual()` prevents timing attacks
2. **Header Validation**: Checks both `x-api-key` and `Authorization` headers
3. **Token Comparison**: Constant-time comparison regardless of token length
4. **No Logging of Sensitive Data**: Auth tokens not logged

## Testing Strategy

### Unit Tests (Recommended)
- Test transformations with sample Anthropic/OpenAI payloads
- Test edge cases: empty messages, tool calls without text, images only
- Test error scenarios: malformed JSON, missing required fields
- Test utility functions: `timingSafeEqual`, `mapStopReason`

### Integration Tests (Recommended)
- Mock OpenAI API responses
- Test full request/response cycle with streaming and non-streaming
- Test model mapping

### Manual Testing
- Deploy to Vercel/Cloudflare and test with Claude Code
- Verify streaming works correctly
- Test tool use workflows (request → tool_use → tool_result → response)

## Performance Considerations

1. **Client Caching**: OpenAI client created once and reused
2. **Streaming Efficiency**: Response streamed directly from OpenAI to client (no buffering)
3. **String Operations**: Minimal string concatenation, uses joins for system message
4. **JSON Parsing**: Lazy parsed only when needed (tool arguments)

## Compatibility Notes

- **Runtime**: Works on Node.js 18+, Cloudflare Workers, Deno, Bun (via Hono)
- **APIs**: Uses standard JavaScript TextEncoder (not Node.js crypto for auth)
- **Framework**: Hono provides multi-platform support, no custom server implementation

## Code Quality Standards

1. **No External Dependencies**: Only Hono for framework (included in package.json)
2. **Readable Over Clever**: Prefer explicit logic over compact code
3. **Comments for Non-Obvious Logic**: Transformation rules, SSE event sequencing
4. **Self-Documenting Names**: Function names describe purpose, no abbreviations
5. **Modular Structure**: Single responsibility per file