# ghchinoy/gen architecture

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

- Interactive diagram: https://gitdiagram.com/ghchinoy/gen
- Repository: https://github.com/ghchinoy/gen

## Overview

##### Project type and purpose
- Type: Command-line application (CLI) written in Go.
- Purpose: Expose a `gen` command with subcommands (`prompt`, `tokens`, `interactive`, `version`, etc.) to call Google Cloud’s Vertex AI Generative AI models (Gemini, PaLM) and Model Garden models (Anthropic’s Claude, etc.), manage config, and display results.

##### File structure
- Top-level files
– `main.go`: Instantiates and runs the root Cobra command.
– `go.mod`/`go.sum`: Go module definitions and dependencies.
– `README.md`, `LICENSE`, `.gitignore`: Project metadata.
- Directories
– `internal/cmd`: Implements the CLI commands using Cobra (root.go, prompt/interactive/tokens/version commands, flags, help text).
– `internal/model`: Defines model-specific wrappers and interfaces (Gemini, PaLM, Anthropic), model selection logic, request/response types, config schemas.
– `media`: Example GIF for README; not part of runtime.
- Scripts
– `makedist`: Build/release helper.

##### Extract architecture from README
- Usage patterns:
– Single-shot `gen prompt` calls.
– Token counting via `gen tokens`.
– Interactive REPL mode.
– Model-parameterization via `--model` and `--config` flags.
- Dependencies & flow:
– Standard Google Cloud auth (ADC).
– HTTP/REST or gRPC calls to Vertex AI endpoint.
– Optional JSON file input/output.

##### Main components
a. User Interface (CLI):
– STDIN (user types commands) / STDOUT (console output)
– `main.go` → Cobra root & subcommands (`internal/cmd`)
b. Command Dispatcher & Flag Parser:
– Flag parsing (`--project`, `--region`, `--model`, `--config`, `--output`)
– Subcommands: `prompt`, `tokens`, `interactive`, `version`
c. Model Abstraction Layer:
– `internal/model` interface that selects and configures the correct model client (Gemini, PaLM, Anthropic).
– Config loader (JSON → Go structs)
d. Authentication & Environment:
– Google ADC (env var / gcloud CLI)
– Env vars: `PROJECT_ID`, `REGION`
e. External Services:
– Google Vertex AI Generative API (Gemini, PaLM)
– Model Garden endpoints (Anthropic Claude)
f. Output Formatter:
– Plain text logger
– JSON serialization (if `--output json`)

##### Relationships & data flow
1. User issues `gen prompt "..."`
2. Cobra parses flags and dispatches to `PromptCommand`
3. Command code calls Model Abstraction Layer
4. Abstraction layer reads config, selects model client
5. Model client uses HTTP/gRPC to call Vertex AI / Model Garden
6. Response marshaled back through abstraction → Command → STDOUT

##### Architectural patterns & design principles
- Command pattern (Cobra) for subcommands.
- Adapter/strategy pattern for pluggable model clients.
- Layered separation: CLI → Command logic → Model layer → External API.
- Single Responsibility: each package has a distinct role.

##### Essential elements to capture
- Clear component names matching directory/package names.
- Notes on flags/env vars that affect routing (project/region/model/config).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% gen CLI Entry
    CLI["gen CLI"]:::internal
    click CLI "https://github.com/ghchinoy/gen/blob/main/main.go"

    %% CLI Layer
    subgraph "CLI Layer"
        Root["Cobra Root Command"]:::internal
        click Root "https://github.com/ghchinoy/gen/blob/main/internal/cmd/root.go"
        Parser["Command Parser Utilities"]:::internal
        click Parser "https://github.com/ghchinoy/gen/blob/main/internal/cmd/cmd.go"
        subgraph "Subcommand Handlers"
            Prompt["prompt"]:::internal
            click Prompt "https://github.com/ghchinoy/gen/blob/main/internal/cmd/prompt.go"
            Tokens["tokens"]:::internal
            click Tokens "https://github.com/ghchinoy/gen/blob/main/internal/cmd/tokens.go"
            Interactive["interactive"]:::internal
            click Interactive "https://github.com/ghchinoy/gen/blob/main/internal/cmd/interactive.go"
            Version["version"]:::internal
            click Version "https://github.com/ghchinoy/gen/blob/main/internal/cmd/version.go"
            ModelsFlag["model flags"]:::internal
            click ModelsFlag "https://github.com/ghchinoy/gen/blob/main/internal/cmd/models.go"
        end
    end

    %% Model Abstraction Layer
    subgraph "Model Abstraction Layer"
        Interface["Base Model Interfaces"]:::internal
        click Interface "https://github.com/ghchinoy/gen/blob/main/internal/model/meta.go"
        Registry["Model Registry/Selection"]:::internal
        click Registry "https://github.com/ghchinoy/gen/blob/main/internal/model/catalog.go"
        ConfigLoader["Config Loader"]:::config
        click ConfigLoader "https://github.com/ghchinoy/gen/blob/main/internal/model/config.go"
        subgraph "Model Clients"
            Gemini["Gemini Client"]:::internal
            click Gemini "https://github.com/ghchinoy/gen/blob/main/internal/model/gemini.go"
            PaLM["PaLM Client"]:::internal
            click PaLM "https://github.com/ghchinoy/gen/blob/main/internal/model/palm.go"
            Anthropic["Anthropic Client"]:::internal
            click Anthropic "https://github.com/ghchinoy/gen/blob/main/internal/model/anthropic.go"
            ExtraModels["Additional Models"]:::internal
            click ExtraModels "https://github.com/ghchinoy/gen/tree/main/internal/model/models/"
        end
    end

    %% Auth and Config
    Auth["Auth Provider\n(Google ADC)"]:::config

    %% External Services
    subgraph "External Services"
        VertexAI["Google Vertex AI"]:::external
        ModelGarden["Model Garden (Anthropic)"]:::external
    end

    %% Supporting files
    Makedist["makedist script"]:::internal
    click Makedist "https://github.com/ghchinoy/gen/tree/main/makedist"
    Media["media (examples)"]:::external
    click Media "https://github.com/ghchinoy/gen/tree/main/media/"

    %% Data Flow
    CLI -->|"invoke command"| Root
    Root --> Parser
    Parser --> SubcommandHandlers
    SubcommandHandlers -->|"Prompt + Params"| Interface
    SubcommandHandlers -->|"Token Request"| Interface
    SubcommandHandlers -->|"Interactive Input"| Interface
    Interface --> Registry
    ConfigLoader --> Registry
    Registry --> Gemini
    Registry --> PaLM
    Registry --> Anthropic
    Registry --> ExtraModels
    Gemini -->|"HTTP/gRPC"| VertexAI
    PaLM -->|"HTTP/gRPC"| VertexAI
    Anthropic -->|"HTTP Request"| ModelGarden
    Auth --> VertexAI
    Auth --> ModelGarden
    VertexAI -->|"Response JSON"| SubcommandHandlers
    ModelGarden -->|"Response JSON"| SubcommandHandlers
    SubcommandHandlers -->|"Formatted Output"| CLI

    %% Styles
    classDef internal fill:#D0E7FF,stroke:#0288D1,stroke-width:1px
    classDef config fill:#DFFFE0,stroke:#388E3C,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#F57C00,stroke-width:1px
```
