# PLAN — delivery phases

Work proceeds **one phase at a time**. At each phase gate: build + tests are run,
a short summary and any decision (ADR) are reported, then work **stops and waits
for an explicit "continue"** before the next phase begins (see `docs/PROMT.md` §11).

## Resolved configuration (FILL-IN defaults)

| Key | Value |
|---|---|
| `APP_NAME` | `demo` |
| `BASE_PACKAGE` | `com.codebyte.api` |
| `BUILD_TOOL` | Maven |
| `JAVA_VERSION` | 21 |
| Spring Boot | 3.5.16 |
| `CI_PLATFORM` | GitHub Actions |
| `REGISTRY` | `ghcr.io/<owner>/<repo>` |
| `MAIL_PROVIDER` | SMTP (env), MailHog in dev / GreenMail in tests |
| `DEPLOY_TARGET` | single Linux VM over SSH + docker compose |

## Phase checklist

- [x] **0 — Skeleton & build.** Maven with Spotless, Checkstyle, SpotBugs,
  Surefire/Failsafe split, JaCoCo, PIT wired. `CLAUDE.md`, `README.md` skeleton,
  `.editorconfig`, `.gitignore`, `docs/adr/0001-stack.md`, this `PLAN.md`.
- [x] **1 — Docker & boot.** `Dockerfile`, `docker-compose.yml`, `.env.example`;
  app boots on 4455 with Actuator + live Postgres; one smoke integration test.
- [x] **2 — Persistence.** Flyway `V1__init.sql` (items), `Item` entity + JPA
  auditing, repository, ArchUnit tests, singleton Testcontainers base class,
  migration + persistence integration tests.
- [x] **3 — Item CRUD.** DTOs (records), MapStruct mapper, service, controller,
  RFC 7807 `ProblemDetail` handler, pagination/filtering, full unit + IT.
  JaCoCo gate ON for `item.service` (100% line/branch); PIT 95%. OpenAPI/Swagger
  deferred to Phase 8 per the phase table.
- [x] **4 — Users & registration.** User/roles/OneTimeToken domain (V2 migration),
  registration + activation, Argon2id encoder, password policy, SMTP mail
  (MailHog/GreenMail), no-enumeration behaviour, tests. Gate ON for `auth.service`.
  *(Activation resend + rate limiting deferred to Phase 6.)*
- [x] **5 — Security.** Stateless JWT SecurityConfig (HS256 resource server),
  login with lockout + no-enumeration, opaque refresh rotation + reuse detection,
  logout, `/users/me`, RFC7807 401/403, authz-matrix + full-journey ITs.
  `auth.service` gate: 100% line / 92% branch.
- [x] **6 — Account recovery.** Forgot/reset password (revokes all refresh tokens),
  activation resend, prior-token invalidation, in-memory token-bucket rate
  limiting on `/auth/**` (single-instance), tests. auth.service 100%/96%.
- [x] **7 — TLS.** In-memory `SslBundleRegistrar` from the cert/CA/key trio (chain
  assembly, PKCS#1/#8 plain+encrypted keys, fail-fast validation), `ssl` health
  indicator + expiry metric, `prod` profile, `docker-compose.prod.yml`,
  `scripts/gen-dev-certs.sh`, `docs/ssl.md`, HTTPS leaf+intermediate chain IT.
- [x] **8 — Observability.** springdoc OpenAPI + Swagger UI, `X-Request-Id` MDC
  correlation filter + ECS JSON logs (prod), Prometheus metrics (authenticated),
  graceful shutdown, HikariCP + Tomcat tuning, JVM flags documented.
- [x] **9 — CI.** GitHub Actions stages 1–7 (validate → unit-test →
  integration-test → coverage-gate (merge+comment) → security(Trivy) → build →
  docker (multi-arch, SBOM, provenance, cosign)); `make verify`/`verify.sh`,
  Dependabot, `.trivyignore`. All job commands validated locally.
- [x] **10 — CD.** Reusable `deploy.yml` (SSH + compose pull/up + health wait +
  smoke), auto staging on `main` / protected prod on tags, `rollback.yml`,
  deploy/smoke/rollback scripts, secrets checklist + forward-only migration
  policy (`docs/deployment.md`).
- [x] **11 — Docs.** Full `README.md` (quickstart/test/API/deploy/troubleshoot),
  operational runbook (`docs/runbook.md`), auth threat model (`docs/security.md`),
  final full-suite verification (125 tests green, PIT 80%, container boot).
- [x] **12 — Postman.** OpenAPI-derived collection (`gen-postman.sh`) enriched with
  bearer auth, token capture, MailHog-driven **Smoke** folder + negative paths;
  local/staging/prod envs (placeholders only); Newman validated (Smoke 14 / Negative
  6 assertions green) and wired into staging CD.

## Definition of Done (every phase)

`mvn verify` green · unit + IT written and passing · coverage gates met (once
enabled) · Spotless/Checkstyle/SpotBugs clean · `docker compose up` healthy on
4455 · OpenAPI matches reality · ADR written if a decision was made · no secrets,
no dead/commented-out code, no unused deps · conventional-commit message proposed.