💍 AGENTS.md

Wedding App – Agent Specification (Hero + Secure Edition)

1. Project Overview

A private wedding web application for invited guests.

Production URL:

https://www.svenja-dominic-hochzeit.de/

The entire platform is protected by login.
There is no public content accessible without authentication.

Core goals:

password-protected access (event password)

RSVP + plus-one selection

photo upload + shared gallery

modern information pages (schedule, hotels, taxi, location)

embedded Google Maps (2-click solution)

external link to official location website

language switch (German / English)

visually polished, modern, mobile-first UI

2. Access Model (IMPORTANT)

The entire site must be login-protected.

No publicly accessible landing page.

Flow:

User visits root URL → redirected to login

User enters:

event password

guest name

On success:

guest stored in database (if new)

session created

redirect to internal start page

All internal routes must require authentication.

3. Internal Start Page Structure (Hero + Dashboard Concept)

After login, the start page consists of two sections:

Section 1 – Hero Area (Emotional Welcome)

Must include:

large background image

headline:
“Willkommen zu unserer Hochzeit”

wedding date

short personal text

smooth scroll transition to dashboard

Purpose:
Make the platform feel emotional and elegant, not like a business app.

Section 2 – Dashboard Area

Below the hero section:

Card-based grid layout containing:

RSVP

Upload

Gallery

Ablauf (Schedule)

Hotels

Taxi

Location

The dashboard must:

use rounded cards

soft shadows

consistent spacing

mobile-first responsive layout

4. Tech Stack (Required)

Python 3.12
Flask
Gunicorn
uv (dependency management)
SQLite
Docker + Docker Compose

Frontend:

Jinja2 templates

Tailwind via CDN OR lightweight custom CSS

No heavy JS frameworks

Minimal JavaScript only where needed

5. UI / UX Requirements (Very Important)

Visual style:

elegant and modern

wedding-like aesthetic

soft spacing

rounded elements

subtle shadows

warm color palette (cream / beige / dark green / gold accents)

clean typography (Google Fonts allowed)

Mobile-first design required.

Minimal clutter.

Smooth hover transitions.

6. Language Switch (DE / EN)

Must include:

language toggle in header

switch stored in session

no automatic geo-detection

static text controlled via simple translation dictionary or structure

7. Location Page Requirements

Must include:

Location name (env variable)

Address (env variable)

Google Maps embed (iframe)

Prominent button:

“Zur Location-Webseite” / “Visit Location Website”

target="_blank"

rel="noopener"

Environment variables:

LOCATION_NAME
LOCATION_ADDRESS
LOCATION_WEBSITE_URL
GOOGLE_MAPS_EMBED_URL

Google Maps Privacy Requirement

Google Maps must NOT load automatically.

Implement a 2-click solution:

Show placeholder container

Display privacy notice:
“Zur Anzeige der Karte werden Daten an Google übertragen.”

Only after user click → load iframe dynamically

No global cookie banner required.

8. Authentication Requirements

Event password stored in environment variable:

EVENT_PASSWORD

Guest provides:

event password

name

Use Flask sessions.

No:

email verification

role system

admin panel

9. Database Schema

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 only.

10. RSVP Logic

Guest selects:

attending Yes / No

plus_one only visible if attending Yes

Persist to database.

11. Upload Requirements

Allowed types:

jpg
jpeg
png

Must:

validate file extension

validate MIME type

limit file size (configurable)

sanitize filenames

prevent path traversal

store files in /uploads

store reference in database

Optional but recommended:

remove EXIF metadata before saving

12. Gallery Requirements

All guests see all images

Responsive grid layout

Click → larger view (simple modal)

No download tracking

13. Legal Pages (Important)

Must implement:

/datenschutz

/impressum

Both:

accessible without login (legal requirement)

linked in footer

always visible in footer

No cookie banner required because:

only technically necessary session cookies used

Google Maps loaded via 2-click solution

14. Dependency Management Rules

Use uv.

Dependencies defined in:

pyproject.toml

Commit:

uv.lock

No requirements.txt allowed.

Docker must run:

uv sync --frozen --no-dev

15. Docker Requirements

Base image:

python:3.12-slim

Must:

install uv

copy pyproject.toml + uv.lock first (cache optimization)

run uv sync --frozen --no-dev

expose port 8000

start with:

uv run gunicorn -b 0.0.0.0:8000 app:app

Uploads + SQLite database must use persistent volumes.

16. Non-Goals (Strict)

Do NOT implement:

Admin dashboards

Email systems

Payment systems

OAuth

Cloud storage

Microservices

Tracking tools

Analytics tools

17. Design Philosophy

Aesthetic first, but not overengineered.
Simple, maintainable code.
Minimal dependencies.
Excellent mobile UX.
Elegant, but not playful.