Controller-Layer Structure — refactor-chain · backend lane · step 05/09

Bundle: refactor-chain (self-diagnosing, self-healing fix-it pipeline). Phase: do-the-work · Prerequisite: refactor-backend-04-service · Next: refactor-backend-06-dependency-guard. Adaptivity / conditional: repo-agnostic — works on any layered backend project in any registry-detected stack. The two audience sub-packages default to external/ and internal/; projects with an existing convention (e.g. custom//common/, open//admin/) keep their names.

Purpose

Check and, on request, fix the controller layer so every controller lives under controller/<external>/<group>/ or controller/<internal>/<domain>/. Admission is annotation-truth: a file is a controller only if it carries an active (uncommented) @RestController/@Controller annotation — file names prove nothing. Placement comes from a three-level deterministic chain (exact-name table → keyword table → default external), so repeated runs agree. Only package lines, import lines, and file locations change.

When to use

• After the service step (04) and before the dependency guard (06).
• You say things like: "controller layer check", "controller layer fix", "separate external and internal controllers", "why is this controller under config/", "organize controllers by audience".
• Controllers are scattered under feature/config packages, or sit in packages that disagree with the classification chain's computed target.