# justlovemaki/gemini-cli-2-api architecture

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

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

## Overview

##### Project Type and Purpose
- This is a backend‐only Node.js proxy service that wraps the Google Gemini CLI and exposes both the native Gemini API (v1beta) and an OpenAI‐compatible API (v1) over HTTP.
- Its goal is to let any client (e.g., curl, LobeChat, NextChat, VS Code plugin) talk to Gemini as if it were a local OpenAI‐style REST API, handling OAuth, token refresh, request/response translation, streaming, logging, and API‐key validation.

##### File Structure Analysis
- Only two JS files in the root:
- gemini-api-server.js – the entry point, HTTP server, request router, CLI invocation orchestration, OpenAI‐ and Gemini‐path handlers, CLI flags, logging setup.
- gemini-core.js – the “heart” module: auth flow, token store, CLI or Google Cloud API invocation, format‐conversion between OpenAI↔Gemini, prompt log writer, streaming.
- package.json + package-lock.json define dependencies (`google-auth-library`, `uuid`) and set `"type":"module"`.
- No database or frontend; everything runs in one Node.js process**.

##### Key Architecture Insights from README
- Single HTTP server listens on configurable host/port.
- Supports three API‐key modes: bearer token, query param, `x-goog-api-key`.
- OAuth token storage on disk, auto‐refresh.
- Two logical API layers:
- /v1/... for OpenAI compatibility (models, chat/completions, streaming)
- /v1beta/... for native Gemini (listModels, generateContent, streamGenerateContent)
- Logging subsystem captures and persists prompts.
- Extensibility hooks: system‐prompt injection, caching, filtering.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients
    Clients["Clients\n(curl, LobeChat,\nVS Code plugin)"]:::client

    %% Storage
    TokenStore["Token Store\n(disk)"]:::storage
    LogFile["Log File\n(disk)"]:::storage

    %% External Services
    subgraph "External Services"
        GoogleOAuth["Google OAuth\nEndpoint"]:::external
        GeminiCloud["Google Cloud\nGemini API"]:::external
        GeminiCLI["Gemini CLI\nSubprocess"]:::external
    end

    %% API Server
    subgraph "API Server\n(gemini-api-server.js)" 
        HTTPServer["HTTP Server\n(v1 & v1beta Routes)"]:::internal
        LoggingSetup["Logging Setup"]:::internal
    end

    %% Core Modules
    subgraph "Core Logic Module\n(gemini-core.js)"
        AuthManager["Auth Manager &\nToken Refresh"]:::internal
        Translator["Request/Response\nTranslator"]:::internal
        APIInvoker["Gemini CLI/API\nInvoker"]:::internal
        CoreLogger["Prompt Log Writer"]:::internal
    end

    %% Documentation & Config
    subgraph "Project Files"
        PackageJSON["package.json"]:::config
        README["README.md"]:::doc
        License["LICENSE"]:::doc
        Gitignore[".gitignore"]:::doc
    end

    %% Data Flow
    Clients --> HTTPServer
    HTTPServer --> AuthManager
    AuthManager --> TokenStore
    AuthManager --> GoogleOAuth
    HTTPServer --> Translator
    Translator --> APIInvoker
    APIInvoker -->|CLI| GeminiCLI
    APIInvoker -->|HTTP| GeminiCloud
    APIInvoker --> Translator
    Translator --> HTTPServer
    HTTPServer --> Clients

    %% Logging Flow
    HTTPServer --> LoggingSetup
    AuthManager --> CoreLogger
    Translator --> CoreLogger
    APIInvoker --> CoreLogger
    CoreLogger --> LogFile

    %% Documentation Links
    HTTPServer --> PackageJSON
    HTTPServer --> README
    HTTPServer --> License
    HTTPServer --> Gitignore

    %% Click Events
    click HTTPServer "https://github.com/justlovemaki/gemini-cli-2-api/blob/main/gemini-api-server.js"
    click LoggingSetup "https://github.com/justlovemaki/gemini-cli-2-api/blob/main/gemini-api-server.js"
    click AuthManager "https://github.com/justlovemaki/gemini-cli-2-api/blob/main/gemini-core.js"
    click Translator "https://github.com/justlovemaki/gemini-cli-2-api/blob/main/gemini-core.js"
    click APIInvoker "https://github.com/justlovemaki/gemini-cli-2-api/blob/main/gemini-core.js"
    click CoreLogger "https://github.com/justlovemaki/gemini-cli-2-api/blob/main/gemini-core.js"
    click PackageJSON "https://github.com/justlovemaki/gemini-cli-2-api/blob/main/package.json"
    click README "https://github.com/justlovemaki/gemini-cli-2-api/blob/main/README.md"
    click License "https://github.com/justlovemaki/gemini-cli-2-api/tree/main/LICENSE"
    click Gitignore "https://github.com/justlovemaki/gemini-cli-2-api/blob/main/.gitignore"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef external fill:#E6FFED,stroke:#28A745,stroke-width:1px
    classDef storage fill:#FFF5D1,stroke:#C58600,stroke-width:1px
    classDef client fill:#F0E6FF,stroke:#794BC4,stroke-width:1px
    classDef config fill:#E8F1FF,stroke:#0366D6,stroke-width:1px
    classDef doc fill:#FFF0F0,stroke:#D73A49,stroke-width:1px
```
