wedding-website/plans/wedding-bootstrap-plan.md

# Wedding Website Bootstrap Plan

## Goal

Build the dynamic foundation for a wedding website before final visual/content design is complete.

The website should support:

- A public wedding homepage with static sections and personalized guest content.
- Unique invitation links for each invited group/household.
- RSVP and per-person attendance/meal collection.
- Optional guest contributions such as song requests, toast requests, messages, and one photo upload.
- A private `/admin` portal restricted to the couple through Google login.
- A Docker Compose runtime with PostgreSQL and MinIO.

## Confirmed decisions

### Application stack

- Framework: Next.js App Router.
- Database: PostgreSQL.
- Query layer: Kysely, no ORM.
- Authentication: Google OAuth.
- Admin access: restricted by email allowlist from `.env`.
- Object storage: MinIO using S3-compatible APIs.
- Deployment/runtime style: Docker Compose.
- Admin UI component system: shadcn/ui only.

### Admin UI requirement

All UI components used in the admin area must come from shadcn/ui.

This applies to every admin page under:

```txt
/admin
/admin/*
```

The admin area must use shadcn/ui components for:

- layout primitives where applicable
- cards
- buttons
- forms
- inputs
- selects
- checkboxes
- dialogs
- dropdown menus
- tables
- badges
- tabs
- alerts
- toasts/sonner notifications
- action menus
- empty states where applicable
- loading/skeleton states

Custom admin UI should only be composed from shadcn/ui components and small local wrappers around them. Do not introduce another component library for the admin portal.

If a needed admin component is not yet installed from shadcn/ui, add it through the shadcn workflow and then reuse it consistently.

The guest-facing invitation pages may have custom wedding-themed design, but the admin management UI must remain shadcn-based.

### Invitation model

- The primary guest-facing unit is an `Invitation`, not an individual guest.
- An invitation represents a household, couple, family, individual guest, or group.
- Each invitation has one unique private token and one invite URL:

```txt
/invite/[token]
```

- Each invitation must have a required language.
- The invitation language is the source of truth for which language the guest-facing invitation page uses.
- This is a core requirement because many guests may only speak one of the wedding languages.
- Admins choose the invitation language when creating or editing an invitation.
- Admin pages can remain in the couple's preferred management language initially, but guest-facing copy must respect the invitation language.

### Invitation members

- Each invitation contains one or more `InvitationMember` records.
- Members are modeled from the start because attendance and food choices can differ per person.
- Per-person attendance lives on `invitation_members.attending`.
- The response table must not duplicate attendance status.

### RSVP/response model

- `invitation_members` owns per-person answers:
  - attending
  - meal preference
  - dietary restrictions
- `invitation_responses` owns group-level logistics:
  - submitted timestamp
  - travel dates
  - stay location
  - transport help
  - message to the couple
- RSVP edits are allowed until a configured deadline.

### Photo uploads

- One image per invitation/group.
- The image may be replaced until the deadline.
- Store files in MinIO.
- Store object metadata in PostgreSQL.

### Optional wedding interactions

Include these from the bootstrap if feasible:

- Song requests.
- Optional toast/speech request.
- Advice, wish, or favorite memory message.

## Proposed environment variables

```env
DATABASE_URL=postgres://wedding:wedding@localhost:5432/wedding

AUTH_SECRET=change-me
AUTH_GOOGLE_ID=change-me
AUTH_GOOGLE_SECRET=change-me
ADMIN_EMAILS=person-one@example.com,person-two@example.com

APP_URL=http://localhost:3000
RSVP_DEADLINE=2026-08-01

S3_ENDPOINT=http://localhost:9000
S3_REGION=us-east-1
S3_BUCKET=wedding-uploads
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_FORCE_PATH_STYLE=true
```

## Target folder structure

```txt
app/
  page.tsx
  invite/
    [token]/
      page.tsx
  admin/
    page.tsx
    guests/
      page.tsx
      new/
        page.tsx
      [id]/
        page.tsx
  api/
    auth/
      [...nextauth]/
        route.ts
    uploads/
      presign/
        route.ts
      complete/
        route.ts

lib/
  auth.ts
  config.ts
  db/
    client.ts
    types.ts
    queries/
      invitations.ts
      members.ts
      responses.ts
      uploads.ts
      song-requests.ts
      toast-requests.ts
      guest-messages.ts
  storage/
    s3.ts
    uploads.ts
  i18n/
    config.ts
    dictionaries/
      en.ts
      es.ts
      de.ts
  validation/
    invitation.ts
    response.ts
    upload.ts
    interactions.ts

scripts/
  migrate-sql.mjs

migrations/
  0001_initial_schema.sql

docker-compose.yml
plans/
  wedding-bootstrap-plan.md
```

