391 lines
5.1 KiB
Markdown
391 lines
5.1 KiB
Markdown
💍 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. |