docs(server): align reactor guidance

Author: FelixTJDietrich

.github/workflows/ci-server-clean-reference.yml

@@ -62,7 +62,8 @@ jobs:
         working-directory: server
         run: |
           mkdir -p ../ci-metrics/unit-architecture
-          ./mvnw -f application/pom.xml test -Parchitecture-tests -DskipCoverage=false \
+          ./mvnw -f application/pom.xml test -Parchitecture-tests \
+            -Dsurefire.includedGroups=unit,architecture -DskipCoverage=false \
             -Dmaven.build.cache.enabled=false -Dprofile=unit-architecture -DprofileFormat=JSON \
             -Dmaven-profiler-report-directory=../ci-metrics/unit-architecture --batch-mode
 

AGENTS.md

@@ -115,8 +115,9 @@ Holds wherever TypeScript is written here, the Bun agent trees and `scripts/**`
 | `webapp/src/routeTree.gen.ts` | TanStack Router Vite plugin |
 | `server/generated-clients/target/generated-sources/**` | GraphQL and Outline codegen, owned by the generated-clients Maven module |
 
-Regeneration is destructive: it empties the target directory, so stash local edits first. Commit
-generated clients alongside the API change that caused them.
+Regeneration is destructive: it empties the target directory, so do not edit or commit Maven-generated
+sources. Commit the version-controlled OpenAPI specification and webapp client alongside the API
+change that produced them.
 
 ## Database changes (Liquibase)
 

docs/contributor/ci-cd.mdx

@@ -117,6 +117,7 @@ Coolify handles PR previews:
 | `ci-docker-build.yml`  | Called by cicd.yml    | Docker image builds per component                  |
 | `ci-security-scan.yml` | Called by cicd.yml    | Dependency scanning (Trivy), secret detection      |
 | `ci-profile.yml` | Weekly, manual | Profiles server integration tests and Spring contexts |
+| `ci-server-clean-reference.yml` | Weekly, manual | Records cold server phases and compares generated JARs |
 | `verify-changesets.yml`| PRs                   | Fails shipped-code PRs that carry no changeset     |
 | `ci-compose-validate.yml` | PRs, push to main  | Renders the reference and self-host compose stacks so an interpolation or merge break is a red check, not a stranger's bad first boot |
 | `version-pr.yml`       | Push to main          | Maintains the accumulating Version PR (changesets) |
@@ -220,6 +221,11 @@ resource usage, JUnit results, and Spring context-cache metrics. It signals only
 consecutive regressions against five earlier default-branch profiles. Branch dispatches produce
 standalone diagnostic artifacts without changing or enforcing that baseline.
 
+The weekly **Server Phase Reference** workflow records cache-disabled Maven generation, compilation,
+test-compilation, and execution profiles and compares two clean generated-client JARs. GitHub Actions
+step durations remain the source for toolchain setup and artifact-upload time; Maven Profiler covers
+only work inside Maven.
+
 `SpringTestContextArchitectureTest` separately enforces the reviewed Spring context keys. Run the
 profile options locally with:
 
@@ -235,7 +241,7 @@ mkdir -p ci-metrics
 
 Before pushing, run the same checks that CI runs:
 
-### Quick Check (Recommended)
+### Full Local Check (Recommended)
 
 ```bash
 # Format and check all services
@@ -253,7 +259,7 @@ pnpm run test:webapp           # Unit tests
 
 # Application Server (Java) — includes the integration.core.webhook receiver
 pnpm run format:java:check     # Check formatting
-cd server && ./mvnw test          # Unit tests, including required reactor dependencies
+cd server && ./mvnw test       # Unit tests, including required reactor dependencies
 
 # Agent runtime (Bun) — the Pi runner and the practice precompute scripts
 pnpm run test:agents           # Runner + precompute specs

docs/contributor/local-development.mdx

@@ -45,12 +45,11 @@ pnpm run check:agents          # Biome format, then oxlint, then both typechecks
 pnpm run check:agents:fix      # Apply every safe fix
 pnpm run check:webapp          # The SPA: Biome format check, then oxlint
 pnpm run typecheck:webapp      # The SPA's typecheck — a separate leg, not part of check:webapp
-pnpm run check                 # Everything — a strict superset of CI
+pnpm run check                 # Complete local quality gate; every leg also runs in CI
 ```
 
-`check` is a superset, not a copy: PMD (`lint:java`), `check:story-sort` and `check:diagrams` run in
-no workflow, so green CI is not evidence that `check` passes. The `pre-push` hook is the only thing
-that runs them before a merge, and `--no-verify` skips it.
+Every `pnpm run check` leg also runs in CI. Run it locally before pushing because it fails faster and
+reports the complete local gate in one command.
 
 JetBrains alternatives such as IntelliJ (Java) and WebStorm (React/TypeScript) work equally well.
 