## Database schema plan

### `invitations`

Represents one invite/group/household.

```txt
id uuid primary key
token text unique not null
display_name text not null
language text not null
contact_email text
contact_phone text
max_party_size integer not null default 1
allow_member_edits boolean not null default false
notes text
created_at timestamptz not null
updated_at timestamptz not null
```

Notes:

- `token` must be unguessable.
- `display_name` is what the guest sees, e.g. `Ana & Luis` or `The Garcia Family`.
- `language` controls guest-facing page copy and form labels for this invitation.
- Recommended initial language values should be short locale codes such as `en`, `es`, `de`, etc.
- `allow_member_edits` allows flexible +1 or family edits later.

### `invitation_members`

Represents each individual person under an invitation.

```txt
id uuid primary key
invitation_id uuid not null references invitations(id) on delete cascade
name text not null
is_primary_contact boolean not null default false
attending boolean
meal_preference text
dietary_restrictions text
notes text
created_at timestamptz not null
updated_at timestamptz not null
```

Notes:

- `attending = null` means pending/unanswered.
- Attendance status is derived from this table, not from `invitation_responses`.
- Meal preference examples: `meat`, `fish`, `vegetarian`, `vegan`, `kids`, `other`.

### `invitation_responses`

Stores group-level RSVP metadata and logistics.

```txt
id uuid primary key
invitation_id uuid unique not null references invitations(id) on delete cascade
submitted_at timestamptz
arrival_date date
departure_date date
stay_location text
coming_from text
needs_transport_help boolean
message_to_couple text
created_at timestamptz not null
updated_at timestamptz not null
```

Notes:

- No attendance status here.
- No attendee count here.
- Admin dashboard derives totals from `invitation_members`.

### `photo_uploads`

Stores one uploaded activity/surprise image per invitation.

```txt
id uuid primary key
invitation_id uuid unique not null references invitations(id) on delete cascade
bucket text not null
object_key text not null
original_filename text
content_type text
size_bytes integer
created_at timestamptz not null
updated_at timestamptz not null
```

Notes:

- Unique `invitation_id` enforces one photo per invitation.
- Replacing a photo updates this record and may delete/overwrite the old object.

### `song_requests`

Stores optional party song requests.

```txt
id uuid primary key
invitation_id uuid not null references invitations(id) on delete cascade
title text not null
artist text
note text
created_at timestamptz not null
```

Notes:

- Recommended limit: up to 3 song requests per invitation.

### `toast_requests`

Stores optional requests to say a few words.

```txt
id uuid primary key
invitation_id uuid not null references invitations(id) on delete cascade
member_id uuid references invitation_members(id) on delete set null
speaker_name text not null
estimated_minutes integer
note text
status text not null default 'pending'
created_at timestamptz not null
updated_at timestamptz not null
```

Recommended statuses:

```txt
pending
accepted
declined
scheduled
```

Notes:

- Toast requests are voluntary.
- Admin approval is required before scheduling.

### `guest_messages`

Stores optional advice, wishes, or memories.

```txt
id uuid primary key
invitation_id uuid not null references invitations(id) on delete cascade
type text not null
message text not null
created_at timestamptz not null
```

Recommended message types:

```txt
advice
memory
wish
```

### `admin_audit_events` optional

Useful but not required for the first pass.

```txt
id uuid primary key
admin_email text not null
action text not null
target_type text
target_id uuid
metadata jsonb
created_at timestamptz not null
```

## Derived RSVP status logic

Admin-facing status should be computed instead of stored redundantly.

Suggested derived statuses:

```txt
Pending
  invitation_response.submitted_at is null

Partially answered
  submitted_at exists and at least one member has attending = null

Attending
  at least one member has attending = true and no members are pending

Declined
  all members have attending = false and no members are pending

Partial
  at least one member attending = true and at least one member attending = false
```

Dashboard metrics can derive:

- total invitations
- total invited members
- attending members
- declined members
- pending members
- invitations with submitted responses
- invitations with uploaded photos
- song request count
- pending toast requests

## Guest-facing invite flow

Route:

```txt
/invite/[token]
```

Flow:

1. Resolve invitation by token.
2. If token is invalid, show a friendly invalid-invitation page.
3. If valid, render personalized wedding page shell.
4. Load guest-facing copy based on `invitations.language`.
5. Show static wedding information:
   - hero
   - date
   - countdown
   - location
   - accommodation information
   - short couple story placeholder
