# justlovemaki/aiclient-2-api architecture

> Architecture diagram of the GitHub repository justlovemaki/aiclient-2-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/justlovemaki/aiclient-2-api
- Repository: https://github.com/justlovemaki/aiclient-2-api

## Overview

##### 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/.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Edge (HTTP Layer)
    subgraph "Edge (HTTP Layer)"
        Server["HTTP Server\nsrc/api-server.js"]:::http
        Health["Health Check Endpoint\nhealthcheck.js"]:::http
    end

    %% Core Engine
    subgraph "Core Engine"
        Auth["Authentication Layer"]:::http
        Protocol["Protocol Identification\nsrc/provider-strategies.js"]:::core
        Convert["Conversion Engine\nsrc/convert.js"]:::core
        Factory["Strategy Factory & Registry\nsrc/provider-strategies.js"]:::core
        StrategyBase["Abstract Strategy Base\nsrc/provider-strategy.js"]:::core
    end

    %% Adapters (Singleton)
    subgraph "Adapters (Singleton)"
        Adapter["ApiServiceAdapter\nsrc/adapter.js"]:::adapter
    end

    %% Shared Configuration & Utilities
    Config["Shared Utilities & Configuration\nsrc/common.js"]:::config

    %% External Providers
    subgraph "External Model Providers"
        OpenAI_Core["OpenAI Core Client\nsrc/openai/openai-core.js"]:::external
        OpenAI_Strategy["OpenAI Strategy\nsrc/openai/openai-strategy.js"]:::external
        Gemini_Core["Gemini CLI Core\nsrc/gemini/gemini-core.js"]:::external
        Gemini_Strategy["Gemini Strategy\nsrc/gemini/gemini-strategy.js"]:::external
        Claude_Core["Anthropic Claude Core\nsrc/claude/claude-core.js"]:::external
        Claude_Strategy["Claude Custom Strategy\nsrc/claude/claude-strategy.js"]:::external
        Kiro["Claude-Kiro OAuth Adapter\nsrc/claude/claude-kiro.js"]:::external
    end

    %% Logging & Tests
    subgraph "Auxiliary"
        Log["Logging Subsystem"]:::aux
        Tests["Integration Tests\ntests/api-integration.test.js"]:::aux
    end

    %% Data Flow
    Server --> Auth
    Auth --> Protocol
    Protocol --> Convert
    Convert --> Factory
    Factory --> StrategyBase
    StrategyBase --> Adapter

    Factory --> OpenAI_Strategy
    Factory --> Gemini_Strategy
    Factory --> Claude_Strategy
    Factory --> Kiro

    OpenAI_Strategy --> Adapter
    Gemini_Strategy --> Adapter
    Claude_Strategy --> Adapter
    Kiro --> Adapter

    Adapter --> OpenAI_Core
    Adapter --> Gemini_Core
    Adapter --> Claude_Core

    %% Response Flow
    OpenAI_Core -->|response| Adapter
    Gemini_Core -->|response| Adapter
    Claude_Core -->|response| Adapter
    Adapter --> StrategyBase
    StrategyBase --> Convert
    Convert --> Server

    %% Config Dependencies
    Config --> Server
    Config --> Auth
    Config --> Protocol
    Config --> Factory
    Config --> Adapter

    %% Logging Hooks
    Convert --- Log
    Adapter --- Log

    %% Health & Tests
    Server --> Health
    Health --> Tests

    %% Click Events
    click Server "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/api-server.js"
    click Health "https://github.com/justlovemaki/aiclient-2-api/blob/main/healthcheck.js"
    click Protocol "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/provider-strategies.js"
    click Convert "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/convert.js"
    click Factory "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/provider-strategies.js"
    click StrategyBase "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/provider-strategy.js"
    click Adapter "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/adapter.js"
    click Config "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/common.js"
    click OpenAI_Core "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/openai/openai-core.js"
    click OpenAI_Strategy "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/openai/openai-strategy.js"
    click Gemini_Core "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/gemini/gemini-core.js"
    click Gemini_Strategy "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/gemini/gemini-strategy.js"
    click Claude_Core "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/claude/claude-core.js"
    click Claude_Strategy "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/claude/claude-strategy.js"
    click Kiro "https://github.com/justlovemaki/aiclient-2-api/blob/main/src/claude/claude-kiro.js"
    click Tests "https://github.com/justlovemaki/aiclient-2-api/blob/main/tests/api-integration.test.js"

    %% Styles
    classDef http fill:#f9c6c9,stroke:#333,stroke-width:1px
    classDef core fill:#fde68a,stroke:#333,stroke-width:1px
    classDef adapter fill:#a5b4fc,stroke:#333,stroke-width:1px
    classDef external fill:#6ee7b7,stroke:#333,stroke-width:1px
    classDef config fill:#f0abfc,stroke:#333,stroke-width:1px
    classDef aux fill:#d1d5db,stroke:#333,stroke-width:1px
```
