# smithy-lang/smithy-typescript architecture

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

- Interactive diagram: https://gitdiagram.com/smithy-lang/smithy-typescript
- Repository: https://github.com/smithy-lang/smithy-typescript

## Overview

##### Project Type and Purpose
- This is a monorepo for **Smithy-TypeScript**, a code-generation framework that reads Smithy models and emits TypeScript client and server SDKs.
- It has two halves:
- A **Java/Gradle-based** code generator (`smithy-typescript-codegen` plus plugins and integrations via SPI).
- A **TypeScript/Yarn workspace** of dozens of small, focused packages (core, middleware, util, protocol, handlers, etc.) that form the runtime libraries and generated SDKs.

##### Main Components
A. **Java Code Generation Layer**
- Smithy CLI / Gradle Plugin (invokes `smithy build`)
- `smithy-typescript-codegen` (Java code generators)
- TypeScriptIntegration implementations (in `src/main/java/...`)
- ProtocolGenerators (HTTP-binding, RPC)
- RuntimeClientPlugins (endpoint resolution, auth schemes)
- SPI registration files under `META-INF/services`
- Build artifacts produced under `build/smithy/...`

B. **TypeScript Monorepo Workspace**
- Root level: `package.json`, `turbo.json`, Yarn workspace config
- `packages/` directory: ~100 packages (abort-controller, middleware-*, util-*, protocol-http, etc.)
- `smithy-typescript-ssdk-libs/`: server SDK support packages
- `private/` & `smithy-typescript-codegen-test`: local models and test harness projects
- Build tooling: `scripts/` (copy generated packages, test harness), `Makefile`, Gradle wrapper

C. **CI/CD & Release Pipelines**
- GitHub Actions workflows (`.github/workflows/*.yml`)
- Changesets for versioning in TS packages
- Gradle build & publish to Maven Local (Java)
- Yarn/turbo build, test, and publish to npm registry (TS)

##### Relationships & Data Flow
1. **Smithy Model Input** (user’s `.smithy` files)
↓
2. **Smithy CLI/Gradle** loads the Java plugin (`smithy-typescript-codegen`) via SPI
↓
3. **Java Codegen**
- Parses models → applies ProtocolGenerators & RuntimeClientPlugins → writes TypeScript sources under `build/smithy/source/typescript-client-codegen` (or server codegen projection)
↓
4. **Copy Script** (`scripts/build-generated-test-packages.js`)
- Stages generated TS packages into `node_modules` for integration
↓
5. **TypeScript Workspace**
- Yarn/turbo picks up all TS packages under `packages/` and `smithy-typescript-ssdk-libs/`
- Builds each package (via `tsc`, Vitest/Jest)
- Runs integration tests against generated clients
↓
6. **Publish**
- Java artifacts to Maven Central or Maven Local
- TS packages to npm (or private registry) via GH Actions

##### Architectural Patterns & Principles
- **Plugin & SPI** in Java: loose coupling, custom ProtocolGenerators & integrations
- **Monorepo with Yarn Workspaces + Turbo**: single source, consistent tooling, fast builds
- **Modular TS Packages**: each small library has a single responsibility (e.g., compression, retry, signature)
- **Middleware Stack** pattern in generated clients: pluggable HTTP requests/response processing