6. Show RSVP section with all invitation members.
7. For each member:
   - attending yes/no
   - meal preference if attending
   - dietary restrictions if attending
8. Show group logistics:
   - arrival date
   - departure date
   - stay location
   - coming from
   - transport help
   - message to the couple
9. Show optional interaction sections:
   - song requests
   - toast/speech request
   - advice/wish/memory
   - one photo upload
10. Before deadline, allow edits.
11. After deadline, show submitted answers read-only and explain that changes require contacting the couple.

Guest-facing localized content should include at least:

- page headings
- navigation/section labels
- RSVP form labels
- validation messages
- success/error messages
- deadline/read-only messages
- upload instructions
- optional interaction prompts

Wedding factual content, such as venue names and addresses, can remain shared, but surrounding explanatory copy should be localized.

## Admin portal plan

Admin routes:

```txt
/admin
/admin/guests
/admin/guests/new
/admin/guests/[id]
```

Although the domain model is `invitations`, the UI can still use guest-friendly labels like `Guests`.

### `/admin`

Dashboard cards:

- Total invitations.
- Total invited people.
- RSVP pending.
- Attending people.
- Declined people.
- Uploaded photos.
- Song requests.
- Pending toast requests.

### `/admin/guests`

Invitation list table:

- display name
- language
- contact email
- contact phone
- members count
- derived RSVP status
- attending count
- invite link
- last updated

Actions:

- copy invite link
- view details
- edit

### `/admin/guests/new`

Create invitation form:

- display name
- language
- contact email
- contact phone
- max party size
- allow member edits
- notes
- initial members

On submit:

- generate token
- create invitation
- create initial members
- show generated invite URL

The language field is required.

### `/admin/guests/[id]`

Detail page:

- invitation metadata
- invite token/link
- member list and per-person RSVP answers
- group logistics
- uploaded photo preview/link
- song requests
- toast requests with admin status controls
- advice/wish/memory messages
- admin notes

Admin actions:

- edit invitation
- add/edit/remove members if needed
- regenerate invite token
- manually adjust RSVP/member data
- accept/decline/schedule toast request

## Authentication plan

Use Google OAuth with an email allowlist.

Implementation targets:

```txt
auth.ts
app/api/auth/[...nextauth]/route.ts
middleware.ts
```

Rules:

- Only emails listed in `ADMIN_EMAILS` may access `/admin` and `/admin/*`.
- Non-admin Google users are rejected or shown a forbidden page.
- Guest invite pages do not require login.
- Admin emails remain in `.env` for the bootstrap.

Before implementation, verify the exact current Next.js/Auth.js setup for the installed framework version.

## MinIO upload plan

Use AWS SDK S3-compatible client.

Upload flow:

1. Guest selects one image.
2. Client asks the app for a presigned upload URL.
3. App validates invitation token and deadline.
4. App creates an object key:

```txt
invitations/{invitationId}/{uuid}-{safeFilename}
```

5. Browser uploads directly to MinIO using presigned PUT.
6. Client calls complete endpoint.
7. App upserts `photo_uploads` metadata for the invitation.

Validation:

- Allow only image MIME types:
  - `image/jpeg`
  - `image/png`
  - `image/webp`
- Enforce a max size.
- Enforce one current photo per invitation.

Admin viewing:

- Generate short-lived signed GET URLs for previews/downloads.

## Docker Compose plan

Services:

```txt
app
postgres
minio
minio-init
```

Postgres:

- expose `5432`
- database: `wedding`
- user: `wedding`
- password: `wedding`

MinIO:

- API: `9000`
- console: `9001`
- bucket: `wedding-uploads`

`minio-init`:

- wait for MinIO
- create bucket if it does not exist

## Implementation sequence

### Step 1: Review framework-specific docs

Because this project uses Next.js 16, review the locally installed Next documentation before coding framework-specific pieces.

Focus areas:

- App Router route handlers.
- Server actions/forms.
- Middleware behavior.
- Authentication integration compatibility.

### Step 2: Add dependencies

Install likely packages:

```bash
npm install kysely pg zod next-auth @aws-sdk/client-s3 @aws-sdk/s3-request-presigner nanoid
npm install -D @types/pg kysely-codegen
```

Adjust if current package versions require different auth package names or setup.

### Step 3: Add environment handling

- Create `.env.example`.
- Add typed config helper in `lib/config.ts`.
- Validate required env vars at startup/server usage.

### Step 4: Add Docker Compose

- Add `docker-compose.yml`.
- Define Postgres service.
- Define MinIO service.
- Define MinIO bucket initialization.
- Optionally define app service.

### Step 5: Add Kysely database client

