# speakeasy-api/speakeasy architecture

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

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

## Overview

##### Main Components
- CLI Interface – The entry point of the application which passes control to various subcommands (located in the “cmd” directory). Each subcommand (e.g., ask, auth, billing, bump, clean, etc.) corresponds to a key functionality and is responsible for handling user inputs.
- Command Handlers & Core Logic – Under “cmd”, you have multiple dedicated files and subdirectories (like “generate”, “lint”, “openapi”, “overlay”, etc.) that serve as the controllers, forwarding requests to internal logic.
- Internal Business Logic – The “internal” folder contains a host of packages (e.g., ask, auth, cache, changes, charm, config, docs, download, git, github, interactivity, links, markdown, run, sdk, suggest, transform, etc.) which implement the core processing, business rules, and transformations. They encapsulate the interactions, such as generating SDKs, normalizing OpenAPI inputs, handling overlays, and managing environment configurations.
- Integration & Testing – The “integration” directory contains tests, sample OpenAPI specs, overlays, and related resources that verify component interactions.
- Utility & Helper Modules – There are packages such as “pkg” (with code samples, merging, overlay logic) and “registry” (handling tagging and versioning), along with configurations and scripts for CI/CD (e.g., GitHub workflows, Makefile, install.sh).

##### Component Relationships & Interactions
- The user interacts with the CLI, which maps into specific subcommand modules (e.g., “speakeasy auth”, “speakeasy run”, etc.).
- Each command in “cmd” delegates processing to corresponding internal packages. For instance, the “cmd/openapi” module likely calls internal utilities (from internal/transform or internal/validation) to process OpenAPI specs.
- The internal modules themselves are composed in a layered manner: configuration and environment management, logging and caching, then domain-specific logic (e.g., SDK generation, overlay transformation, source tracking).
- External integrations should be highlighted too – such as interfacing with Git/GitHub (internal/git, internal/github), or external API mock servers (using Arazzo in the contract tests).
- The testing/integration folder confirms interactions across the system modules and verifies code sample generations and OpenAPI transformations.

##### Architectural Patterns & Design Principles
- The project exhibits a modular, layered architecture where the CLI (presentation) layer is separated from the business/processing logic in “internal” and “pkg,” following separation of concerns.
- There is an evident command design pattern where each subcommand is implemented as a discrete module.
- The integration tests and scripts suggest a focus on continuous testing and deployment (e.g., via GitHub workflows and dependency management scripts).

##### Relevant Technologies & Frameworks
- The project is written in Go, leveraging its module system (go.mod, go.sum) for dependency management.
- Build and deployment automation are managed by tools like Make and CI configuration files in “.github/workflows.”
- Additional tooling is evident in directories like “internal/sdkgen,” “internal/studio,” and “internal/markdown” which indicate specialized handling for code generation and documentation.

##### Detail Level
- Module or critical subsystem (e.g., auth, sdk, merge, overlay, lint) is clearly identified and annotated.
- Notes on directories like “internal/studio” and “internal/defaultcodesamples” to show how they provide specialized support such as styling, code sample generation, and SDK customization.

