MJGA treats the OpenAPI contract as the source of truth for a generated stack

The four branches are generated output, not source templates

The most important thing to understand about this repository is that you are not looking at a template. The README states that the branches are not source templates but a Default Scaffold generated, fully verified and atomically published by the MJGA Generation Service, and that the four branches belong to the same Contract First Template Family, differing only in Architecture Language and Persistence Adapter. The four are Java plus Jimmer, Java plus jOOQ, Kotlin plus Jimmer and Kotlin plus jOOQ, each on its own contract-first branch. That structure has a direct consequence for how you use the project. The repository is a read-only Generated Code Projection published from a private MJGA Platform Source. The main branch holds only product description and branch navigation, the four contract-first branches hold the runnable generated scaffold, and problems must be fixed in the Generation Source, the Catalog or the Base Template Variant and then regenerated. The README explicitly asks that the generated branches not be treated as hand-maintained template source, and offers the issue tracker as the way to report a problem.

One OpenAPI file is the authority for the whole stack

The architecture diagram in the README is the clearest statement of the design, and it is worth reading as a data flow rather than a picture. The file contracts/openapi/openapi.json sits at the top as the cross-stack HTTP authority, and it generates packages/api-client, which in turn feeds apps/web, while apps/server implements the same contract. Alongside that, compose.yaml provides PostgreSQL, the web app and the server, and mjga-project.yaml together with the .mjga directory holds the Recipe, the Generation State and ownership evidence. The generated TypeScript client is described as rebuildable and tested, and the web app is a React and Vite application using TanStack Router, Query and Form with Zod, which does not assemble the server API calls by hand. The point of the arrangement is that the contract is written first and the client is derived from it, so a change to the contract has to propagate rather than drift.

A generated scaffold ships no invented business models

There is a line in the README about what the default scaffold deliberately does not contain, and it reveals the philosophy better than any feature list. The Default Scaffold does not invent business models such as Order or User. Business code starts from a real Capability, and Contract Authoring keeps the OpenAPI, the Event Schema, the Migration and the Generated Client inputs in sync as it evolves. That is a claim about the generator's behaviour, not just its output. A scaffold that ships a fake user table teaches the wrong lesson, because the first thing a developer does is delete it, and what remains is the generated code without the reasoning that produced it. The stack choices are visible in the repository topics, which list gradle, java, java17, java21, spring-boot, spring-cache, spring-security, jimmer, jooq, pmd, spotless and testcontainer, so a reader can see that the generated project carries its own quality tooling and container based testing rather than a bare hello world.

The CLI is preview first, and only apply writes to the workspace

The command line is where most of the product actually lives, and the npm package is mjga-cli. The documented workflow for an already generated project runs the tool against the project directory:

npm ci
docker compose up -d database
mjga add capability order-management --project . --apply
mjga add use-case order-management create-order --kind command --transport http --project . --apply
mjga verify .
npm run dev

The rule that matters is stated as an invariant. All modification commands are preview first, and only an explicit --apply writes to the Project Workspace. That single convention is what makes the tool usable by a coding agent, because an agent can run a plan and read it without changing anything. The capability list of the CLI is long and covers catalog discovery, Recipe validation and export, Generation Plan Preview, online generation with Archive Digest verification and atomic installation, and the domain objects of Capability, Use Case, versioned Event, Workflow, Read Model and Consumer Contract. It also covers database role hardening, Extraction Assessment, Capability Migration Plan, a Contract Workbench, an OpenAPI mock server, a read-only development MCP, OpenRewrite upgrade and full stack verification.

Creation needs the service, but catalog and preview can run offline

There is a deliberate split in where the CLI can work, and it is the kind of split that decides whether the tool fits your environment. Catalog discovery, Recipe validation and export, Preview and the existing workspace tools can run offline within a valid Authenticated Access Lease, but create and generate always use the live Generation Service. In practice that means you can explore the catalog and render plans on a machine with no outbound network, and you cannot generate a new project without one. The installation and first steps of the CLI are short:

npm install --global mjga-cli
mjga login
mjga catalog
mjga preview ./mjga-project.yaml
mjga create ./my-service --recipe ./mjga-project.yaml

The login step is what establishes the lease. The configurator at the product site offers the same choice from a browser, letting you pick Java or Kotlin, jOOQ or Jimmer, the JDK and other stack options, preview the Project Recipe and the Generation Plan, and then download the complete project. For a team evaluating the platform, the preview path is the one to try first, because it produces the plan without producing the code.

The product boundary is deliberately narrow and stated plainly

The access boundaries section is short and worth reading in full, because it tells you what the project will not do. Contract First is the only continuously evolving Current Template Family, and it is free after login with no purchase required. Database First and Model First have been archived, and only historical Archive Entitlement can read the old order assets. Donations are voluntary support and grant no product access and trigger no purchase flow. The Configurator, the CLI and the Remote MJGA MCP share the same Generation Service authentication and Recipe authority, and the Remote MJGA MCP offers only Catalog and Planning, so it does not generate an Archive and does not modify a local workspace. The last point matters for a team with a policy about what may run against their source tree. The documentation site, a Chinese CLI guide in the docs directory and the npm package page carry the detailed instructions.

Every published change passes through the same gates

The maintenance section explains how a change reaches you, and it is the part that separates a generated platform from a template someone maintains in public. The four scaffold branches and the main branch are updated through the same atomic publication transaction, so you never get a scaffold that is newer than the documentation pointing at it, and the current projection source commit is recorded in the README so you can tell exactly what produced what you are looking at. Before publication, the build must pass a set of gates the README lists: build, test, architecture, reproducibility, browser, system and container. A reproducibility gate is the interesting one in a code generator, because it means the same inputs have to produce the same output, which is what lets you regenerate rather than diff. The README is explicit that issues are welcome through the issue tracker, but the generated branches are not to be treated as manually maintained template source.

Where MJGA is the wrong choice

Three situations argue against it. The first is a project that needs to diverge from the generated shape. This is a generated projection, and the source of truth is a private platform source you cannot change, so a team that needs an unusual module, a bespoke persistence model or a non-standard build will find those changes overwritten on the next generation. That is fine for a greenfield service that follows the recipe, and wrong for a codebase that is going to accumulate its own conventions. The second is a team that wants a plain template they own. If the goal is a starting repository with a sensible Gradle, Spring Boot and Docker setup, a hand-maintained template or a code generator you write yourself gives you the same outcome with the ownership that a commercial platform cannot offer, and the archived Database First and Model First families show that even the vendor treats earlier families as historical assets rather than living templates. The third is an environment that cannot reach the generation service. Since create and generate always use the live service, a fully air-gapped team can plan and validate but cannot scaffold, and the local generation path is not documented as an option. The project is also young in its published form, with tags 3.2.1 from 2025-07-24, 3.2 from 2025-05-06 and 3.1 from 2025-04-06, so the CLI surface described in the README may not all be in the version you install.

Editorial conclusion

Adopt MJGA when you want a full stack project whose contract, schema, migrations and client are generated from one place and can be re-verified, and do not fork the scaffold branches expecting to edit them by hand. Verify first which of the four contract-first branches matches your stack, since Java and Kotlin are crossed with jOOQ and Jimmer, and read the CLI guide before you rely on offline catalog and preview commands, because create and generate always talk to the live generation service.

Frequently asked questions

Official sources

1. ccmjga/mjga-scaffold on GitHub
2. License: MIT
3. Project website
4. README
5. Releases