# maze-technology/hello-world-specs-template architecture

> Architecture diagram of the GitHub repository maze-technology/hello-world-specs-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maze-technology/hello-world-specs-template
- Repository: https://github.com/maze-technology/hello-world-specs-template

## Overview

##### Project type and purpose
- This is an open-source specification-to-DTOs code-generation template repository.
- It houses Smithy IDL definitions (“hello world” DTOs) and build scripts to generate language-specific libraries (Java JARs).

##### File structure
- Top-level build system: Gradle (`build.gradle`, `settings.gradle`, `gradlew`), Makefile, and custom scripts.
- Spec definitions under `src/main/smithy/tech/maze/dtos/helloworld/...` (models, payloads, controllers).
- CI/CD configurations in `.github/workflows` (publish, build-scan, release approval, style checks).
- Supporting configuration: `buf.yaml` for Buf (Protobuf/gRPC) codegen, `smithy-protovalidate` script, `gradle.properties`, `sonar-project.properties`.

##### README for additional insights
- Describes toolchain: Smithy CLI, Smithy Translate CLI, Buf CLI, Coursier CLI.
- Purpose: generate DTO libraries consumed as Maven dependencies (`tech.maze:dtos.hello-world`).

##### Main components
a. Specification Repository
- Smithy IDL files under `src/main/smithy`.
- Custom validation script (`smithy-protovalidate`).
b. Toolchain/CLI Layer
- Smithy CLI: validates and compiles Smithy models.
- Smithy Translate CLI: converts Smithy definitions to Protobuf or service definitions.
- Buf CLI: processes Protobuf descriptors and generates gRPC/Java code.
- Coursier CLI: dependency resolution (optional).
c. Build Orchestration
- Gradle build logic (plugins that invoke Smithy Translate and Buf).
- Makefile targets wrap Gradle or direct tool invocations.
d. Continuous Integration/Delivery
- GitHub Actions workflows:
- `build-scan.yaml` – run build, generate reports
- `smithy-fmt-check.yaml` – ensure Smithy formatting
- `publish.yaml` – publish artifacts to Maven Central or GitHub Packages
- `release-approval.yaml` – gating releases
e. Artifact Repository
- Maven Central or GitHub Packages (consumers pull generated JAR).
f. Consumer Project
- Any downstream Java project declaring `tech.maze:dtos.hello-world` as a dependency

##### Relationships and data flows
1. Developer clones the repo (with submodules).
2. Local build invokes Makefile or `./gradlew generateSmithyProtos` →
a. Smithy CLI validates & compiles models
b. Smithy Translate converts to Protobuf descriptors
c. Buf CLI generates Java DTO and gRPC stubs
d. Gradle compiles, tests, and packages JAR
3. CI pipeline runs the same steps, plus quality gates (SonarCloud) and format checks.
4. On successful CI, artifacts are published to a remote Maven repository.
5. Consumer projects fetch the published JAR as a dependency.

##### Architectural patterns and design principles
- Separation of concerns: specification layer (Smithy IDL) is decoupled from generated code.
- Pipeline pattern: chain of tool invocations transforming specs → descriptors → code.
- Infrastructure as code: all build, validation, formatting, and publishing steps are codified (Gradle, Makefile, CI workflows).
- Extensibility: adding a new DTO or service requires only a new Smithy IDL file; the pipeline picks it up automatically.

