How justlovemaki/aiclient-2-api works
Project Type and Purpose
• This is a backend Node.js HTTP API proxy service (“AIClient-2-API”) that exposes an OpenAI-compatible interface and internally routes requests to multiple large-model providers (OpenAI, Gemini, Claude, Kiro). It is not a full-stack web app, but rather a middleware service with a modular, strategy-and-adapter-based architecture.
File-Structure Analysis
• Top-Level Files
• Dockerfile, run-docker.sh/.bat, README*.md, package.json → deployment & docs
• babel, jest configs → build & test setup
• healthcheck.js → custom health-endpoint logic
• src/
• api-server.js → HTTP server entry point
• adapter.js → ApiServiceAdapter factory & singleton cache
• provider-strategy.js → abstract Strategy base class
• provider-strategies.js → Strategy factory & registry
• convert.js → bidirectional protocol-format conversion
• common.js → shared constants & utilities
• claude/, gemini/, openai/ → per-provider implementations (core + strategy)
• tests/ → integration tests against all main API routes
README Insights
• Modules employ Adapter, Strategy, Factory, Singleton patterns
• Seven-step request pipeline: receive → auth → protocol identify → convert → service call → convert back → response
• Health check endpoint, pluggable logging, config.json-driven
A. Entry Point
• Node.js HTTP Server (src/api-server.js).
• Routes: /health, /v1/*, /v1beta/*, /<provider>/v1/* endpoints.
B. Authentication Layer
• Validate API key (config.json / headers & query).
• Health check bypass or info.
C. Protocol Identification
• Client protocol (OpenAI / Gemini / Claude) based on URL prefix or headers.
D. Conversion Engine (src/convert.js)
• Request converter: transforms incoming format → target-provider payload.
• Response converter: reverse.
E. Strategy Factory (src/provider-strategies.js + provider-strategy.js)
• Instantiates correct Strategy (openai-custom, gemini-cli-oauth, claude-custom, claude-kiro-oauth).
• Strategy implements parsing of prompts, parameter extraction, response normalization.
F. Service Adapters (src/adapter.js)
• ApiServiceAdapter instances call external provider SDK/HTTP (OpenAI API, Gemini CLI, Anthropic Claude, Kiro).
• Singleton cache for reuse.
G. External Model Providers
• OpenAI
• Google Gemini CLI (OAuth)
• Anthropic Claude
• Claude-Kiro OAuth
H. Logging & Health
• Prompt log subsystem (console or file) tapped in convert or adapter layer.
• healthcheck.js / /health route returns current config + status.
• Client → HTTP Server
• → Auth Layer
• → Protocol Identifier
• → Conversion Engine (incoming)
• → Strategy Factory → Strategy Instance
• → Adapter → External Service
• ← Response from External Service
• → Strategy → Conversion Engine (outgoing)
• → HTTP Server → Client
• Side path: Logging component subscribes to both request/response payloads.
Architectural Patterns & Tech
• Adapter Pattern: service-specific API calls are encapsulated in ApiServiceAdapter.
• Strategy Pattern: provider-specific request/response logic in Strategy classes.
• Factory Pattern: provider-strategies.js picks and instantiates strategies.
• Singleton: adapter.js caches adapter instances.
• Modules: ES modules ({"type":"module"} in package.json).
• Test Harness: jest.config.js drives integration tests in tests/.