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

- [x] `cd backend && ./mvnw test` — tests pass (context loads + health endpoint returns 200)
- [x] `cd backend && ./mvnw spring-boot:run` — app starts on port 8080
- [x] `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

- [x] `cd frontend && npm install`
- [x] `cd frontend && npm run build` — builds successfully
- [x] `cd frontend && npm run test:unit` — Vitest runs (sample test passes)

### 2.4 Verify via browser

- [x] `cd frontend && npm run dev` — starts dev server
- [x] 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.

- [x] `git status` shows no `target/`, `node_modules/`, `dist/`, or other build artifacts

## Verification Checklist (Done Criteria)

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

### Frontend
- [x] `cd frontend && npm run build` succeeds
- [x] `cd frontend && npm run test:unit` runs and passes
- [x] Browser verification via `browser-interactive-testing` skill confirms page loads

### Shared
- [x] `.gitignore` covers Java/Maven + Node/Vue artifacts
- [x] `git status` shows no unintended tracked build artifacts
- [x] 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.