- Create `lib/db/client.ts`.
- Create initial manual DB types in `lib/db/types.ts`.
- Add SQL migration runner in `scripts/migrate-sql.mjs`.
- Add package script:

```json
"db:migrate": "node scripts/migrate-sql.mjs"
```

### Step 6: Create initial SQL migration

Create `migrations/0001_initial_schema.sql` for:

- `invitations`
- `invitation_members`
- `invitation_responses`
- `photo_uploads`
- `song_requests`
- `toast_requests`
- `guest_messages`
- optional `admin_audit_events`

### Step 7: Add query modules

Create query helpers for:

- invitations
- invitation members
- invitation responses
- uploads
- song requests
- toast requests
- guest messages

Keep SQL explicit and typed through Kysely.

### Step 8: Add validation schemas

Use Zod for:

- creating/updating invitations
- creating/updating members
- submitting RSVP/member attendance
- submitting logistics
- song requests
- toast requests
- guest messages
- upload presign/complete requests

Invitation validation must require a supported language code.

### Step 9: Implement Google admin auth

- Configure Google provider.
- Restrict sign-in to `ADMIN_EMAILS`.
- Protect `/admin` routes.
- Add sign-in/sign-out UI as needed.

### Step 10: Build admin MVP

Implement:

- `/admin` dashboard.
- `/admin/guests` invitation list.
- `/admin/guests/new` create form.
- `/admin/guests/[id]` detail page.

Minimum admin operations:

- create invitation
- add members
- copy invite link
- view submitted RSVP data
- view optional guest interactions

### Step 11: Build guest invite MVP

Implement `/invite/[token]` with:

- invalid token handling
- personalized greeting
- language-aware guest-facing copy based on `invitations.language`
- wedding info shell
- countdown
- member attendance form
- per-member meal/dietary fields
- group logistics form
- submission/edit behavior until deadline

### Step 12: Add optional guest interactions

Add form sections for:

- up to 3 song requests
- optional toast/speech request
- advice/wish/memory message

Admin should be able to view all of them.

### Step 13: Add MinIO photo upload

Implement:

- S3 client.
- presigned PUT endpoint.
- upload complete endpoint.
- one-photo-per-invitation metadata upsert.
- admin signed preview/download URL.

### Step 14: Add basic design shell

Replace default starter UI with a simple wedding-appropriate layout:

- elegant typography
- hero section
- countdown
- location/accommodation placeholders
- story placeholder
- clear guest forms
- responsive mobile-first layout

Final visual design can remain future work.

### Step 14.5: Add localization foundation

Add a simple localization layer for guest-facing invitation pages.

Recommended bootstrap approach:

- Keep supported language codes in config.
- Store the selected language on each invitation.
- Resolve guest-facing copy from `invitations.language` on `/invite/[token]`.
- Create translation dictionaries for guest-facing copy.
- Fallback to a default language only if necessary, but admin should always select a supported language.

Suggested structure:

```txt
lib/
  i18n/
    config.ts
    dictionaries/
      en.ts
      es.ts
      de.ts
```

Do not rely only on browser language detection for invited guests. The invitation language is the source of truth.

### Step 15: Verification

Run:

```bash
npm run lint
npm run build
```

Manual happy path:

1. Start Docker Compose.
2. Run migrations.
3. Log in as admin with allowed Google account.
4. Create an invitation with multiple members.
5. Set the invitation language.
6. Copy invite link.
7. Open invite link.
8. Confirm the page renders in the invitation's configured language.
9. Submit attendance with different meal preferences per member.
10. Add travel details.
11. Add song request, toast request, and message.
12. Upload one photo.
13. Return to admin and confirm all data is visible.
14. Test invalid invite token.
15. Test non-admin access to `/admin`.
16. Test deadline read-only behavior.

## Open implementation questions

These can be decided during implementation:

1. Should guests be able to add/edit member names when `allow_member_edits = true`, or only fill unnamed placeholders?
2. What should the exact RSVP deadline be?
3. What max upload size should be allowed?
4. Should admin be able to export guest/RSVP data as CSV in the first version?
5. Which exact languages should be supported in the first version?

## Recommended first milestone

The first useful milestone should be:

- Docker Compose with Postgres and MinIO.
- Initial pure SQL migration executed by `scripts/migrate-sql.mjs`.
- Google admin login restricted by `.env` emails.
- Admin can create invitation with members.
- Admin can select a language per invitation.
- Guest can open `/invite/[token]` and submit per-member RSVP answers.
- Guest invite page renders in the invitation's configured language.
- Admin can see submitted answers.

After that, add photo uploads and the fun interaction sections.