– The separation between the CLI command layer (cmd) and the underlying services (internal, pkg).
– The flow from user interactions to internal processing and back, emphasizing modularity, code generation, and API transformations.
– Integration points with external systems and continuous integration pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI["CLI Interface"]:::cli
    end

    subgraph "Command Handlers"
        GENERATE["Generate Command"]:::cmd
        LINT["Lint Command"]:::cmd
        OPENAPI["OpenAPI Command"]:::cmd
        OVERLAY["Overlay Command"]:::cmd
        OTHERS["Other Commands (ask,auth,billing,bump,clean, etc.)"]:::cmd
    end

    subgraph "Internal Business Logic"
        ASK["Ask Module"]:::internal
        AUTH["Auth Module"]:::internal
        CACHE["Cache Module"]:::internal
        SDK["SDK Generation"]:::internal
        TRANSFORM["Transformation & Validation"]:::internal
        OTHERS_INTERNAL["Other Internal Packages"]:::internal
    end

    subgraph "Utility & Helper Modules"
        PKG["Pkg Modules (codesamples,merge,overlay)"]:::utility
        PROMPTS["Prompts Module"]:::utility
        REGISTRY["Registry (tagging/versioning)"]:::utility
    end

    subgraph "Integration & Testing"
        INTEGRATION["Integration Tests & Contracts"]:::testing
    end

    subgraph "External Integrations"
        GITHUB["GitHub Integration"]:::external
        TERRAFORM["Terraform Provider"]:::external
        ARAZZO["External API Mock (Arazzo)"]:::external
    end

    %% Relationships from CLI to Command Handlers
    CLI -->|"triggers"| GENERATE
    CLI -->|"triggers"| LINT
    CLI -->|"triggers"| OPENAPI
    CLI -->|"triggers"| OVERLAY
    CLI -->|"triggers"| OTHERS

    %% Command Handlers delegating to Internal Business Logic
    GENERATE -->|"delegates"| SDK
    LINT -->|"delegates"| TRANSFORM
    OPENAPI -->|"calls"| TRANSFORM
    OVERLAY -->|"calls"| TRANSFORM
    OTHERS -->|"delegates"| ASK
    OTHERS -->|"delegates"| AUTH

    %% Internal Business Logic integrating with Utility Modules
    SDK -->|"integrates"| PKG
    TRANSFORM -->|"integrates"| PKG
    AUTH -->|"integrates"| PROMPTS
    CACHE -->|"integrates"| PROMPTS
    OTHERS_INTERNAL -->|"links with"| CACHE

    %% External interactions from Internal Business Logic / Utility Modules
    SDK -->|"external_call"| GITHUB
    AUTH -->|"external_call"| GITHUB
    TRANSFORM -->|"external_call"| ARAZZO
    PKG -->|"supports"| REGISTRY

    %% Integration & Testing validating internal modules
    INTEGRATION -->|"validates"| SDK
    INTEGRATION -->|"validates"| TRANSFORM
    INTEGRATION -->|"validates"| OTHERS

    %% External flows with Terraform and GitHub
    TERRAFORM -->|"uses_output_of"| SDK
    GITHUB -->|"triggers_CI"| INTEGRATION

    %% Click events for component mapping
    click CLI "https://github.com/speakeasy-api/speakeasy/tree/main/cmd/"
    click GENERATE "https://github.com/speakeasy-api/speakeasy/tree/main/cmd/generate"
    click LINT "https://github.com/speakeasy-api/speakeasy/tree/main/cmd/lint"
    click OPENAPI "https://github.com/speakeasy-api/speakeasy/tree/main/cmd/openapi"
    click OVERLAY "https://github.com/speakeasy-api/speakeasy/tree/main/cmd/overlay"
    click OTHERS "https://github.com/speakeasy-api/speakeasy/tree/main/cmd/"
    click SDK "https://github.com/speakeasy-api/speakeasy/tree/main/internal/sdk"
    click TRANSFORM "https://github.com/speakeasy-api/speakeasy/tree/main/internal/transform"
    click AUTH "https://github.com/speakeasy-api/speakeasy/tree/main/internal/auth"
    click PKG "https://github.com/speakeasy-api/speakeasy/tree/main/pkg/"
    click PROMPTS "https://github.com/speakeasy-api/speakeasy/tree/main/prompts/"
    click REGISTRY "https://github.com/speakeasy-api/speakeasy/tree/main/registry/"
    click INTEGRATION "https://github.com/speakeasy-api/speakeasy/tree/main/integration/"

    %% Styles
    classDef cli fill:#ccf,stroke:#000,stroke-width:2px;
    classDef cmd fill:#9f6,stroke:#000,stroke-width:2px;
    classDef internal fill:#ff9,stroke:#000,stroke-width:2px;
    classDef utility fill:#f9c,stroke:#000,stroke-width:2px;
    classDef testing fill:#fc9,stroke:#000,stroke-width:2px;
    classDef external fill:#f99,stroke:#000,stroke-width:2px;
```
