How maze-technology/hello-world-specs-template works
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.