a-pavithraa/springboot-skills-marketplace / plugins/springboot-architecture/skills/creating-springboot-projects
creating-springboot-projects
VerifiedUse when starting a new Spring Boot project or service: scaffolding or bootstrapping a backend, REST API, microservice or modular monolith; choosing how to structure it (layered, package-by-module, modular monolith, tomato, DDD-hexagonal); selecting Spring Boot 4 features; generating the base project with progen or Spring Initializr; or applying the bundled templates and references in this skill. Not for migrating existing projects or for isolated JPA/repository work without broader project-creation context.
references/progen-integration.md
View on GitHub# Progen Integration
[Progen](https://github.com/sivaprasadreddy/progen) is an offline CLI that generates a Spring Boot 4 project: build file, Docker Compose, Testcontainers, security, migrations, CI, and ArchUnit/Modulith tests. Use it for the base project. Then add the architecture layer from this skill on top.
Progen has no architecture option. Its layout is always package-by-module with Spring Modulith (`config/`, `shared/`, `users/`).
Tested with progen v1.0.4 on 2026-10-31 (REST, Maven, PostgreSQL). Progen pins Spring Boot 4.1.2 and Java 25. v1.0.4 (2026-10-24) changed `ArchUnitTests` and has not been tested here.
## When to use progen
Use progen when all of these are true:
- `command -v progen` finds it, or the user agrees to install it.
- The project is a REST API, a server-rendered web app (Thymeleaf), or a Spring Boot + Angular app.
- The database is PostgreSQL, MySQL, or MariaDB.
- The user accepts Spring Security with a sample `users` module. Progen always generates it.
Otherwise, use Spring Initializr (Step 3 of `SKILL.md`).
Install: `go install github.com/sivaprasadreddy/progen@latest`, or download a binary from the releases page. On macOS the binary is unsigned. The user must allow it in Finder (Control-click, Open).
## Safety rules
- **Progen deletes `./<AppName>/` before it generates.** Never run it where that directory exists. The helper script refuses to run in that case.
- **Run progen with JDK 25 on `PATH`.** On JDK 27 the formatting step always fails with `NoSuchFieldError ... JCCompilationUnit`: Spotless 3.10.4 (progen pins 3.10.0) fixes its unused-imports step, but palantir-java-format fails on JDK 27 in every version up to 2.102.0 (checked 2026-10-21). The project then doesn't compile, because the step that failed is the one that removes an unused `AntPathRequestMatcher` import (Spring Security 7 removed the class) from `config/WebSecurityConfig.java`. The helper script stops with exit code 6 on a JDK newer than 25. If you're stuck on JDK 27: pass `--ignore-jdk-check`, delete that import and build with `-Dspotless.check.skip=true`. On JDK 25 progen's output passes `./mvnw verify` as generated (10 tests).
- Progen does not validate most values. An invalid value becomes the default, with only a WARNING. Use the helper script. It rejects invalid values.
- Progen runs `spotless:apply` (Maven) or `spotlessApply` (Gradle) at the end. This needs Java on `PATH` and network access on the first run. If only that step fails, progen prints "failed to format project code" and exits with 1, but the files exist; the script reports this as a warning. Any other progen failure stops the script with exit code 4.
## Step 1: Map the assessment to progen options
| Assessment answer | Script option | Progen value |
|-------------------|---------------|--------------|
| JSON API | `--app-type rest` (default) | `REST API` |
| Server-rendered UI | `--app-type web` | `Web App` (Thymeleaf is on) |
| Angular SPA | `--app-type angular` | `Spring Boot + Angular Full Stack` |
| Maven / Gradle | `--build-tool maven\|gradle` | `Maven` / `Gradle` |
| JPA (all architectures in this skill) | `--persistence jpa` (default) | `Spring Data JPA` |
| SQL-first, user asks for it | `--persistence jdbc\|jooq` | `Spring JdbcClient` / `jOOQ` |
| Database | `--db postgresql\|mysql\|mariadb` | `PostgreSQL` / `MySQL` / `MariaDB` |
| Migrations | `--migration flyway\|liquibase` | `Flyway` / `Liquibase` |
| Optional features | `--features aws,email,rabbitmq,redis,k8s,htmx` | `*Support: true` |
| Java other than 25 | `--java 21` | Script edits the build file after generation |
Rules:
- Tomato and DDD+Hexagonal need `--persistence jpa`. The templates in `assets/` assume JPA.
- With `jdbc` or `jooq`, do not apply JPA templates (`assets/rich-entity.java`, `assets/repository.java`).
- `htmx` needs `--app-type web`.
- Don't pass `otel`. Step 6 of `SKILL.md` runs the harness, whose observability pack replaces it.
- Read `java-version-policy.md` before you pass `--java` above 25.
## Step 2: Generate
`${CLAUDE_SKILL_DIR}` is the `creating-springboot-projects` folder. Codex doesn't set it, so there use that folder's path.
```bash
python3 "${CLAUDE_SKILL_DIR}/scripts/progen_config.py" \
--app-name shop --base-package com.acme.shop \
--build-tool maven --db postgresql --features redis \
--out-dir /path/to/parent --run
```
- Without `--run`, the script only writes and prints `.progen.json`. Show it to the user before you generate.
- The project goes to `<out-dir>/<app-name>/`.
- Exit codes: 0 = success (warnings may print, for example a failed formatting step), 1 = invalid input, 2 = target directory exists, 3 = progen not installed, 4 = progen failed or the project may be incomplete, 5 = generated but the Java version could not be set, 6 = the JDK in use (`JAVA_HOME`, else `java` on `PATH`) is newer than 25.
## Step 3: Add the architecture layer
| Architecture | What to do after generation |
|--------------|-----------------------------|
| `package-by-module` | Matches progen. Add feature packages next to `users/`. |
| `modular-monolith` | Matches progen. Add `*API.java` and `internal/` per module. `ModularityTests.java` exists; do not add `assets/modularity-test.java` again. Copy only extra checks from it. |
| `tomato` | Add `domain/vo/`, rich entities, and `rest/converters/` per module. Apply `assets/value-object.java`, `assets/rich-entity.java`, `assets/spring-converter.java`, `assets/service-cqrs.java`. |
| `ddd-hexagonal` | Add `application/`, `domain/`, `infra/`, `interfaces/` per module. On progen v1.0.3, change `ArchUnitTests.java` as shown below, because `*Handler` services fail the name rule. |
| `layered` | Add `controller/`, `service/`, `repository/`, `domain/`. The tests pass, but Modulith treats each layer as a module, which adds no value. Keep `users/` as the one feature package, and tell the user. |
### Templates to skip (progen already has them)
| Skip this asset | Progen file |
|-----------------|-------------|
| `assets/exception-handler.java` | `config/GlobalExceptionHandler.java`. Add a `DomainException` handler there if needed. |
| `assets/base-entity.java` | `shared/BaseEntity.java` (has `@Version`) |
| `assets/docker-compose.yml` | `compose.yml` |
| `assets/testcontainers-test.java` | `TestcontainersConfig.java`, `BaseIT.java` |
| `assets/modularity-test.java` | `ModularityTests.java` |
| `assets/pom-additions.xml` | Add only entries the pom does not have: `jspecify`, `hypersistence-utils-*` (TSID IDs), `spring-modulith-starter-jpa` (event registry). |
### progen's ArchUnit test
Keep `src/test/java/<base>/ArchUnitTests.java` as progen generates it. The harness (Step 6 of `SKILL.md`) adds `CodeRulesTests` next to it, with the runtime-trap rules progen doesn't have. Don't copy rules from one file into the other.
What `ArchUnitTests` checks depends on the progen version:
- v1.0.3 uses Taikai: name suffixes (`Controller`, `Service`, `Repository`, `Config`), package-private controllers and test classes, the `LOG` logger convention, no generic `throws Exception`, no import cycles, and layer-direction and `@Disabled` rules.
- v1.0.4 uses ArchUnit directly: no access from `domain` to `web` packages, package-private repositories and JPA entities, and `@Service` classes used only from their own module. Check that its `BASE_PACKAGE` constant is the project's base package. In the template it is a fixed `dev.sivalabs.feedbackhub`, which matches no other project.
Change a rule only when it conflicts with the chosen architecture:
- `ddd-hexagonal` on v1.0.3: services may be command handlers, so replace `namesShouldEndWithService()` with `namesShouldMatch(".+(Service|Handler)")`.
- Spring Data custom repository fragments on v1.0.3: replace `namesShouldEndWithRepository()` with `namesShouldMatch(".+Repository(Impl)?")`.
- `layered` on v1.0.4: the module rule reads the first package under the base as the module, so each layer counts as one. Remove `services_must_not_be_used_from_other_modules`.
### Other differences
- Progen creates `V001__create_users_table.sql`. Start new Flyway files at `V002__`. Flyway reads `V1` and `V001` as the same version and fails.
- Progen sets `spring.modulith.events.republish-outstanding-events-on-restart=true` and `spring.modulith.events.jdbc.schema-initialization.enabled=true`. Spring Modulith advises against both for production: republishing duplicates events when several instances run, and the table should come from a Flyway migration. Tell the user before production use.
- Progen sets `spring.threads.virtual.enabled=true`. This skill enables virtual threads only with workload evidence. Tell the user, and keep or remove it based on their answer.
- Progen adds BootUI, devtools, springdoc, JWT (for REST), Spotless, JaCoCo, and git-commit-id. Remove what the user does not want.
## Step 4: Verify
```bash
./mvnw test # or ./gradlew test; Testcontainers needs Docker
```
Run `ArchUnitTests` and `ModularityTests` first. They run without Docker and catch layout errors quickly.
## Align the project with the harness
`scripts/align_progen_project.py` adjusts a new project to the harness rules. `progen_config.py --run` runs it after generating. When you run progen another way, run it yourself before the harness.
| File | Change | Why |
|---|---|---|
| `users/AuthUtils`, `users/TokenHelper` | Marks three methods that can return `null` as `@Nullable` | NullAway in `all` mode |
| `config/GlobalExceptionHandler` | Returns a generic detail from the catch-all handler | `CodeRulesTests.catchAllHandlersKeepTheExceptionServerSide` |
| `config/GlobalExceptionHandler` | Leaves the logging of failures to `HandledFailureFilter` | Each 5xx is logged once |
| `users/AuthController`, `users/UserRestController` | Removes the email address from log lines | `LogLeakCheck` |
Each edit matches exact generated text. If the script prints `skipped`, the generated code differs: check it against these rules, then update the script. Checked on progen v1.0.4 with REST, Maven, JPA and PostgreSQL.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |