# Quickstart: Link Preview (Open Graph Meta-Tags)

**Feature**: 012-link-preview | **Date**: 2026-03-09

## What This Feature Does

Injects Open Graph and Twitter Card meta-tags into the HTML response so that shared links display rich preview cards in messengers (WhatsApp, Telegram, Signal, etc.) and on social media (Twitter/X).

## How It Works

1. **All HTML page requests** go through a new `SpaController` (replaces the current `PathResourceResolver` SPA fallback).
2. The controller reads the compiled `index.html` template once at startup and caches it.
3. For event pages (`/events/{token}`): fetches event data, generates event-specific meta-tags, injects them into the HTML.
4. For non-event pages: injects generic fete branding meta-tags.
5. Static files (`/assets/*`, `/favicon.svg`, `/og-image.png`) continue to be served directly by Spring Boot's default static resource handler.

## Key Files to Create/Modify

### Backend (New)

| File | Purpose |
|---|---|
| `SpaController.java` | Controller handling all non-API/non-static HTML requests, injecting meta-tags |
| `OpenGraphService.java` | Service composing meta-tag values from event data |
| `MetaTagRenderer.java` | Utility rendering meta-tag value objects into HTML `<meta>` strings |

### Backend (Modified)

| File | Change |
|---|---|
| `WebConfig.java` | Remove `PathResourceResolver` SPA fallback (replaced by `SpaController`) |
| `application.properties` | Add `server.forward-headers-strategy=framework` for correct URL construction behind proxies |

### Frontend (Modified)

| File | Change |
|---|---|
| `index.html` | Add `<!-- OG_META_TAGS -->` placeholder comment in `<head>` |

### Static Assets (New)

| File | Purpose |
|---|---|
| `frontend/public/og-image.png` | Brand image for `og:image` (1200x630 PNG) |

## Testing Strategy

- **Unit tests**: `OpenGraphService` — verify meta-tag values for various event states (full data, no location, no description, long title, special characters).
- **Unit tests**: `MetaTagRenderer` — verify HTML escaping, correct meta-tag format.
- **Integration tests**: `SpaController` — verify correct HTML response with meta-tags for event URLs, generic URLs, and 404 events.
- **E2E tests**: Fetch event page HTML without JavaScript, parse meta-tags, verify values match event data.

## Local Development Notes

- In dev mode (Vite dev server), meta-tags won't be injected since Vite serves its own `index.html`. This is expected — meta-tag injection only works when the backend serves the frontend.
- To test locally: build the frontend (`npm run build`), copy `dist/` contents to `backend/src/main/resources/static/`, then run the backend.
- Alternatively, test via the Docker build which assembles everything automatically.
