mirror of
https://github.com/narrrl/holy-flavor-rater.git
synced 2026-11-03 16:41:27 +01:00
updated readme with setup instructions, architecture, and dev workflow
This commit is contained in:
nvrl committed
1 parent
25f33e14f9
commit
b0d3f4b35b
1 file changed
+88
-54
@@ -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.
|
- **Personalized Taste Profiles:** Interactive, tiered (S-D) leaderboards based on your personal ratings.
|
||||||
- **Flavor Gallery:** A space-efficient, grid-based view of all rated and missing flavors.
|
- **Dynamic Hall of Fame:** Automatic carousel featuring community-favorite flavors and highlighted reviews.
|
||||||
- **Personalized Taste Profiles:** Share your ratings with the community using tiered (S-D) leaderboards.
|
- **Advanced Search & Discovery:** Typo-friendly search with category-aware filtering and relevance sorting.
|
||||||
- **Responsive Design:** Optimized for all devices, from ultra-wide monitors to vertical smartphones.
|
- **Interactive Banners:** 10+ procedurally generated Canvas banners (Fireflies, Hextech, Nebula, etc.) that react to your mouse.
|
||||||
- **Secure Authentication:** SMTP-verified email signup, password resets, and session management.
|
- **Pro Themes:** Over 15 built-in themes including Catppuccin, Nord, and T0P (Twenty One Pilots) inspired aesthetics.
|
||||||
- **Catalog Automation:** Automatic flavor syncing from official Shopify sources with local image caching.
|
- **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/)
|
### Option 1: Docker (Recommended)
|
||||||
- [Docker Compose](https://docs.docker.com/compose/install/)
|
The easiest way to get the full stack (Backend + Frontend + DB) running behind a production-ready proxy.
|
||||||
- [SMTP Server](https://support.google.com/mail/answer/185833?hl=en) (e.g., Gmail App Password) for email verification.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Setup
|
|
||||||
|
|
||||||
1. **Clone the repository:**
|
1. **Clone the repository:**
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/your-repo/holy.git
|
git clone https://github.com/nvrl/Holy-Flavor-Rater.git
|
||||||
cd holy
|
cd Holy-Flavor-Rater
|
||||||
```
|
```
|
||||||
|
2. **Environment Configuration:**
|
||||||
2. **Configure your environment:**
|
|
||||||
Copy the example environment file and fill in your specific details (especially SMTP and your domain name):
|
|
||||||
```bash
|
```bash
|
||||||
cp .env.example .env
|
cp .env.example .env.narl.io
|
||||||
|
# Edit .env.narl.io with your SMTP settings and Domain
|
||||||
```
|
```
|
||||||
|
3. **Start Services:**
|
||||||
3. **Start the containers:**
|
|
||||||
```bash
|
```bash
|
||||||
docker-compose up -d --build
|
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:**
|
### Option 2: Local Manual Setup (Development)
|
||||||
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).
|
|
||||||
|
|
||||||
5. **Access the application:**
|
#### Backend
|
||||||
- **Frontend:** [http://localhost:5173](http://localhost:5173) (or your configured domain)
|
1. **Navigate and Install:**
|
||||||
- **API Docs:** [http://localhost:8000/api/schema/swagger-ui/](http://localhost:8000/api/schema/swagger-ui/)
|
```bash
|
||||||
- **Admin Panel:** [http://localhost:8000/admin/](http://localhost:8000/admin/) (or your configured `ADMIN_URL`)
|
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.
|
### Frontend (React 19 + TypeScript)
|
||||||
- `SECRET_KEY`: Use a long, random string.
|
- **State Management:** React Hooks and local state for high performance.
|
||||||
- `ADMIN_URL`: Change this to something unique (e.g., `super-secret-gate/`) to hide your admin panel from scanners.
|
- **UI Framework:** Material UI (MUI) with heavy customization for "Holy" branding.
|
||||||
- `ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`, `CORS_ALLOWED_ORIGINS`: Set these to your actual production domain (e.g., `https://holy.narl.io`).
|
- **Visualization:** Procedural generative art system using HTML5 Canvas for profile backgrounds.
|
||||||
|
- **Internationalization:** Full i18next integration (English & German).
|
||||||
### 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Project Structure
|
## 💻 Development Workflow
|
||||||
|
|
||||||
- `backend/`: Django REST Framework API.
|
### Integrity Protection
|
||||||
- `frontend/`: React 19 application with Material UI and Catppuccin themes.
|
This project includes a **Pre-Push Git Hook** to ensure code quality. It automatically:
|
||||||
- `media/`: Locally cached product images and user avatars.
|
1. Attempts a full Frontend build (`tsc` + `vite build`).
|
||||||
- `legacy/`: Static JSON data for historical flavors.
|
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
|
MIT
|
||||||
Reference in new issue
Block a user