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.

🚀 Key Features

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.

🛠️ Setup & Installation

Option 1: Docker (Recommended)

The easiest way to get the full stack (Backend + Frontend + DB) running behind a production-ready proxy.

Clone the repository:

git clone https://github.com/nvrl/Holy-Flavor-Rater.git
cd Holy-Flavor-Rater

Environment Configuration:

cp .env.example .env
# Edit .env with your SMTP settings and Domain

Start Services:
```
docker compose up -d --build
```
Note: On first startup, the backend runs migrate + collectstatic, then seeds the flavor catalog, legacy data, and banner configurations once (gated by a /app/.seeded marker so subsequent restarts don't repeat the work). Re-run individual seeds later from the admin Jobs tab.

The stack brings up six containers: redis (broker + cache), backend (Gunicorn), worker (Celery worker), beat (Celery beat w/ django_celery_beat.DatabaseScheduler), flower (Celery monitoring UI on :5555), and frontend (Nginx).

Option 2: Local Manual Setup (Development)

Backend

Navigate and Install:

cd backend
python -m venv venv
source venv/bin/activate  # Linux/Mac
pip install -r requirements.txt

Initialize DB:

python manage.py migrate
python manage.py sync_flavors
python manage.py seed_legacy_flavors
python manage.py seed_banners

Run Server:
```
python manage.py runserver
```
By default holy_backend.settings.dev is active, which sets CELERY_TASK_ALWAYS_EAGER=true — tasks run inline with no broker required. To exercise the full async path locally, start a Redis server and run celery -A holy_backend worker -l info + celery -A holy_backend beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler in separate terminals.

Frontend

Navigate and Install:
```
cd frontend
npm install
```
Run Dev Server:
```
npm run dev
```

🏗️ Architecture

The Holy Flavor Rater uses a modern decoupled architecture:

Backend (Django REST Framework)

Models: Custom User model, Flavors (with category constraints), Ratings (with mention parsing), and Dynamic Banners.
Async jobs: Celery workers backed by Redis handle Shopify syncs, duplicate cleanup, legacy seeding, banner seeding, database backups, and transactional email. Scheduling is owned by django_celery_beat (PeriodicTask + IntervalSchedule) and editable from the admin UI Jobs tab.
Caching & rate-limiting: Django cache uses Redis (RedisCache on DB 1). django_ratelimit consumes the same cache.
Security: JWT authentication (SimpleJWT) with refresh-token rotation, CSRF protection, and email-verified account activation.
Monitoring: /health/ endpoint for the backend; Flower UI on :5555 for queue + worker state (basic-auth gated).

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).

💻 Development Workflow

Integrity Protection

This project includes a Pre-Push Git Hook to ensure code quality. It automatically:

Attempts a full Frontend build (tsc + vite build).
Runs Backend system checks and validates missing migrations.

To install the hooks:

bash scripts/install-hooks.sh

Management Commands

Each is also exposed as a Celery task (api.<name>) and triggerable from the admin Jobs tab.

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_legacy_flavors: Loads retired flavors from legacy/*.json.
python manage.py seed_banners: Updates procedurally generated banner configurations from backend/banners/*.json.
python manage.py backup_db (--full for media too): Creates a consistent SQLite snapshot in backend/backups/.

💾 Backups & Restoration

Create a Backup

To create a full snapshot of your database and user-uploaded media:

bash scripts/backup.sh

This will create a .tar.gz file in backend/backups/.

Automating with Cron: Add this to your crontab -e to backup every night at 2:00 AM:

0 2 * * * /path/to/Holy-Flavor-Rater/scripts/backup.sh

Restore from Backup

Extract the archive: tar -xzf backup_filename.tar.gz
Stop the containers: docker-compose down

Replace the current files:

cp extracted_folder/db.sqlite3 backend/db.sqlite3
cp -r extracted_folder/media/* backend/media/

Restart: docker-compose up -d

🌍 Production Configuration

Ensure your .env contains:

DEBUG=false
DJANGO_SETTINGS_MODULE=holy_backend.settings.prod
SECRET_KEY: A long random string.
ALLOWED_HOSTS: Your domain (e.g., holy.narl.io).
FRONTEND_URL: For one-click email verification links.
CELERY_BROKER_URL / CELERY_RESULT_BACKEND: Default redis://redis:6379/0 works inside the compose network.
DJANGO_CACHE_URL: Default redis://redis:6379/1 (DB 1 to avoid colliding with celery).
FLOWER_BASIC_AUTH: user:password for the Flower UI — change from the default before exposing.

Restrict Flower's port 5555 (or reverse-proxy it behind basic-auth + TLS) since it exposes task payloads and worker internals.

📄 License

MIT