Guides with the production practices Pyahu follows for Spring Boot, Java and Next.js, shared with the community. A preview generator implements the supported starting projects. Each guide step answers one question with the failure it prevents. The guides are a public preview: each guide shows which steps are tested here and names the test of each tested claim. The other steps rest on the official documentation the guide lists.
- Site: https://initializer.pyahu.io
- The guides: 24 guides in six parts (foundations, build the service, events and data, run in production, ship, grow)
- Agent Skill: the same guides as plain Markdown for AI coding tools and team reviews
- How to contribute: CONTRIBUTING.md, or AGENTS.md for the short version
- Why the scope is what it is: ADR 0002
A fixture in fixtures/ is a real service built with the exact versions of the baseline in
data/versions.yaml. CI builds it, runs the Go acceptance tests in acceptance/ against its image and fails
unless every required test passes and every version matches. A tested claim has a record in data/evidence/
that names one of those tests, so it holds for as long as main is green. The summary at the top of each guide
says which steps are tested here: compiled code, reproduced behaviour or a measurement.
The generator is frozen at its current options while teams try it. The Start workflow builds all 16 combinations of architecture, PostgreSQL, OIDC and Next.js, runs their own generated CI and tests the form in a browser. These checks cover the generated paths; the tested claims and their limitations say what each guide proves.
| Path | What |
|---|---|
guides/ |
The Astro and Starlight site, its components and diagrams and the guide pages |
services/start/, build-logic/, gradle/ |
The Initializer service behind start.pyahu.io (in development) and its Gradle build |
frontends/start-web/ |
The page of start.pyahu.io: the form, the files it gives and the download (Next.js) |
templates/ |
The files the service renders into a generated project |
skills/ |
The guides as an Agent Skill, generated by guidekit generate |
data/ |
The baseline, official documentation, checklist, tested claims, schemas |
fixtures/ |
Services written by hand that prove the guides |
acceptance/ |
Go behavioural tests run against the fixture images (build tag acceptance) |
cmd/guidekit/, cmd/runworkflow/, internal/ |
Go tooling: checks, generated files, evidence, site and link checks, running a generated project's CI |
Run these from the repository root, starting each server in its own terminal:
go run ./cmd/guidekit check # data, guides, cross-references
npm --prefix guides ci && npm --prefix guides run dev # the site at http://localhost:4321 (Node 24.22.3)
./gradlew :start:bootRun # the generator preview
curl localhost:8080/starter.zip -d name=orders -o orders.zip
curl localhost:8080/starter.zip -d name=orders -d database=postgres -d auth=oidc -d frontend=nextjs -o orders.zip
npm --prefix frontends/start-web ci && npm --prefix frontends/start-web run dev # the page at http://localhost:3001, against the generatorCode, data and fixtures: MIT (LICENSE). Guide text and diagrams: CC BY 4.0 (LICENSE-GUIDES.md). By Terson Rigaud, under the Pyahu community.