From caf16a444e2eadbe44f7360f88cc836ade3e9b78 Mon Sep 17 00:00:00 2001 From: "MH.Dmitrii" Date: Sat, 29 Aug 2026 13:36:08 +0300 Subject: [PATCH] readme add --- readme.md | 633 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 632 insertions(+), 1 deletion(-) diff --git a/readme.md b/readme.md index d8425dd..bbed895 100644 --- a/readme.md +++ b/readme.md @@ -1 +1,632 @@ -test 2d \ No newline at end of file +πŸ’ 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