@@ -63,7 +62,7 @@ have their own `application-<name>.yml` under `server/application/src/main/resou
 the per-role and per-purpose overlays (`worker`, `webhook`, `e2e`, `cds-training`) documented where
 they are used.
 
-They are **not** Maven profiles — `./mvnw -Plocal` warns that the profile does not exist and changes
+They are **not** Maven profiles — `cd server && ./mvnw -Plocal` warns that the profile does not exist and changes
 nothing. Maven passes the active Spring profile through the `app.profiles` property, so the override
 is `-Dapp.profiles=…` (this is what `pnpm dev:server:e2e` does).
 

docs/contributor/overview.mdx

@@ -12,8 +12,9 @@ Hephaestus is maintained by the Applied Education Technologies (AET) team at TUM
 ```text
 Hephaestus/
 ├── webapp/                    # React + Vite front-end (public UI)
-├── server/                    # Spring Boot server (GitHub + mentor APIs, webhook receiver,
-│                              #   Pi mentor agent, sync NATS consumer — three runtime roles)
+├── server/                    # Maven reactor
+│   ├── application/           # Spring Boot application — server, worker, and webhook roles
+│   └── generated-clients/     # Generated GitHub, GitLab, and Outline transports
 ├── docs/                      # Docusaurus site (this documentation)
 └── scripts/                   # Tooling (ERD generation, migrations, utilities)
 ```

docs/contributor/testing.mdx

@@ -14,52 +14,30 @@ Testing keeps regression risk low across services. The application server uses M
 
    ```bash
    # Unit tests only (fast)
-   ./mvnw test
+   cd server && ./mvnw test
 
    # Full suite including integration tests
-   ./mvnw verify
+   cd server && ./mvnw verify
    ```
 
-   The reactor generates and compiles the clients on the first build. Later application and test
-   edits reuse that unchanged module automatically; no skip profile or preserved generated-source
-   directory is required.
+   Generated clients have their own module, so unchanged client inputs do not require regeneration
+   or recompilation when Maven finds a matching build-cache entry. Test selection never depends on
+   existing build output.
 
 3. Extend the correct base class:
 
-   ```java
-   // Unit test
-   class UserServiceTest extends BaseUnitTest { }
-
-   // Integration test
-   class UserServiceIntegrationTest extends BaseIntegrationTest { }
-   ```
+   Unit tests extend `BaseUnitTest`; Spring-backed tests extend `BaseIntegrationTest` or a
+   feature-specific subclass.
 
 :::warning Naming matters
 Use `*Test.java` for unit tests and `*IntegrationTest.java` for integration tests. Maven's surefire and failsafe plugins use these patterns.
 :::
 
-## Why testing?
-
-Tests catch regressions before they hit production, document expected behaviour, and unlock safe refactors. Our setup keeps the feedback loop fast – unit tests finish in under a second, while the shared Testcontainers environment limits the cost of integration suites.
-
 ## Unit tests
 
 - Extend `BaseUnitTest` for isolated component tests.
 - Use Mockito (`@Mock`, `@InjectMocks`) for dependencies.
-- Expect sub-second runtime – no Spring context is loaded.
-
-```java
-class UserServiceTest extends BaseUnitTest {
-    @Mock private UserRepository repository;
-    @InjectMocks private UserService service;
-
-    @Test
-    @DisplayName("Should validate email format")
-    void shouldValidateEmailFormat() {
-        // Fast isolated test
-    }
-}
-```
+- Keep unit tests independent of Spring contexts and Testcontainers.
 
 ## Integration tests
 
@@ -137,7 +115,7 @@ The `hephaestus.tenancy.enforcement: throw` setting in `application-test.yml` fa
 
 ## Webhook fixtures and tooling
 
-Reusable webhook JSON lives in `src/test/resources/github`, named after the event it records. Load one with a `ClassPathResource`, or extract new samples with:
+Reusable webhook JSON lives in `server/application/src/test/resources/github`, named after the event it records. Load one with a `ClassPathResource`, or extract new samples with:
 
 ```bash
 pnpm run nats:extract-examples
@@ -182,7 +160,7 @@ Each annotation pins JUnit to `Execution(SAME_THREAD)` so two live tests in the
 ### Authoring a new live test
 
 1. Pick the right meta-annotation. If the env var doesn't exist yet, add a new annotation alongside the existing four — don't reuse one with a misleading name.
