How speakeasy-api/speakeasy works
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.