##### Details
- Every step of the pipeline and every external dependency.
- Which configuration files drive which step (`buf.yaml` → Buf CLI; `build.gradle` → Gradle tasks; `.github/workflows` → CI).
- Don’t omit the consumer perspective: how downstream projects integrate the generated library.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Specification Repository
    subgraph "Specification Repository"
        SpecRepo["Smithy IDL Files\n(src/main/smithy/tech/maze/dtos/helloworld)"]:::inRepo
        ValidationScript["Custom Validation Script\n(scripts/smithy-protovalidate)"]:::inRepo
    end

    %% CLI Tools
    subgraph "CLI Tools"
        SmithyCLI["Smithy CLI"]:::external
        SmithyTranslate["Smithy Translate CLI"]:::external
        BufCLI["Buf CLI"]:::external
        CoursierCLI["Coursier CLI"]:::external
    end

    %% Build Orchestration
    subgraph "Build Orchestration"
        Gradle["Gradle Build Logic\n(build.gradle)"]:::inRepo
        Settings["settings.gradle"]:::inRepo
        GradleProps["gradle.properties"]:::inRepo
        Wrapper["Gradle Wrapper\n(gradlew, gradlew.bat)"]:::inRepo
        WrapperJar["gradle-wrapper.jar"]:::inRepo
        WrapperProps["gradle-wrapper.properties"]:::inRepo
        Makefile["Makefile"]:::inRepo
        BufConfig["Buf Config\n(buf.yaml, buf.gen.yaml, buf.lock)"]:::inRepo
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        BuildScan["build-scan.yaml"]:::external
        SmithyFMT["smithy-fmt-check.yaml"]:::external
        Publish["publish.yaml"]:::external
        ReleaseApproval["release-approval.yaml"]:::external
        Sonar["sonar-project.properties"]:::inRepo
        ReleaseScript["release.sh"]:::inRepo
    end

    %% Config Files
    subgraph "Project Configuration"
        Gitmodules[".gitmodules"]:::inRepo
        Codeowners["CODEOWNERS"]:::inRepo
        License["LICENSE"]:::inRepo
        Readme["README.md"]:::inRepo
        PrettierRC[".prettierrc.json"]:::inRepo
        PrettierIgnore[".prettierignore"]:::inRepo
        EditorConfig[".editorconfig"]:::inRepo
    end

    %% Artifact Repository and Consumer
    ArtifactRepo["Artifact Repository\n(Maven Central/GitHub Packages)"]:::external
    Jar["Generated JAR Package"]:::output
    Consumer["Consumer Project"]:::external

    %% Data Flow
    SpecRepo -->|".smithy files"| ValidationScript -->|".smithy files"| SmithyCLI
    SmithyCLI -->|".proto descriptors"| SmithyTranslate -->|".proto descriptors"| BufCLI
    BufCLI -->|".java DTO & gRPC code"| Gradle
    Wrapper -->|invokes| Gradle
    Makefile -->|wraps| Gradle
    Gradle -->|"compiles & packages"| Jar
    Jar -->|".jar artifact"| ArtifactRepo
    ArtifactRepo -->|dependency| Consumer

    %% CI Workflow Triggers
    BuildScan -->|triggers| Gradle
    SmithyFMT -->|format check| SmithyCLI
    Publish -->|publish artifact| ArtifactRepo
    ReleaseApproval -->|gate releases| Publish
    Sonar -->|quality analysis| Gradle
    ReleaseScript -->|release helper| Gradle

    %% External Tool Integration
    BufConfig -->|configures| BufCLI
    Settings -->|configures| GradleProps
    CoursierCLI -->|optional dependency| Gradle

    %% Click Events
    click SpecRepo "https://github.com/maze-technology/hello-world-specs-template/tree/develop/src/main/smithy/tech/maze/dtos/helloworld"
    click ValidationScript "https://github.com/maze-technology/hello-world-specs-template/tree/develop/scripts/smithy-protovalidate"
    click Gradle "https://github.com/maze-technology/hello-world-specs-template/blob/develop/build.gradle"
    click Settings "https://github.com/maze-technology/hello-world-specs-template/blob/develop/settings.gradle"
    click GradleProps "https://github.com/maze-technology/hello-world-specs-template/blob/develop/gradle.properties"
    click Wrapper "https://github.com/maze-technology/hello-world-specs-template/tree/develop/gradlew"
    click WrapperJar "https://github.com/maze-technology/hello-world-specs-template/blob/develop/gradle/wrapper/gradle-wrapper.jar"
    click WrapperProps "https://github.com/maze-technology/hello-world-specs-template/blob/develop/gradle/wrapper/gradle-wrapper.properties"
    click Makefile "https://github.com/maze-technology/hello-world-specs-template/tree/develop/Makefile"
    click BufConfig "https://github.com/maze-technology/hello-world-specs-template/blob/develop/buf.yaml"
    click BufConfig "https://github.com/maze-technology/hello-world-specs-template/blob/develop/buf.gen.yaml"
    click BufConfig "https://github.com/maze-technology/hello-world-specs-template/blob/develop/buf.lock"
    click BuildScan "https://github.com/maze-technology/hello-world-specs-template/blob/develop/.github/workflows/build-scan.yaml"
    click Publish "https://github.com/maze-technology/hello-world-specs-template/blob/develop/.github/workflows/publish.yaml"
    click ReleaseApproval "https://github.com/maze-technology/hello-world-specs-template/blob/develop/.github/workflows/release-approval.yaml"
    click SmithyFMT "https://github.com/maze-technology/hello-world-specs-template/blob/develop/.github/workflows/smithy-fmt-check.yaml"
    click Sonar "https://github.com/maze-technology/hello-world-specs-template/blob/develop/sonar-project.properties"
    click ReleaseScript "https://github.com/maze-technology/hello-world-specs-template/blob/develop/release.sh"
    click Gitmodules "https://github.com/maze-technology/hello-world-specs-template/blob/develop/.gitmodules"
    click Codeowners "https://github.com/maze-technology/hello-world-specs-template/tree/develop/CODEOWNERS"
    click License "https://github.com/maze-technology/hello-world-specs-template/tree/develop/LICENSE"
    click Readme "https://github.com/maze-technology/hello-world-specs-template/blob/develop/README.md"
    click PrettierRC "https://github.com/maze-technology/hello-world-specs-template/blob/develop/.prettierrc.json"
    click PrettierIgnore "https://github.com/maze-technology/hello-world-specs-template/blob/develop/.prettierignore"
    click EditorConfig "https://github.com/maze-technology/hello-world-specs-template/blob/develop/.editorconfig"

    %% Styles
    classDef inRepo fill:#FFEB3B,stroke:#333,stroke-width:1px;
    classDef external fill:#2196F3,stroke:#333,stroke-width:1px,color:#fff;
    classDef output fill:#8BC34A,stroke:#333,stroke-width:1px;color:#fff;
```