##### Technologies & Frameworks
- **Java/Gradle**: Smithy CLI, codegen, SPI, Gradle Kotlin DSL
- **TypeScript**: Yarn workspaces, Turbo, Vitest/Jest, Changesets
- **CI/CD**: GitHub Actions, npm registry, Maven repositories

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Java Codegen Layer
    subgraph "Java Codegen" 
        direction TB
        Models["Smithy Models (.smithy files)"]:::external
        CLI["Smithy CLI / Gradle Plugin"]:::java
        Codegen["smithy-typescript-codegen"]:::java
        SPI["SPI Integrations & ProtocolGenerators"]:::java
        Artifacts["Generated TS Sources"]:::artifact
    end

    %% TypeScript Workspace
    subgraph "TypeScript Monorepo Workspace"
        direction TB
        RootConfig["Root Workspace Config"]:::ts
        Packages["TS Packages (core, middleware-*, util-*, protocol)"]:::ts
        SSDKLibs["Server SDK Support Libraries"]:::ts
        TestHarness["Local Test Harness & Models"]:::ts
        CopyScript["Copy Script & Build Scripts"]:::script
        TSBuild["Yarn/Turbo Build & Test"]:::ts
    end

    %% CI/CD & Publishing
    subgraph "CI/CD & Publishing"
        direction TB
        GHActions["GitHub Actions Workflows"]:::ci
        PublishJava["Publish Java Artifacts"]:::ci
        PublishTS["Publish TS Packages"]:::ci
        MavenCentral[(Maven Central)]:::external
        NpmRegistry[(npm Registry)]:::external
    end

    %% Flow
    Models -->|"load via SPI"| CLI
    CLI -->|"invoke codegen"| Codegen
    Codegen --> SPI
    SPI -->|"generate TS code"| Artifacts
    Artifacts -->|"stage into npm packages"| CopyScript
    CopyScript -->|"install into workspace"| RootConfig
    RootConfig --> Packages
    Packages --> TSBuild
    SSDKLibs --> TSBuild
    TestHarness --> TSBuild
    TSBuild -->|"integration tests"| TestHarness
    TSBuild -->|"publish trigger"| GHActions
    GHActions --> PublishJava
    GHActions --> PublishTS
    PublishJava --> MavenCentral
    PublishTS --> NpmRegistry

    %% Click Events - Java Codegen
    click CLI "https://github.com/smithy-lang/smithy-typescript/blob/main/smithy-typescript-codegen/build.gradle.kts"
    click Codegen "https://github.com/smithy-lang/smithy-typescript/tree/main/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen"
    click SPI "https://github.com/smithy-lang/smithy-typescript/tree/main/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/integration"
    click SPI "https://github.com/smithy-lang/smithy-typescript/tree/main/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/protocols"
    click SPI "https://github.com/smithy-lang/smithy-typescript/blob/main/smithy-typescript-codegen/src/main/resources/META-INF/services/software.amazon.smithy.build.SmithyBuildPlugin"
    click SPI "https://github.com/smithy-lang/smithy-typescript/blob/main/smithy-typescript-codegen/src/main/resources/META-INF/services/software.amazon.smithy.typescript.codegen.integration.TypeScriptIntegration"
    click Artifacts "https://github.com/smithy-lang/smithy-typescript/tree/main/build/smithy/"

    %% Click Events - TS Workspace
    click RootConfig "https://github.com/smithy-lang/smithy-typescript/blob/main/package.json"
    click RootConfig "https://github.com/smithy-lang/smithy-typescript/blob/main/turbo.json"
    click RootConfig "https://github.com/smithy-lang/smithy-typescript/tree/main/.yarn/"
    click Packages "https://github.com/smithy-lang/smithy-typescript/tree/main/packages/"
    click SSDKLibs "https://github.com/smithy-lang/smithy-typescript/tree/main/smithy-typescript-ssdk-libs/server-apigateway"
    click SSDKLibs "https://github.com/smithy-lang/smithy-typescript/tree/main/smithy-typescript-ssdk-libs/server-common"
    click SSDKLibs "https://github.com/smithy-lang/smithy-typescript/tree/main/smithy-typescript-ssdk-libs/server-node"
    click TestHarness "https://github.com/smithy-lang/smithy-typescript/tree/main/private/my-local-model"
    click TestHarness "https://github.com/smithy-lang/smithy-typescript/tree/main/smithy-typescript-codegen-test"
    click CopyScript "https://github.com/smithy-lang/smithy-typescript/blob/main/scripts/build-generated-test-packages.js"
    click CopyScript "https://github.com/smithy-lang/smithy-typescript/tree/main/scripts/cli-dispatcher/"
    click CopyScript "https://github.com/smithy-lang/smithy-typescript/tree/main/Makefile"

    %% Click Events - CI/CD & Configs
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/.github/workflows/ci.yml"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/.github/workflows/git-sync.yml"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/.github/workflows/release-npm-packages.yml"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/.github/workflows/release-npm-ssdk-libs.yml"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/.github/workflows/update-smithy-gradle-plugin.yml"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/tree/main/.changeset/"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/tree/main/smithy-typescript-ssdk-codegen-test-utils"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/tree/main/smithy-typescript-protocol-test-codegen"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/tree/main/gradlew"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/tree/main/gradle/wrapper/"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/settings.gradle.kts"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/gradle.properties"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/tsconfig.json"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/jest.config.base.js"
    click GHActions "https://github.com/smithy-lang/smithy-typescript/blob/main/vitest.config.ts"

    %% Styles
    classDef java fill:#cfe2f3,stroke:#3b6ea5,color:#0b3b91;
    classDef ts fill:#d9ead3,stroke:#6aa84f,color:#38761d;
    classDef script fill:#e7e6e6,stroke:#999999,color:#333333;
    classDef ci fill:#ead1dc,stroke:#a64d79,color:#741b47;
    classDef artifact fill:#fce5cd,stroke:#e69138,color:#b45f06;
    classDef external fill:#ffffff,stroke:#000000,color:#000000;
```
