NOTE CURRENTLY UNDER MAINTAINANCE AND REFACTORING

Wedding Website & Custom Registry

This project is a comprehensive, open-source wedding website that features a custom-built, fully functional gift registry system. It serves as a customizable and self-hostable alternative to traditional wedding registry platforms, complete with modern features like 3D animations and a full administrative interface.

Live Demo | Architecture Overview | Runtime Contract | Deployment Recipes | API Specification | Asset Storage System | Downstream Upgrade Guide | Versioning Policy

Table of Contents

1. Purpose
2. Key Features
3. Tech Stack
4. Setup & Installation
   • Prerequisites
   • Installation Steps
   • Environment Variables
   • Database Setup
5. Usage
   • Development Server
   • Admin Access
   • Registry Management
6. Project Structure
7. Contributing
8. License

Purpose

The primary goal of this project is to provide a personal, customizable, and cost-effective solution for couples who want more control over their wedding website and registry. Unlike commercial platforms that often charge fees or have limited customization, this open-source solution allows you to:

• Host your own registry without third-party fees.
• Customize the design and content to match your wedding theme.
• Integrate unique features like 3D interactive elements.
• Keep your guest data private.

Key Features

• Interactive User Experience:
  • Engaging 3D animations using React Three Fiber (e.g., the interactive Heart page).
  • A fully responsive design for seamless viewing on all devices.
  • Smooth page transitions and scroll-based animations with Framer Motion.
  • "Add to Calendar" functionality for guests.
• Custom Gift Registry:
  • Add & Edit Items: Manually input gift details or use the built-in web scraper to pre-fill item information from online stores (supports Open Graph metadata and basic Amazon scraping).
  • Group Gifting: Allow guests to contribute partial amounts towards higher-priced items. Progress bars visualize the contribution status.
  • Filtering & Sorting: Guests can easily browse the registry by filtering items by category, price range, and status.
• Admin Dashboard: A password-protected dashboard for managing registry items, including adding, editing, and deleting products.
• Standard Wedding Info Pages: Easily customizable pages for event details, travel information, weather forecasts, and photo galleries.

Tech Stack

This project is built with a modern, full-stack TypeScript architecture.

• Framework: Next.js (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Database ORM: Prisma
• Database: PostgreSQL (portable contract; compatible with local PostgreSQL, Neon, Supabase, Railway, AWS RDS, GCP Cloud SQL, etc.)
• 3D & Animation: React Three Fiber, Drei, & Framer Motion
• Physics: Rapier (via @react-three/rapier) for 3D interactions.
• State Management: React Query (TanStack Query) for server state.
• Testing: Jest, React Testing Library, and Playwright for end-to-end testing.
• Deployment: Multi-cloud options including Docker / VPS, Google Cloud Run, Vercel, and Railway / Render (See Deployment Guide).

Setup & Installation

For production hosting guidelines and minimum runtime requirements across container and cloud environments, see the Application Runtime Contract and Deployment Documentation.

Prerequisites

• Node.js: LTS version recommended (v22+).
• Git: For version control.
• PostgreSQL Database: Compatible with local PostgreSQL or cloud providers (e.g. Neon, Supabase, Railway, RDS, Cloud SQL). See DEPLOYMENT.md for the PostgreSQL Database Contract and operational guidance.

Installation Steps

1. Clone the repository:

   git clone https://github.com/fderuiter/wedding_website.git
   cd wedding_website

2. Install dependencies:

   npm install

Environment Variables

Create a .env.development.local file in the root directory by copying the .env.example file or creating a new one. You need to define the following variables:

# Required for Admin Login (Must be a scrypt hash, NOT plaintext)
# Generate a hash by running: node scripts/generate-password-hash.mjs "your_password"
# The format must be: scrypt:[saltBase64]:[keyBase64]
ADMIN_PASSWORD="scrypt:c2FsdA==:aGFzaA=="

# Required for Prisma (PostgreSQL connection)
# Obtain this from your database provider
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

Database Setup

1. Run Migrations: Apply the database schema to your PostgreSQL database.

   npm run migrate:dev

   This command creates the necessary tables (RegistryItem, Contributor, etc.) defined in prisma/schema.prisma.

2. Seed Data (Optional): If you have a seeding script or want to migrate data from a JSON file, you can run the migration script (this uses the configured Prisma provider to seed the database).

   npm run db:seed

Usage

Development Server

Start the development server:

npm run dev

The application will be available at http://localhost:3000.

Linting & Testing

Run the linter to ensure code quality:

npm run lint

Running Tests with Isolated Database Setup

This project features an automated, zero-configuration local testing setup. Running the test command automatically:

1. Starts the local PostgreSQL database container (using Docker Compose) if it is not already running.
2. Waits for the database to be fully ready and accepting connections.
3. Automatically provisions and synchronizes the Prisma schema to an isolated, dedicated test database (wedding_test). This ensures that executing the test suite will never delete, modify, or insert records into your default development database.

To execute the unit and integration test suite:

npm test

To run tests in watch mode:

npm run test:watch

First-Run Setup & Bootstrap

1. Initial Setup Wizard: On a fresh installation, visiting the site presents the First-Run Setup Wizard.
2. Authentication: Enter the admin password corresponding to the ADMIN_PASSWORD scrypt hash configured in your environment. No default password exists.
3. Core Site Configuration: Enter your partner details, wedding date, canonical site URL, venue details, and timezone.
4. Replay Protection: Once setup completes, the setup endpoint (/api/admin/setup) is protected against unauthorized replay attacks (403 Forbidden). Future configuration changes require an authenticated admin session.

Admin Access

1. Navigate to /admin/login.
2. Enter the password you configured in ADMIN_PASSWORD.
3. Upon successful login, you will be redirected to /admin/dashboard.

Registry Management

• Adding Items: From the dashboard, click "Add New Item". You can paste a product URL to auto-fill details or enter them manually.
• Group Gifts: Toggle the "Allow Group Gifting?" checkbox to let multiple guests contribute to a single item.
• Managing Contributions: The dashboard shows the funded status of each item. You can edit items to update quantities or fix typos.

Upgrading & Upstream Maintenance

If you cloned or forked this template to host your own wedding website, you can pull upstream fixes and new features using Git:

• See docs/upgrading.md for step-by-step instructions on adding upstream remotes, resolving conflicts, running database migrations (npm run migrate:deploy), and post-upgrade testing.
• See docs/versioning.md for our Semantic Versioning policy, release note categorization, and breaking change protocols.

Project Structure

• src/app: Next.js App Router pages and Route Handlers.
• src/components: Shared React components (Layout, UI elements, 3D scenes).
• src/features: Feature-specific logic (e.g., src/features/registry contains all registry-related components, hooks, and services).
• src/data: Static data files (e.g., wedding party members, things to do).
• src/lib: Core library configurations (Prisma client).
• src/utils: Utility functions (validation, formatting, auth).
• src/styles: Global styles and theme configuration.
• prisma: Database schema definition.
• public: Static assets (images, fonts).
• e2e: End-to-end tests (Playwright).
• scripts: Utility scripts for database migration and maintenance.

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for guidelines on how to participate in this project.

License

This project is open-source and available under the GNU Affero General Public License.