💍 Wedding Site

A personal wedding website with guest authentication, RSVP forms, event information, and an administration panel.

⸻

📖 About the Project

Wedding Site is a web application designed for a wedding event.

The website allows guests to:

* receive a personalized invitation;
* authenticate using a unique access code;
* view the wedding schedule;
* get information about transportation and travel;
* browse photos;
* fill out a guest questionnaire;
* specify food and drink preferences;
* leave a personal message or request.

The organizers have access to administrative features for managing guests.

The project is a full-stack application with a Python backend and a native HTML/CSS/JavaScript frontend.

⸻

✨ Features

👰 For Guests

* 🔐 Authentication using a unique 6-digit code
* 🎫 Personalized access to the invitation
* 📅 Wedding day schedule
* 🚗 Transportation and travel information
* 📸 Photo gallery
* 📝 Guest questionnaire
* 🍽️ Food preferences
* 🥂 Drink preferences
* 💬 Ability to leave a message or request
* 🚪 Secure logout

👨‍💼 For Administrators

* 👥 View the guest list
* ➕ Create new guests
* ✏️ Edit guest information
* 🔑 Manage guest access codes
* 📊 View guest activation status
* 🕐 Track the last login time
* 🛡️ Role-based administrative access

⸻

🏗️ Architecture

                         ┌─────────────────────┐
                         │        Guest        │
                         │   Browser / Mobile  │
                         └──────────┬──────────┘
                                    │
                              HTTPS / HTTP
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │       Caddy         │
                         │ Reverse Proxy / TLS │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │       FastAPI       │
                         │       Backend       │
                         └──────────┬──────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
          │     JWT     │    │  Pydantic   │    │  SQLAlchemy │
          │     Auth    │    │ Validation  │    │     ORM     │
          └─────────────┘    └─────────────┘    └──────┬──────┘
                                                        │
                                                        ▼
                                                 ┌─────────────┐
                                                 │   SQLite    │
                                                 │   guests.db │
                                                 └─────────────┘

⸻

🧰 Technologies

Backend

Technology	Purpose
Python 3.13	Core programming language
FastAPI	REST API
Uvicorn	ASGI server
Pydantic	Data validation
SQLAlchemy 2	ORM
SQLite	Database
aiosqlite	Async SQLite driver
Alembic	Database migrations
PyJWT	JWT authentication

Frontend

Technology	Purpose
HTML5	Markup
CSS3	Styling
JavaScript	Client-side logic
Swiper.js	Sliders and gallery

Infrastructure

Technology	Purpose
Docker	Containerization
Docker Compose	Container orchestration
Caddy	Reverse proxy and HTTPS
Ansible	Deployment automation
Gitea Actions	CI/CD

⸻

📁 Project Structure

```
.
├── .gitea/
│   └── workflows/
│       └── ci.yml
│
├── ansible/
│   ├── deploy.yml
│   ├── inventory.ini
│   └── secrets.yml
│
├── docker/
│   ├── caddy/
│   ├── gitea_runner_image/
│   ├── gitea_runners/
│   ├── docker-compose.yaml
│   ├── dockerfile.project
│   └── start.sh
│
├── server/
│   ├── backend/
│   │   ├── auth/
│   │   │   └── JWT.py
│   │   │
│   │   ├── database/
│   │   │   ├── DB/
│   │   │   ├── alembic/
│   │   │   └── db.py
│   │   │
│   │   ├── endpoints/
│   │   │   └── endpoints.py
│   │   │
│   │   └── schema/
│   │       └── pydantic.py
│   │
│   └── frontend/
│       ├── auth/
│       │   ├── fonts/
│       │   ├── image/
│       │   ├── login.css
│       │   ├── login.html
│       │   └── login.js
│       │
│       └── main/
│           ├── fonts/
│           ├── images/
│           ├── api.js
│           ├── index.html
│           ├── main.js
│           ├── reset.css
│           └── style.css
│
├── .gitignore
├── env_example
├── makefile
├── requirements.txt
└── run.py
```

⸻

🔐 Authentication

Authentication is based on a personal access code assigned to each guest.

```
Guest
  │
  │ 6-digit code
  ▼
POST /api/auth
  │
  ├── Validate user
  ├── Verify access code
  ├── Update last_login
  └── Generate JWT
          │
          ▼
     HTTP-only Cookie
          │
          ▼
      Authenticated
```

The JWT is stored in a cookie and used for subsequent API requests.

The authentication cookie uses the following security attributes:

HttpOnly
Secure
SameSite=Strict

The JWT secret key and token configuration are provided through environment variables.

⸻

🔌 API

Main API endpoints:

Method	Endpoint	Description	Auth
POST	/api/auth	Guest authentication	❌
GET	/api/verify	Verify authentication	✅
POST	/api/logout	Logout	✅
POST	/api/update	Update guest information	✅
POST	/api/create	Create a guest	👑
GET	/api/list	Get the guest list	👑

Where:

* ✅ — authenticated user;
* 👑 — administrator only.

Swagger

Interactive API documentation is available at:

/api/docs

ReDoc

/api/redoc

OpenAPI

/api/openapi.json

⸻

🗄️ Database

The project uses SQLite as its database.

Main entity:

users

The table contains:

* user ID;
* access code;
* first name;
* middle name;
* last name;
* personal message or request;
* food preferences;
* drink preferences;
* activation status;
* creation timestamp;
* update timestamp;
* last login timestamp;
* administrator privileges.

