# rohitaryal/imagefx-api architecture

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

- Interactive diagram: https://gitdiagram.com/rohitaryal/imagefx-api
- Repository: https://github.com/rohitaryal/imagefx-api

## Overview

##### Project type and purpose
- This is an open-source, Node.js/TypeScript SDK + CLI wrapper (“imagefx”) for Google’s private ImageFX (Imagen) API.
- It exposes both a programmatic interface (ImageFX class, Prompt, Image, etc.) and a command-line interface (CLI entrypoint `src/cli.ts`).

##### File structure
- Top level:
- src/ – core TS source files
– index.ts        → exports public API (ImageFX)
– cli.ts          → CLI entrypoint, command parsing with Commander/Yargs
– Account.ts      → handles cookie/auth management
– Prompt.ts       → builds generation requests (seed, model, size)
– Image.ts, ImageFX.ts → models Image instances and core client logic
– Constants.ts, Types.ts → enum definitions and shared types
- examples/ – usage examples of both module and CLI
- tests/    – unit tests mapped to src modules
- .github/workflows – CI/CD (release, tests)
- package.json, tsconfig.json – build & packaging config

##### Key insights from README
- Exposes three major capabilities:
a) generate images from text
b) generate captions from existing images
c) fetch previously generated images by media ID
- Authentication via environment variable `GOOGLE_COOKIE`
- Offers both CLI commands (`imagefx generate`, `caption`, `fetch`) and JS/TS module API (`new ImageFX(cookie)`, `.generateImage()`, `.caption()`, etc.).

##### Main components & their interactions
a. CLI Layer
– Parses user commands/flags (prompts, model, count, size).
– Instantiates ImageFX core client.
– Calls appropriate method (`generateImage`, `caption`, `fetchMedia`).
b. Core Library Layer
– ImageFX class
- Holds auth cookie
- Exposes async methods: generateImage(promptOrString), caption(imagePath), fetch(mediaId)
– Account module (Account.ts)
- Manages cookie header, token refresh if needed
– Prompt module (Prompt.ts)
- Builds typed request objects (seed, count, model, aspect ratio)
– Image and ImageFX model classes
- Wrap response data: media ID, binary data, metadata
- Provide `.save(dir)` to write files to disk
c. HTTP Client / Network Layer
– Under the hood, ImageFX methods issue HTTP requests to labs.google/fx endpoints.
– Handles retries, error handling.
d. External Service
– Google ImageFX API (private endpoints)
e. Filesystem
– Local disk for saving images.

##### Architectural patterns/design principles
- Single-process, modular design
- Separation of concerns:
- CLI parsing vs. core logic
- Request-building (Prompt) vs. network I/O (ImageFX) vs. persistence (Image.save)
- Typed interfaces and models (Types.ts, Constants.ts for enums)
- Layered architecture: CLI → Core client → HTTP → External API → File I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing Layer
    subgraph "User-Facing Layer"
        direction TB
        User["User"]:::user
        CLI["CLI Interface"]:::user
        Examples["Usage Examples"]:::user
    end

    %% Core Library Layer
    subgraph "Core Library Layer"
        direction TB
        Index["Public API Entry Point (index.ts)"]:::core
        ImageFX["ImageFX Core Client"]:::core
        Prompt["Prompt Builder"]:::core
        Account["Account/Auth Manager"]:::core
        Types["Shared Types"]:::core
        Constants["Shared Enums"]:::core
    end

    %% HTTP & Network Layer
    subgraph "Network Layer"
        direction TB
        HTTPClient["HTTP Client"]:::network
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleAPI["Google ImageFX API"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        FileSystem["Local File System"]:::infra
        Tests["Unit Tests"]:::infra
        CI["CI/CD (GitHub Actions)"]:::infra
        EnvVar["GOOGLE_COOKIE\n(env var)"]:::infra
    end

    %% Relationships
    User -->|"runs command"| CLI
    User -->|"reads code"| Examples
    CLI -->|"import & call"| Index
    Index -->|"exports class"| ImageFX
    CLI -->|" invokes methods"| ImageFX
    ImageFX -->|"attach cookie"| Account
    EnvVar -->|"provides token"| Account
    ImageFX -->|"build payload"| Prompt
    ImageFX -->|"send request"| HTTPClient
    HTTPClient -->|"POST/GET"| GoogleAPI
    GoogleAPI -->|"response data"| HTTPClient
    HTTPClient -->|"wrap response"| ImageModel
    subgraph "Image Model & File I/O"
        direction TB
        ImageModel["Image Model"]:::core
        ImageModel -->|"save()"| FileSystem
    end
    Examples -->|"use API"| Index
    Tests -.->|"test modules"| Index
    Tests -.->|"test modules"| ImageFX
    Tests -.->|"test modules"| Account
    Tests -.->|"test modules"| Prompt
    Tests -.->|"test modules"| ImageModel
    CI -->|"runs"| Tests

    %% Click Events
    click CLI "https://github.com/rohitaryal/imagefx-api/blob/main/src/cli.ts"
    click ImageFX "https://github.com/rohitaryal/imagefx-api/blob/main/src/ImageFX.ts"
    click Prompt "https://github.com/rohitaryal/imagefx-api/blob/main/src/Prompt.ts"
    click Account "https://github.com/rohitaryal/imagefx-api/blob/main/src/Account.ts"
    click HTTPClient "https://github.com/rohitaryal/imagefx-api/blob/main/src/ImageFX.ts"
    click ImageModel "https://github.com/rohitaryal/imagefx-api/blob/main/src/Image.ts"
    click Types "https://github.com/rohitaryal/imagefx-api/blob/main/src/Types.ts"
    click Constants "https://github.com/rohitaryal/imagefx-api/blob/main/src/Constants.ts"
    click Index "https://github.com/rohitaryal/imagefx-api/blob/main/src/index.ts"
    click Examples "https://github.com/rohitaryal/imagefx-api/tree/main/examples/"
    click Tests "https://github.com/rohitaryal/imagefx-api/tree/main/tests/"

    %% Styles
    classDef user fill:#cce5ff,stroke:#1f78b4,color:#000;
    classDef core fill:#d4edda,stroke:#2e7d32,color:#000;
    classDef network fill:#fff3cd,stroke:#ff9800,color:#000;
    classDef external fill:#ffe5e5,stroke:#d32f2f,color:#000;
    classDef infra fill:#e0e0e0,stroke:#616161,color:#000;
```
