fete/README.md

fete

A privacy-focused, self-hostable web app for event announcements and RSVPs. An alternative to Facebook Events or Telegram groups — reduced to the essentials.

What it does

• Create events with title, description, date, time, location, and an expiry date
• Share a single link — guests open it, see all details, and RSVP
• No accounts, no login — the organizer gets a secret token stored in the browser; guests just enter a name
• Automatic cleanup — all event data is permanently deleted after the expiry date
• Works offline-first — installable as a PWA, local event list stored entirely in the browser

For organizers

• Edit event details, post update messages, manage the guest list
• Cancel or delete events at any time
• Generate a QR code for posters and flyers
• Optionally pick a color theme or header image (via self-hosted Unsplash proxy)

For guests

• RSVP with just a name — no personal data required
• Bookmark events locally across devices
• Download .ics or subscribe via webcal:// for calendar integration
• See highlighted changes and new update indicators on revisit

Privacy by design

• No analytics, no telemetry, no external requests from the client
• No CDNs, no Google Fonts, no tracking-capable dependencies
• Server never logs PII or IP addresses
• Data retention is bounded by a mandatory expiry date

Tech stack

Layer	Technology
Backend	Java (latest LTS), Spring Boot, Maven
Frontend	Vue 3, Vite, TypeScript
Database	PostgreSQL (external, not bundled)
Architecture	SPA + RESTful API, hexagonal/onion backend
Deployment	Single Docker container

Self-hosting

Prerequisites

• Docker and Docker Compose
• A PostgreSQL instance (self-hosted or managed)

Quick start

# docker-compose.yml
services:
  fete:
    image: fete:latest
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: "jdbc:postgresql://db:5432/fete"
      # Optional: limit simultaneous active events
      # MAX_ACTIVE_EVENTS: 100
      # Optional: enable Unsplash image search for event headers
      # UNSPLASH_API_KEY: your-api-key
    depends_on:
      - db

  db:
    image: postgres:17
    environment:
      POSTGRES_DB: fete
      POSTGRES_USER: fete
      POSTGRES_PASSWORD: changeme
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

docker compose up -d

The app runs at http://localhost:8080. Database migrations run automatically on startup.

Configuration

All configuration is done via environment variables:

Variable	Required	Description
DATABASE_URL	Yes	JDBC connection string for PostgreSQL
MAX_ACTIVE_EVENTS	No	Maximum number of non-expired events. Unset = unlimited
UNSPLASH_API_KEY	No	Enables header image search via Unsplash. Images are fetched server-side and stored locally — guests never contact Unsplash

Image storage

If you use the Unsplash header image feature, mount a persistent volume for stored images so they survive container restarts. The exact path will be documented once the feature is implemented.

Development

Prerequisites

• Java (latest LTS) + Maven
• Node.js (latest LTS) + npm
• PostgreSQL (or Docker for Testcontainers)

Project structure

fete/
├── backend/      # Spring Boot application (Maven)
├── frontend/     # Vue 3 SPA (Vite, TypeScript)
├── spec/         # User stories, personas, implementation phases
├── Dockerfile    # Multi-stage build for production
└── CLAUDE.md     # Project statutes and AI agent instructions

Running tests

# Backend (uses Testcontainers — needs Docker running)
cd backend && mvn test

# Frontend
cd frontend && npm test

Building

# Backend
cd backend && mvn package

# Frontend
cd frontend && npm run build

Code quality

Automated quality gates run as Claude Code hooks during AI-assisted development. They provide immediate feedback after every file edit and block the agent from finishing when tests fail.

Backend (Java / Maven)

After editing a *.java file (PostToolUse hook):

What	Command	Fails on
Checkstyle	./mvnw compile	Style violations (Google Style)
Java compiler	./mvnw compile	Compile errors

Checkstyle enforces Google Style (2-space indent, import order, Javadoc on public types) and is bound to the validate phase, so it runs automatically as part of every compile. Covers both src/main and src/test.

When the agent finishes (Stop hook — only if backend/src/ has uncommitted changes):

What	Command	Fails on
JUnit 5	./mvnw test	Test failures (fail-fast, stops at 1)
ArchUnit (9 rules)	./mvnw test	Hexagonal architecture violations

ArchUnit enforces hexagonal boundaries: domain must not depend on adapters, application, config, or Spring; ports must be interfaces; web and persistence adapters must not cross-depend.

Not hooked (run manually):

What	Command	Fails on
SpotBugs	./mvnw verify	Potential bugs, null dereferences, resource leaks

Frontend (TypeScript / Vue)

After editing a *.ts or *.vue file (PostToolUse hook):

What	Command	Fails on
TypeScript (strict)	vue-tsc --noEmit	Type errors
oxlint + ESLint	oxlint, eslint	Lint violations

When the agent finishes (Stop hook — only if frontend/src/ has uncommitted changes):

What	Command	Fails on
Vitest	npm run test:unit -- --run	Test failures (fail-fast, stops at 1)

Not hooked (run manually or via editor):

What	Command	Fails on
Prettier	npm run format	Formatting issues

License

GPL — see LICENSE for details.