# charmbracelet/catwalk architecture

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

- Interactive diagram: https://gitdiagram.com/charmbracelet/catwalk
- Repository: https://github.com/charmbracelet/catwalk

## Overview

##### Project type and purpose
- This is an open-source Go application and library called “Catwalk.”
- Purpose: maintain a database of CRUSH-compatible ML model providers.
- It ships as:
- A CLI binary (cmd/openrouter & root main.go)
- A Go client package (pkg/catwalk) for embedding in other tools

##### File structure
- cmd/openrouter
– CLI entrypoint: parses commands, flags, user input
- main.go (root)
– Initializes the Catwalk service (root command, global flags)
- pkg/catwalk
– client.go: primary Client type to query providers
– provider.go: Provider interface
– pkg.go: package-level constructors
- internal/providers
– providers.go: registry loader
– configs/*.json: metadata for each external provider
- go.mod/go.sum + .github/workflows + goreleaser configs
– Go module definition, CI/CD build & release pipelines

##### README for additional insights
- “A database for Crush-compatible models.”

a. Main components
1. CLI Application
- cmd/openrouter
- root main.go
2. Catwalk Client Library
- pkg/catwalk
3. Provider Layer
- internal/providers
- JSON config store
4. External Model Provider APIs
- OpenAI, Anthropic, VertexAI, etc.
- GitHub Actions
- GoReleaser
b. Relationships & interactions
- CLI → invokes → Catwalk Client Library
- Client Library → loads JSON configs → instantiates Providers
- Providers → perform HTTP calls → External APIs
- API responses → mapped to uniform Model metadata → returned up call chain → displayed by CLI
- Push code → CI workflows → build/test → GoReleaser → published binaries
c. Architectural patterns & design principles
- Layered architecture: Presentation (CLI), Domain (client package), Infrastructure (providers + configs), External Services
- Interface-based extensibility: Provider interface + pluggable JSON configs
- Configuration-driven behavior: metadata stored in versioned JSON files
- Single binary distribution with embedded assets
d. Key technologies
- Go (modules, standard library HTTP client)
- JSON (provider metadata)
- GitHub Actions (CI), GoReleaser (CD)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation Layer"
        CLI_dir["cmd/openrouter"]:::code
        CLI_file["cmd/openrouter/main.go"]:::code
        Root_main["main.go"]:::code
    end

    subgraph "Domain Layer"
        CL_dir["pkg/catwalk"]:::code
        Client_go["pkg/catwalk/client.go"]:::code
        Provider_go["pkg/catwalk/provider.go"]:::code
        Pkg_go["pkg/catwalk/pkg.go"]:::code
    end

    subgraph "Provider Layer"
        Prov_dir["internal/providers"]:::code
        Loader["providers.go"]:::code
        subgraph "JSON Config Store"
            JSON_store["configs/*.json\n(anthropic.json, azure.json, bedrock.json, cerebras.json, gemini.json, groq.json, lambda.json, openai.json, openrouter.json, venice.json, vertexai.json, xai.json, zai.json)"]:::config
        end
    end

    subgraph "External Model Provider APIs"
        OpenAI_cloud["OpenAI"]:::external
        Anthropic_cloud["Anthropic"]:::external
        VertexAI_cloud["VertexAI"]:::external
    end

    subgraph "CI/CD & Release Pipeline"
        GH_workflows[".github/workflows"]:::ci
        GoReleaser_yaml[".goreleaser.yaml"]:::ci
        GoReleaser_docker["goreleaser.dockerfile"]:::ci
    end

    CLI_file -->|"invokes"| CL_dir
    Root_main -->|"initializes"| CL_dir
    CL_dir -->|"loads JSON"| Loader
    Loader -->|"load configs"| JSON_store
    Loader -->|"HTTP request"| OpenAI_cloud
    Loader -->|"HTTP request"| Anthropic_cloud
    Loader -->|"HTTP request"| VertexAI_cloud
    OpenAI_cloud -->|"return metadata"| CL_dir
    Anthropic_cloud -->|"return metadata"| CL_dir
    VertexAI_cloud -->|"return metadata"| CL_dir
    CL_dir -->|"return metadata"| CLI_file

    GH_workflows -->|"CI build/test"| GoReleaser_yaml
    GoReleaser_yaml -->|"CD release"| GoReleaser_docker

    click CLI_dir "https://github.com/charmbracelet/catwalk/tree/main/cmd/openrouter"
    click CLI_file "https://github.com/charmbracelet/catwalk/blob/main/cmd/openrouter/main.go"
    click Root_main "https://github.com/charmbracelet/catwalk/blob/main/main.go"
    click CL_dir "https://github.com/charmbracelet/catwalk/tree/main/pkg/catwalk"
    click Client_go "https://github.com/charmbracelet/catwalk/blob/main/pkg/catwalk/client.go"
    click Provider_go "https://github.com/charmbracelet/catwalk/blob/main/pkg/catwalk/provider.go"
    click Pkg_go "https://github.com/charmbracelet/catwalk/blob/main/pkg/catwalk/pkg.go"
    click Prov_dir "https://github.com/charmbracelet/catwalk/tree/main/internal/providers"
    click Loader "https://github.com/charmbracelet/catwalk/blob/main/internal/providers/providers.go"
    click JSON_store "https://github.com/charmbracelet/catwalk/tree/main/internal/providers/configs"
    click GH_workflows "https://github.com/charmbracelet/catwalk/tree/main/.github/workflows"
    click GoReleaser_yaml "https://github.com/charmbracelet/catwalk/blob/main/.goreleaser.yaml"
    click GoReleaser_docker "https://github.com/charmbracelet/catwalk/blob/main/goreleaser.dockerfile"

    classDef code fill:#add8e6,stroke:#333
    classDef config fill:#90ee90,stroke:#333
    classDef external fill:#ffa500,stroke:#333
    classDef ci fill:#d3d3d3,stroke:#333

    subgraph Legend
        C1["Code Components"]:::code
        C2["Config Store"]:::config
        C3["External Services"]:::external
        C4["CI/CD"]:::ci
    end
```