-2. Put the test under `src/test/java/.../live/`. The directory marker keeps live and non-live tests in different code-review buckets.
+2. Put the test under `server/application/src/test/java/.../live/`. The directory marker keeps live and non-live tests in different code-review buckets.
 3. Read credentials from `LiveLlmCredentials.fromEnv()` (or the GitHub helpers); never inline values. Secrets stay in env vars only.
 4. Per-test wall-clock timeouts: 90s is reasonable for a single mentor turn; 5 minutes for a full practice run.
 

docs/decisions/0001-flat-top-level-layout.md

@@ -1,6 +1,6 @@
 # ADR 0001: Flat top-level layout
 
-**Status:** Superseded by [ADR 0032](0032-generated-clients-build-boundary.md)
+**Status:** Accepted
 **Date:** 2026-05-20
 **Authors:** Server foundations epic (#1097)
 

docs/decisions/0002-java-package-rename-to-aet-cit-tum.md

@@ -6,7 +6,7 @@
 
 ## Context
 
-The Java code under `server/application/src/main/java/` used `de.tum.in.www1.hephaestus` — a legacy
+The Java code under `server/src/main/java/` used `de.tum.in.www1.hephaestus` — a legacy
 TUM naming convention referencing the "Informatics, chair www1" structure. That structure
 has since been reorganized into CIT (Computation, Information and Technology) with
 multiple chairs at `*.cit.tum.de`. The legacy package name no longer reflects organisation

docs/decisions/0032-generated-clients-build-boundary.md

@@ -47,9 +47,10 @@ Only generated-client output participates in Maven Build Cache; the application
 and saving build output. Pull requests may restore an exact generated entry, while only the default
 branch may publish one.
 
-Maven Build Cache addresses output from effective build inputs. CI persists its local cache using an
-exact source-and-toolchain key. The scheduled Server Phase Reference workflow monitors byte
-reproducibility by comparing two clean generated-client builds with caching disabled.
+Maven Build Cache computes checksums from configured inputs and the effective Maven model. CI wraps
+its local cache in an exact source-and-toolchain Actions cache key. The scheduled Server Phase
+Reference workflow monitors byte reproducibility by comparing two clean generated-client builds with
+caching disabled.
 
 ## Consequences
 
@@ -60,11 +61,21 @@ reproducibility by comparing two clean generated-client builds with caching disa
 - Commands start at `server/`; deployable-only invocations target `application` after installing its
   reactor dependency.
 - Tooling addresses module-owned paths rather than the former monolithic source and output trees.
-- ADR 0001 remains valid for organizational nesting; this reactor adds an enforceable build-lifecycle
-  boundary.
+- ADR 0001's rationale against organizational nesting remains applicable; this reactor adds an
+  enforceable build-lifecycle boundary.
 
 ## Revisit when
 
 Reconsider the mechanism if cache validation or reproducibility fails, cache transfer cost erases the
-measured gain, or Maven Build Cache support changes materially. Preserve the generated/application
-ownership boundary unless their lifecycles cease to differ.
+measured gain, or Maven Build Cache support changes materially. Re-test removal of the Relay wrapper
+cleanup when GraphQL Java Codegen is upgraded. Preserve the generated/application ownership boundary
+unless their lifecycles cease to differ.
+
+## References
+
+- [Issue #1527](https://github.com/ls1intum/Hephaestus/issues/1527) and
+  [PR #1529](https://github.com/ls1intum/Hephaestus/pull/1529) contain the measurements and hosted
+  observation record.
+- [Maven reactor builds](https://maven.apache.org/guides/mini/guide-multiple-modules.html)
+- [Maven Build Cache concepts](https://maven.apache.org/extensions/maven-build-cache-extension/concepts.html)
+- [Maven reproducible builds](https://maven.apache.org/guides/mini/guide-reproducible-builds.html)

docs/decisions/README.md

@@ -70,5 +70,6 @@ do, its home is the Admin Guide (`docs/admin/`) and the runbook links to it.
 | [0029](0029-measurement-intervention-seam-and-channel-levels.md) | Measurement and intervention are separate turns; a channel names where feedback lands, and its level follows | Accepted |
 | [0030](0030-agent-runtime-is-typescript-on-bun.md) | The agent runtime is TypeScript on Bun, with no Node in the sandbox | Accepted |
 | [0031](0031-agent-image-follows-the-deployments-own-tag.md) | The agent image reference follows the deployment's own image tag | Accepted |
+| [0032](0032-generated-clients-build-boundary.md) | Generated clients are a Maven build boundary | Accepted |
 
 Template: [0000-template.md](0000-template.md).