fete/CLAUDE.md

# fete

A privacy-focused, self-hostable PWA for event announcements and RSVPs. Alternative to Facebook Events or Telegram groups — reduced to the essentials.

## Project Statutes

These are the non-negotiable principles of this project. Every decision — architectural, technical, or design-related — must be consistent with them.

### Governance

- The agent works autonomously on implementation tasks.
- When facing architectural decisions, fundamental design questions, tech stack choices, or dependency selections: advise, propose options, and ask for approval before proceeding.
- Actively challenge decisions — including the developer's — when there are good reasons to. Don't be a yes-machine.
- When encountering problems, attempt to solve them independently first. Only escalate when stuck.

### Methodology

- Follow Research → Spec → Test → Implement → Review. No shortcuts.
- Never write implementation code without a specification.
- Always write tests before implementation (TDD). Red → Green → Refactor.
- Refactoring is permitted freely as long as it does not alter the fundamental architecture.
- No vibe coding. Every line of code must be intentional and traceable to a requirement.
- Document integrity: when a decision is revised (pivot), add an addendum with rationale — never rewrite or delete the original decision. Traceability over tidiness.
- When a setup task or user story is completed, check off its acceptance criteria in the corresponding spec file (`spec/setup-tasks.md` or `spec/userstories.md`) before committing. Progress must be tracked — no silent completions.

### Privacy

- Privacy is a design constraint, not a feature. It shapes every decision from the start.
- No analytics, no telemetry — not even self-hosted.
- Never log PII or IP addresses on the server.
- For every feature, critically evaluate what data is necessary. Only store what is absolutely required for functionality.
- Never include external dependencies that phone home: no CDNs, no Google Fonts, no tracking-capable libraries.

### Quality

- KISS and grugbrain. Engineer it properly, but don't over-engineer.
- No workarounds. Always fix the root cause, even if it takes longer.
- Address technical debt immediately. Don't let it accumulate.
- Accessibility is a baseline requirement, not an afterthought.

### Dependencies

- Every dependency is a deliberate, justified decision.
- A dependency must provide substantial value and a significant portion of its features must actually be used.
- Dependencies must be actively maintained and open source. Copyleft is fine — the project is GPL-licensed.
- Never introduce a dependency that phones home or compromises user privacy.

### Language

- Conversation and brainstorming: German.
- Code, comments, commits, documentation: English — no exceptions.

### Deployment

- The project provides a Dockerfile. How and where it is deployed is the hoster's responsibility.
- A docker-compose example in the README is sufficient.
- Documentation lives in the README. No wiki, no elaborate docs site.

### Tech Stack

- **Backend:** Java 25 (LTS, installed via SDKMAN), Spring Boot 3.5.x, Maven with wrapper (`./mvnw`)
- **Frontend:** Vue 3, TypeScript, Vue Router, Vite, Vitest, ESLint, Prettier
- **Node.js:** 24 LTS (for Docker/CI; development tolerates newer versions)
- **Base package:** `de.fete`, hexagonal architecture (single Maven module, package-level separation)
- **No Pinia** — Composition API (`ref`/`reactive`) + localStorage is sufficient
- **No JPA until T-4** — added when database infrastructure is ready

### Build Commands

| What             | Command                                |
|------------------|----------------------------------------|
| Backend test     | `cd backend && ./mvnw test`            |
| Backend run      | `cd backend && ./mvnw spring-boot:run` |
| Frontend install | `cd frontend && npm install`           |
| Frontend build   | `cd frontend && npm run build`         |
| Frontend test    | `cd frontend && npm run test:unit`     |
| Frontend dev     | `cd frontend && npm run dev`           |
| Backend checkstyle | `cd backend && ./mvnw checkstyle:check` |
| Backend full verify | `cd backend && ./mvnw verify`         |

### Agent Documentation

- Research reports: `docs/agents/research/`
- Implementation plans: `docs/agents/plan/`
- Agent test reports (browser verification): `.agent-tests/` (gitignored)
- Use the `browser-interactive-testing` skill (rodney/showboat) for visual verification — this is an agent tool, not manual work.

### Skills

The following skills are available and should be used for their respective purposes:

| Skill                         | Trigger                                      | Purpose                                                                                                                 |
|-------------------------------|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| `rpi-research`                | Deep codebase investigation needed           | Conducts thorough research and produces a written report. Use for understanding how something works before changing it. |
| `rpi-plan`                    | Feature, refactor, or bug fix needs planning | Creates detailed, phased implementation plans through interactive research and iteration.                               |
| `rpi-implement`               | Approved plan ready for execution            | Executes approved implementation plans phase by phase with automated and manual verification.                           |
| `browser-interactive-testing` | Visual verification of web pages             | Headless Chrome testing via rodney/showboat. Use for screenshots, browser automation, and visual test reports.          |

### Ralph Loops

- Autonomous work is done via Ralph Loops. See [.claude/rules/ralph-loops.md](.claude/rules/ralph-loops.md) for documentation.
- The loop runner is `ralph.sh`. Each run lives in its own directory under `.ralph/`.
- Run directories contain: `instructions.md` (prompt), `chief-wiggum.md` (directives), `answers.md` (human answers), `questions.md` (Ralph's questions), `progress.txt` (iteration log), `meta.md` (metadata), `run.log` (execution log).
- Project specifications (user stories, setup tasks, personas, etc.) live in `spec/`.