AGENTS.md
💍 Wedding App – Agent Specification (Modern UI Edition)
1. Project Overview

A private wedding web app for invited guests. (Link: https://www.svenja-dominic-hochzeit.de/)

Core goals:

password-protected access (event password)

RSVP + plus-one selection

photo upload + shared gallery

modern information pages (schedule, hotels, taxi)

embedded Google Maps location

external link to the official location website 

button to switch the language of the webapp from german to english 

visually polished, modern design (mobile-first)



2. Tech Stack (Required)

Python 3.12

Flask

Gunicorn

uv (dependency management)

SQLite

Docker + Docker Compose

Frontend approach:

Use server-rendered templates (Jinja2)

Use modern CSS (prefer one of the following):

Tailwind CSS via CDN (fastest)

or a small handcrafted CSS design system (preferred if no CDN)

No heavy JS frameworks required.

3. UI / UX Design Requirements (IMPORTANT)

The site must look modern, elegant, and “wedding-like”:

Visual Style

Clean typography (Google Fonts allowed)

Soft spacing, rounded cards, subtle shadows

Consistent color palette (e.g., beige / cream / dark green / gold accents)

Smooth hover states and transitions

High-quality hero section on landing page

Layout

Mobile-first (works on phones)

Clear navigation

Dashboard cards for features (RSVP, Upload, Info)

Minimal clutter, lots of whitespace

Pages

Must implement at least:

Landing / Login page (with hero design)

Dashboard

RSVP page (or dashboard section)

Upload page

Gallery page

Info pages (schedule, hotels, taxi, location)

4. Location Page Requirements

Must include:

Embedded Google Maps iframe

Address (configurable)

A prominent button:

“Zur Location-Webseite” (or “Visit Location Website”)

open in new tab (target="_blank" rel="noopener")

The location website URL must be configurable via environment variable:

LOCATION_WEBSITE_URL

Optionally also:

LOCATION_NAME

LOCATION_ADDRESS

GOOGLE_MAPS_EMBED_URL

5. Authentication Requirements

Registration/login requires event password

Event password stored in environment variable:

EVENT_PASSWORD

Guest provides:

event password

guest name

Use Flask sessions

Keep it simple (no email verification, no roles)

6. Database Schema (Minimum)

Table: guests

id (PK)

name (required)

attending (boolean, nullable)

plus_one (boolean, default False)

created_at (timestamp)

Table: uploads

id (PK)

filename

uploaded_by (guest id)

uploaded_at (timestamp)

SQLite is sufficient.

7. RSVP Logic

In the UI:

guest selects attending Yes/No

plus_one option only shown if attending Yes

persist to database

8. Upload Requirements

allowed types: jpg, jpeg, png

configurable max upload size

sanitize filenames

prevent path traversal

store in /uploads

store upload reference in DB

9. Gallery Requirements

all guests can view uploaded images

show thumbnails in a responsive grid

click opens a larger view (simple modal or dedicated page)

10. Dependency Management Rules

Use uv

Dependencies defined in pyproject.toml

Commit uv.lock

No requirements.txt

In Docker:

uv sync --frozen --no-dev

11. Docker Requirements

Dockerfile must:

Base: python:3.12-slim

Install uv

Copy pyproject.toml + uv.lock first (cache-friendly)

Run uv sync --frozen --no-dev

Start with:

uv run gunicorn -b 0.0.0.0:8000 app:app

Uploads + SQLite database must be persistent via volumes.

12. Non-Goals (Do NOT implement)

Admin dashboards

Email systems

Payments

OAuth

External cloud storage

Microservices

13. Design Philosophy

Aesthetic first, but not overengineered

Simple, maintainable code

Minimal dependencies

Good UX on mobile