feat: Add comprehensive README.md detailing project features, setup, deployment, and structure.

2026-03-17 23:44:53 -07:00
parent 24ad30dc56
commit 5059f64a00
1 changed files with 138 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,138 @@
+# 🌎 G Travel — Guatemala Tourism Website
+
+A modern, responsive tourism website for Guatemala built with **Flask**, **SQLite**, and **Jinja2**. Features a premium glassmorphism design, an admin dashboard, and integrations with Cloudflare Turnstile, Retell AI, and Mailtrap SMTP.
+
+![Python](https://img.shields.io/badge/Python-3.12-blue)
+![Flask](https://img.shields.io/badge/Flask-3.x-green)
+![SQLite](https://img.shields.io/badge/Database-SQLite-lightgrey)
+
+---
+
+## ✨ Features
+
+### Public Website
+- 🏛️ **Tours, Surf & Volcanoes** — Dynamic sections loaded from the database
+- 🎬 **Hero Video Background** — Autoplay MP4 video with overlay
+- 🌐 **Multi-language** — English / Spanish toggle
+- 📱 **Fully Responsive** — Hamburger menu on mobile
+- 📝 **Contact Form** — With Cloudflare Turnstile bot protection
+- 🤖 **Retell AI Opt-in** — Checkbox to request an AI agent call
+- 🔍 **Tour Detail Pages** — Individual pages with booking forms
+
+### Admin Dashboard (`/admin`)
+- 🔐 **HTTP Basic Auth** — Username: `admin` / Password: `admin`
+- 📑 **Tabbed Interface** — Leads & Forms, Tours & Activities, System Settings
+- ✏️ **Full CRUD for Tours** — Create, Read, Update, Delete with image upload
+- 📊 **Lead Management** — View all submitted inquiries
+- ⚙️ **System Settings** — Configure all integrations from the UI:
+  - Agency name, email, and logo (URL or upload)
+  - Hero video (URL or upload)
+  - Mailtrap SMTP credentials
+  - Cloudflare Turnstile keys
+  - Retell AI API key, phone number, agent ID, and enable/disable toggle
+
+---
+
+## 🚀 Quick Start
+
+### 1. Clone the repository
+```bash
+git clone <your-repo-url>
+cd GTravel
+```
+
+### 2. Create a virtual environment
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+### 3. Install dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### 4. Seed the database (first run)
+```bash
+python seed.py
+```
+
+### 5. Run the application
+```bash
+python main.py
+```
+
+The app will be available at **http://localhost:8000**
+
+---
+
+## 🌐 Production Deployment (CloudPanel / Gunicorn)
+
+This app is ready for deployment on **CloudPanel.io** or any WSGI-compatible server.
+
+### Using Gunicorn
+```bash
+gunicorn wsgi:application --bind 0.0.0.0:8000
+```
+
+### CloudPanel Setup
+1. Create a new Python application in CloudPanel
+2. Point the entry file to `wsgi.py`
+3. Install dependencies: `pip install -r requirements.txt`
+4. Run `python seed.py` to initialize the database
+5. The `wsgi.py` file exposes the standard `application` variable
+
+---
+
+## 📁 Project Structure
+
+```
+GTravel/
+├── main.py                 # Flask application (all routes)
+├── database.py             # SQLAlchemy models & DB setup
+├── seed.py                 # Database seeder with sample data
+├── wsgi.py                 # WSGI entry point for production
+├── requirements.txt        # Python dependencies
+├── gtravel.db              # SQLite database (auto-created)
+├── static/
+│   ├── css/
+│   │   └── style.css       # All styles (glassmorphism theme)
+│   ├── images/             # Tour images & uploaded logos
+│   └── videos/             # Uploaded hero videos
+└── templates/
+    ├── base.html            # Base layout (navbar, hamburger menu)
+    ├── index.html           # Homepage (hero, tours, surf, volcanoes, contact)
+    ├── detail.html          # Tour detail page with booking form
+    └── dashboard.html       # Admin dashboard (tabbed interface)
+```
+
+---
+
+## 🔧 Configuration
+
+All configuration is managed through the **Admin Dashboard** → **System Settings** tab.
+
+| Setting | Description |
+|---|---|
+| **Agency Name** | Displayed in the browser title |
+| **Agency Email** | Used as sender/receiver for email notifications |
+| **Logo** | Upload an image or provide a URL |
+| **Hero Video** | Upload an MP4 or provide a URL for the homepage background |
+| **Mailtrap SMTP** | Host, Port, Username, Password for email delivery |
+| **Cloudflare Turnstile** | Site Key & Secret Key for bot protection |
+| **Retell AI** | API Key, Phone Number, Agent ID, and Enable toggle |
+
+---
+
+## 🛡️ Security Notes
+
+- Change the default admin credentials in `main.py` before deploying to production
+- Set a strong `SECRET_KEY` environment variable: `export SECRET_KEY="your-secret-key"`
+- Configure Cloudflare Turnstile to protect public forms from bots
+- Use HTTPS in production (CloudPanel handles this automatically)
+
+---
+
+## 📄 License
+
+This project is proprietary. All rights reserved.