diff --git a/README.md b/README.md index fc088c0..c625d49 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,119 @@ -# Holy Energy Archive & Community Hub +# Holy Flavor Rater -A premium, responsive full-stack platform for "Holy Energy" fans to rate flavors, explore a categorized archive, and share personalized rating profiles. +A high-density, community-driven platform for "Holy Energy" enthusiasts. Browse every flavor ever released—from current bestsellers to retired legacy editions—rate them, and build your own personal tiered leaderboard to share with the world. -## Features +## 🚀 Key Features -- **Dynamic Hall of Fame:** An auto-rotating carousel featuring the top-rated flavors and community reviews. -- **Flavor Gallery:** A space-efficient, grid-based view of all rated and missing flavors. -- **Personalized Taste Profiles:** Share your ratings with the community using tiered (S-D) leaderboards. -- **Responsive Design:** Optimized for all devices, from ultra-wide monitors to vertical smartphones. -- **Secure Authentication:** SMTP-verified email signup, password resets, and session management. -- **Catalog Automation:** Automatic flavor syncing from official Shopify sources with local image caching. +- **Personalized Taste Profiles:** Interactive, tiered (S-D) leaderboards based on your personal ratings. +- **Dynamic Hall of Fame:** Automatic carousel featuring community-favorite flavors and highlighted reviews. +- **Advanced Search & Discovery:** Typo-friendly search with category-aware filtering and relevance sorting. +- **Interactive Banners:** 10+ procedurally generated Canvas banners (Fireflies, Hextech, Nebula, etc.) that react to your mouse. +- **Pro Themes:** Over 15 built-in themes including Catppuccin, Nord, and T0P (Twenty One Pilots) inspired aesthetics. +- **Social Interaction:** Follow other collectors, receive follow notifications, and leave messages in profile guestbooks. +- **Enterprise Verification:** Secure one-click email verification and password recovery. +- **Automated Catalog:** Real-time syncing with Shopify APIs and historical legacy flavor data. --- -## Prerequisites +## 🛠️ Setup & Installation -- [Docker](https://docs.docker.com/get-docker/) -- [Docker Compose](https://docs.docker.com/compose/install/) -- [SMTP Server](https://support.google.com/mail/answer/185833?hl=en) (e.g., Gmail App Password) for email verification. - ---- - -## Quick Setup +### Option 1: Docker (Recommended) +The easiest way to get the full stack (Backend + Frontend + DB) running behind a production-ready proxy. 1. **Clone the repository:** ```bash - git clone https://github.com/your-repo/holy.git - cd holy + git clone https://github.com/nvrl/Holy-Flavor-Rater.git + cd Holy-Flavor-Rater ``` - -2. **Configure your environment:** - Copy the example environment file and fill in your specific details (especially SMTP and your domain name): +2. **Environment Configuration:** ```bash - cp .env.example .env + cp .env.example .env.narl.io + # Edit .env.narl.io with your SMTP settings and Domain ``` - -3. **Start the containers:** +3. **Start Services:** ```bash docker-compose up -d --build ``` + *Note: On first startup, the backend will automatically migrate, sync the flavor catalog, and clean up any duplicates.* -4. **Wait for initial setup:** - The first time you start the backend, it will automatically: - - Run database migrations. - - Collect static files. - - **Sync flavors** from the Holy Energy Shopify API (this might take a minute). +### Option 2: Local Manual Setup (Development) -5. **Access the application:** - - **Frontend:** [http://localhost:5173](http://localhost:5173) (or your configured domain) - - **API Docs:** [http://localhost:8000/api/schema/swagger-ui/](http://localhost:8000/api/schema/swagger-ui/) - - **Admin Panel:** [http://localhost:8000/admin/](http://localhost:8000/admin/) (or your configured `ADMIN_URL`) +#### Backend +1. **Navigate and Install:** + ```bash + cd backend + python -m venv venv + source venv/bin/activate # Linux/Mac + pip install -r requirements.txt + ``` +2. **Initialize DB:** + ```bash + python manage.py migrate + python manage.py sync_flavors + python manage.py seed_legacy_flavors + ``` +3. **Run Server:** + ```bash + python manage.py runserver + ``` + +#### Frontend +1. **Navigate and Install:** + ```bash + cd frontend + npm install + ``` +2. **Run Dev Server:** + ```bash + npm run dev + ``` --- -## Production Hosting +## 🏗️ Architecture -### Security Best Practices +The Holy Flavor Rater uses a modern **decoupled architecture**: -When hosting this application publicly, ensure you update your `.env` with: +### Backend (Django REST Framework) +- **Models:** Custom User model, Flavors (with category constraints), Ratings (with mention parsing), and Dynamic Banners. +- **Automation:** Management commands for periodic Shopify API syncing and database deduplication. +- **Security:** Token-based authentication, CSRF protection, and email-verified account activation. +- **Monitoring:** Integrated `/health/` endpoint for Docker container status. -- `DEBUG=false`: Essential for disabling internal Django stack traces. -- `SECRET_KEY`: Use a long, random string. -- `ADMIN_URL`: Change this to something unique (e.g., `super-secret-gate/`) to hide your admin panel from scanners. -- `ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`, `CORS_ALLOWED_ORIGINS`: Set these to your actual production domain (e.g., `https://holy.narl.io`). - -### Performance - -- The application uses **WhiteNoise** for efficient static file serving. -- **Gunicorn** is configured as the production WSGI server. -- **Compression Middleware** (Gzip/Brotli) is active for API responses. -- **Lazy Loading** is enabled for all flavor and carousel images. +### Frontend (React 19 + TypeScript) +- **State Management:** React Hooks and local state for high performance. +- **UI Framework:** Material UI (MUI) with heavy customization for "Holy" branding. +- **Visualization:** Procedural generative art system using HTML5 Canvas for profile backgrounds. +- **Internationalization:** Full i18next integration (English & German). --- -## Project Structure +## 💻 Development Workflow -- `backend/`: Django REST Framework API. -- `frontend/`: React 19 application with Material UI and Catppuccin themes. -- `media/`: Locally cached product images and user avatars. -- `legacy/`: Static JSON data for historical flavors. +### Integrity Protection +This project includes a **Pre-Push Git Hook** to ensure code quality. It automatically: +1. Attempts a full Frontend build (`tsc` + `vite build`). +2. Runs Backend system checks and validates missing migrations. -## License +**To install the hooks:** +```bash +bash scripts/install-hooks.sh +``` +### Management Commands +- `python manage.py sync_flavors`: Syncs the latest products from the official Holy Energy API. +- `python manage.py cleanup_duplicates`: Merges duplicate entries and maintains rating integrity. +- `python manage.py seed_banners`: Updates procedurally generated banner configurations from JSON. + +--- + +## 🌍 Production Configuration + +Ensure your `.env` contains: +- `DEBUG=false` +- `SECRET_KEY`: A long random string. +- `ALLOWED_HOSTS`: Your domain (e.g., `holy.narl.io`). +- `FRONTEND_URL`: For one-click email verification links. + +## 📄 License MIT