The database layer uses an asynchronous stack:
```
FastAPI
   │
   ▼
SQLAlchemy 2
   │
   ▼
aiosqlite
   │
   ▼
SQLite
```
Database schema changes are managed using Alembic.

⸻

🚀 Local Development

Requirements

Before running the project, install:

* Python 3.13+
* pip
* SQLite

For Docker-based deployment:

* Docker
* Docker Compose

⸻

1. Clone the Repository

git clone https://git.homyk.space/MH.Dmitrii/wedding-site.git
cd wedding-site

⸻

2. Create a Virtual Environment

Linux / macOS

python3.13 -m venv .venv
source .venv/bin/activate

Windows

py -3.13 -m venv .venv
.venv\Scripts\activate

⸻

3. Install Dependencies

pip install -r requirements.txt

⸻

4. Environment Variables

Create a .env file in the project root.
```
Example:

DIR=/path/to/project
PORT=8000
SECRET_KEY=change-me
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_SECONDS=3600
```
You can use env_example as a reference when configuring the environment.

⚠️ Never commit a real SECRET_KEY to Git.

⸻

5. Run the Application

python run.py

Or using Make:

make run

Debug mode:

make run_debug

After starting, the application will be available at:

http://localhost:8000

Swagger:

http://localhost:8000/api/docs

⸻

🐳 Docker

Docker Compose is used for production-like deployments.

Start the application:

docker compose -f docker/docker-compose.yaml up -d

Check running containers:

docker compose -f docker/docker-compose.yaml ps

View logs:

docker compose -f docker/docker-compose.yaml logs -f

Stop the application:

docker compose -f docker/docker-compose.yaml down

The SQLite database is persisted using a Docker volume, so recreating the container should not remove the database data.

⸻

🧬 Database Migrations

The project uses Alembic for database migrations.

Check the current migration:

make migrate_current

Apply all migrations:

make migrate_head

Rollback the latest migration:

make migrate_down

View migration history:

make migrate_history

View migration heads:

make migrate_heads

Create a new migration:

make migrate

⸻

⚙️ Makefile

The project provides a Makefile with shortcuts for common development and database operations.

Main commands:

make run
make run_debug
make migrate_current
make migrate_head
make migrate_down
make migrate_history
make migrate_heads
make migrate

To see all available commands:

make help

⸻

🔄 CI/CD

The project uses Gitea Actions for automation.
```
The general workflow:

              git push
                  │
                  ▼
          ┌───────────────┐
          │ Gitea Actions │
          └───────┬───────┘
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
   Build Docker        Deployment
        │                   │
        ▼                   ▼
   Docker Image          Ansible
                            │
                            ▼
                     Docker Compose
                            │
                            ▼
                       Production
```
The workflow builds the Docker image and performs deployment to the target environment.

⸻

🌐 Production
```
The production infrastructure consists of:

Internet
    │
    ▼
  Caddy
    │
    │ HTTPS
    ▼
 FastAPI
    │
    ▼
 SQLite
```
Caddy acts as a reverse proxy and handles external HTTP/HTTPS traffic.

Ansible is used to automate deployment and server configuration.

⸻

📱 Frontend

The frontend does not use React, Vue, Angular, or other SPA frameworks.

The main stack is:

HTML
CSS
JavaScript

This keeps the client-side application lightweight and easy to deploy.

Main pages:

/auth/login.html
/main/index.html

JavaScript is responsible for:

* authentication;
* API communication;
* mobile navigation;
* sliders;
* interactive elements;
* countdown timer;
* guest questionnaire submission.

⸻

🧪 Development
```
Recommended development workflow:

Feature branch
      │
      ▼
Development
      │
      ▼
Commit
      │
      ▼
Push
      │
      ▼
Gitea Actions
      │
      ▼
Build
      │
      ▼
Deploy
```
Before pushing changes, it is recommended to run:

python -m compileall .

and verify that the application starts correctly in the local environment.

⸻

🔒 Security

For production deployment, make sure to:

* use a strong, randomly generated SECRET_KEY;
* use HTTPS;
* never commit .env files to Git;
* never store production secrets in plain text;
* restrict access to the SQLite database;
* regularly back up the database;
* disable debug mode in production.

⚠️ Deployment configuration and secrets should be reviewed carefully before making the repository public.

⸻

🗺️ Roadmap

Possible future improvements:

* Add comprehensive automated tests
* Add API test coverage
* Add SQLite backup and restore
* Add a dedicated admin frontend
* Add guest response statistics
* Add guest list export to Excel/CSV
* Add rate limiting to /api/auth
* Add CSRF protection for cookie-based authentication
* Add centralized logging
* Add a dedicated healthcheck endpoint
* Add application monitoring

⸻

📊 Project
```
Main languages used in the project:

HTML        ████████████████████  40.5%
CSS         ███████████████       29.5%
Python      ██████████            20.9%
JavaScript  ████                   7.6%
Makefile    ▏                      0.7%

The statistics are based on the current state of the repository.
```
⸻

📄 License

No explicit license is currently specified in the repository.

If the project is intended to be distributed as open source, it is recommended to add a:

LICENSE

file and specify the chosen license in this section.

⸻

👨‍💻 Author

MH.Dmitrii

Repository:

https://git.homyk.space/MH.Dmitrii/wedding-site