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

```yaml
# 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:
```

```bash
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

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

# Frontend
cd frontend && npm test
```

### Building

```bash
# 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](LICENSE) for details.