fete/docs/agents/plan/2026-03-04-t1-monorepo-setup.md

Implementation Plan: T-1 — Initialize Monorepo Structure

Context

This is the first setup task for the fete project — a privacy-focused, self-hostable PWA for event announcements and RSVPs. The repository currently contains only documentation, specs, and Ralph loop infrastructure. No application code exists yet.

The tech stack was decided during the research phase (see docs/agents/research/2026-03-04-t1-monorepo-setup.md):

• Backend: Java 25 (latest LTS), Spring Boot 4.0 Spring Boot 3.5.11 (see addendum), Maven, hexagonal architecture, base package de.fete
• Java installation: Via SDKMAN! (sdk install java 25-open), no system-level JDK
• Frontend: Vue 3, Vite, TypeScript, Vue Router, Vitest
• Node.js: Latest LTS (24)

Phase 1: Backend Scaffold

1.1 Create directory structure

Create backend/ with the hexagonal architecture package layout:

backend/
├── pom.xml
├── mvnw, mvnw.cmd
├── .mvn/wrapper/maven-wrapper.properties
└── src/
    ├── main/
    │   ├── java/de/fete/
    │   │   ├── FeteApplication.java
    │   │   ├── domain/
    │   │   │   ├── model/package-info.java
    │   │   │   └── port/
    │   │   │       ├── in/package-info.java
    │   │   │       └── out/package-info.java
    │   │   ├── application/
    │   │   │   └── service/package-info.java
    │   │   ├── adapter/
    │   │   │   ├── in/web/package-info.java
    │   │   │   └── out/persistence/package-info.java
    │   │   └── config/package-info.java
    │   └── resources/
    │       └── application.properties
    └── test/
        └── java/de/fete/
            └── FeteApplicationTest.java

1.2 Create pom.xml

• Parent: spring-boot-starter-parent (latest 4.0.x, or fall back to 3.5.x if 4.0 is unavailable)
• GroupId: de.fete, ArtifactId: fete-backend
• Java version: 25
• Dependencies:
  • spring-boot-starter-web (embedded Tomcat, Spring MVC)
  • spring-boot-starter-test (scope: test)
  • NO JPA yet (deferred to T-4)

1.3 Add Maven Wrapper

Generate via mvn wrapper:wrapper (or manually create the wrapper files). This ensures contributors and Docker builds don't need a Maven installation.

1.4 Create application class

FeteApplication.java in de.fete — minimal @SpringBootApplication with main().

1.5 Create a minimal health endpoint

A simple @RestController in adapter/in/web/ that responds to GET /health with HTTP 200 and a JSON body like {"status": "ok"}. This satisfies:

• The user's requirement that a REST request returns 200
• Prepares for T-2's health-check requirement

1.6 Create package-info.java markers

One per leaf package, documenting the package's purpose and architectural constraints. These serve as Git directory markers AND developer documentation.

1.7 Write integration test

FeteApplicationTest.java:

• @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
• Test 1: Spring context loads successfully
• Test 2: HTTP GET to /health returns 200

1.8 Verify backend

• cd backend && ./mvnw test — tests pass (context loads + health endpoint returns 200)
• cd backend && ./mvnw spring-boot:run — app starts on port 8080
• curl http://localhost:8080/health — returns 200 with {"status": "ok"}

Phase 2: Frontend Scaffold

2.1 Scaffold Vue project

Run npm create vue@latest in frontend/ with these options:

• TypeScript: Yes
• Vue Router: Yes
• Pinia: No
• Vitest: Yes
• ESLint: Yes
• Prettier: Yes
• E2E: No

If the interactive prompts can't be automated, create the project manually based on the create-vue template output.

2.2 Add composables/ directory

Create src/composables/ (empty, with a .gitkeep or initial placeholder) — convention for Composition API composables needed later.

2.3 Verify frontend builds and tests

• cd frontend && npm install
• cd frontend && npm run build — builds successfully
• cd frontend && npm run test:unit — Vitest runs (sample test passes)

2.4 Verify via browser

• cd frontend && npm run dev — starts dev server
• Use browser-interactive-testing skill to visit the dev server URL and verify the page loads

Phase 3: Shared Files

3.1 Update .gitignore

Extend the existing .gitignore with sections for:

• Java/Maven (target/, *.class, *.jar, Maven release files, crash logs)
• Node.js/Vue/Vite (node_modules/, dist/, build/, vite temp files)
• Environment files (.env, .env.* but NOT .env.example)
• Editor swap files (*.swp, *.swo, *~)
• Spring Boot (.springBeans, .sts4-cache)

Keep existing entries (IDE, OS, Claude settings) intact.

3.2 Verify .gitignore

Run git status after building both projects to confirm build artifacts are properly ignored.

• git status shows no target/, node_modules/, dist/, or other build artifacts

Verification Checklist (Done Criteria)

Backend

• cd backend && ./mvnw test passes (integration test: context loads + GET /health → 200)
• cd backend && ./mvnw spring-boot:run starts successfully
• curl http://localhost:8080/health returns HTTP 200
• Hexagonal package structure exists with package-info.java markers

Frontend

• cd frontend && npm run build succeeds
• cd frontend && npm run test:unit runs and passes
• Browser verification via browser-interactive-testing skill confirms page loads

Shared

• .gitignore covers Java/Maven + Node/Vue artifacts
• git status shows no unintended tracked build artifacts
• T-1 acceptance criteria from spec/setup-tasks.md are met

Files to Create/Modify

Create:

• backend/pom.xml
• backend/mvnw, backend/mvnw.cmd, backend/.mvn/wrapper/maven-wrapper.properties
• backend/src/main/java/de/fete/FeteApplication.java
• backend/src/main/java/de/fete/adapter/in/web/HealthController.java
• backend/src/main/java/de/fete/domain/model/package-info.java
• backend/src/main/java/de/fete/domain/port/in/package-info.java
• backend/src/main/java/de/fete/domain/port/out/package-info.java
• backend/src/main/java/de/fete/application/service/package-info.java
• backend/src/main/java/de/fete/adapter/in/web/package-info.java
• backend/src/main/java/de/fete/adapter/out/persistence/package-info.java
• backend/src/main/java/de/fete/config/package-info.java
• backend/src/main/resources/application.properties
• backend/src/test/java/de/fete/FeteApplicationTest.java
• frontend/ (entire scaffolded project via create-vue)

Modify:

• .gitignore (extend with Java/Maven + Node/Vue sections)

Addendum: Spring Boot 4.0 → 3.5 Pivot

During implementation, Spring Boot 4.0.3 was abandoned in favor of 3.5.11. The 4.0 release reorganized test infrastructure into new modules and packages (TestRestTemplate → spring-boot-resttestclient, AutoConfigureMockMvc → unknown location) without adequate migration documentation. Multiple attempts to resolve compilation and auto-configuration errors failed, making it impractical for the scaffold phase.

The pivot has no impact on project architecture or future tasks. Migration to 4.x can be revisited once the ecosystem matures. See the research report addendum for full details.