6.5 KiB
💍 AGENTS.md
Wedding App – Agent Specification (Hero + Secure + Group Edition)
- 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
invitation-based access system
group-based RSVP handling
photo upload + shared gallery with permission control
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
- Access Model (IMPORTANT – UPDATED)
The entire site must be login-protected.
No publicly accessible landing page.
Invitation-Based Authentication Model
Each account represents one invitation.
An invitation can be:
a single person
a family
a couple
any defined group
Even single guests are technically treated as a group with one member.
Login Flow
User visits root URL → redirected to login
User enters:
group password
group name (predefined)
On success:
group loaded from database
session created
redirect to internal start page
No free registration allowed.
Each group has:
a predefined group name
an individual password
Different groups → different passwords.
Group Management After Login
After login, the group sees:
all predefined members of their invitation
RSVP selection per member
For each member:
attending Yes / No
Only one person per group must log in and manage the responses.
- Roles System (NEW)
Two roles must exist:
Role: Guest (Default)
Can:
manage RSVP for their group
upload images
delete only their own uploaded images
Cannot:
delete images uploaded by others
Role: Admin (Hosts)
Can:
delete any uploaded image
manage all groups
optionally view attendance overview
No public admin panel required, but role logic must exist internally.
- 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
Dashboard must:
use rounded cards
soft shadows
consistent spacing
mobile-first responsive layout
Navigation Requirement (NEW)
A back button (arrow icon) must exist:
visible in header area
allows navigation back to previous page
must NOT replace logout button
Logout remains separate and visible.
- 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
- 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.
- 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
- RSVP Logic (UPDATED – GROUP BASED)
Database structure must support:
group entity
group members
Each group contains:
multiple persons
For each person:
attending (boolean)
Optional plus-one logic may be removed since groups now define structure.
Persist responses per individual.
- Image Upload & Gallery System (UPDATED) 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
Uploads must support:
mobile gallery uploads (iOS / Android compatible input field)
Optional but recommended:
remove EXIF metadata before saving
Gallery Requirements
All authenticated guests see all images.
Responsive grid layout.
Click → larger modal view.
Image Permissions (NEW)
Guest:
may delete only images where: image.uploaded_by == current_user.id
Admin:
may delete any image
Every image must have:
visible download button
direct file download (no right-click dependency)
Optional:
future ZIP export of all images
- 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 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.
- Database Schema (UPDATED)
Table: groups
id (PK)
name (required)
password_hash
role (guest / admin)
created_at
Table: group_members
id (PK)
group_id (FK)
name
attending (boolean, nullable)
Table: uploads
id (PK)
filename
uploaded_by (group id)
uploaded_at (timestamp)
SQLite only.
- Legal Pages (Important)
Must implement:
/datenschutz /impressum
Both:
accessible without login (legal requirement)
linked in footer
always visible
- 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
- 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.
- Non-Goals (Strict)
Do NOT implement:
email systemsnur
payment systems
OAuth
cloud storage
microservices
tracking tools
analytics tools
- Design Philosophy
Aesthetic first, but not overengineered. Simple, maintainable code. Minimal dependencies. Excellent mobile UX. Elegant, mature, emotionally warm.
Not playful. Not corporate. Not overcomplex.