flixcooks-website/README.md

🍳 FlixCooks – Premium Culinary Experience

Welcome to FlixCooks, a high-end, immersive recipe web application built on vanilla technologies. Drawing aesthetic inspiration from state-of-the-art luxury design concepts (such as Floema, Capitolium, and fromanother), FlixCooks marries gorgeous visual design with swift, lightweight performance.

---

🏛️ Codebase Architecture

The project is architected to remain extremely lightweight and fast, intentionally bypassing heavy frameworks in favor of a clean, optimized vanilla stack.

Core Structure

• Root Pages:
  • index.php: The atmospheric landing page showcasing featured recipe selections, introducing the brand, and housing the Sleek Swipe Discovery Carousel.
  • recipe.php: The immersive recipe detail page, featuring floating macro-nutrition widgets, interactive ingredients lists, and the fullscreen Step-by-Step Cooking Mode.
  • admin.php: A custom, lightweight CMS/admin dashboard allowing full CRUD capabilities over the recipe database, dynamic ingredient line parsing, cooking timers, and video URL associations.
  • login.php: Local profile page for dietary goals and saved favorites (browser storage).
• Support & Layouts:
  • partials/: Contains modular templates (head.php, header.php, footer.php) to maintain a clean DRY structure.
  • helpers.php: Core PHP utilities containing data formatting helpers and the data access layer for the flat-file database.
  • config.php: Environment-independent configuration loader which reads runtime secrets from .env.
  • assets/fc-local.js: Browser-side storage for favorites and dietary goals.
  • data/: Houses recipes.json, our flat-file recipe database.

---

💻 Tech-Stack

FlixCooks uses a modern, carefully curated vanilla tech-stack focused on lightning-fast speed, dynamic transitions, and pristine responsive aesthetics.

🎨 Frontend & Design Systems

• Core Structure: Semantic HTML5 & Vanilla PHP layout templates.
• Styling: Vanilla CSS leveraging custom properties (CSS variables), clamp() functions for seamless fluid typography and spacing, asymmetric layouts (FloemaLayoutGrid 24-column grid), and modern glassmorphism overlay styles.
• Smooth Scrolling: Lenis Smooth Scroll for premium, inertia-driven page physics.
• Animations: GSAP (GreenSock Animation Platform) and ScrollTrigger for advanced storytelling, pinned sequences, and micro-interactions.
• Fonts: Elegantly paired fonts (Playfair Display for headings and modern, geometric Manrope for high-readability body copy).

⚙️ Backend & Data

• Engine: Vanilla PHP.
• Database: PostgreSQL (production/staging) with automatic seed from data/recipes.json. Without DATABASE_URL, the app falls back to the JSON file.
• Environment: Custom .env variable parser integrated into PHP bootstrap.

---

🚀 Local Development Setup

Follow these simple steps to spin up the local development environment.

Prerequisites

Make sure you have the following installed on your local machine:

• PHP (8.x recommended) with the pgsql extension (php-pgsql on Linux/WSL)
• Docker (for local Postgres via docker-compose.dev.yml)
• A modern web browser

1. Set Up Environment Variables

1. Duplicate the template environment file:

   cp .env.example .env
   

2. Open .env and optionally set local Postgres (see Local Postgres (Docker) below).

2. Local Postgres (Docker)

Für DB-Integration auf einem Dev-Branch – getrennt von Production.

# Container starten
docker compose -f docker-compose.dev.yml up -d

# Warten bis healthy (einmalig prüfen)
docker compose -f docker-compose.dev.yml ps

In .env (Werte passen zu docker-compose.dev.yml):

DATABASE_URL="postgresql://flixcooks:flixcooks_dev@127.0.0.1:5432/flixcooks_dev"

PHP-Extension (WSL/Ubuntu, einmalig):

sudo apt install php-pgsql
# oder passend zur Version: sudo apt install php8.5-pgsql

Datenbank-Shell (zum Lernen / Inspizieren):

docker exec -it flixcooks-postgres-dev psql -U flixcooks -d flixcooks_dev

Nützliche SQL-Befehle in psql:

\dt                          -- alle Tabellen
\d recipes                   -- Spalten der Tabelle recipes
SELECT slug, created_at FROM recipes;
SELECT slug, data->>'title' AS title FROM recipes, jsonb_to_record(data) AS x(title text);  -- optional
\q                           -- beenden

DB komplett leeren und neu seeden (lädt wieder aus data/recipes.json beim nächsten Seitenaufruf):

docker compose -f docker-compose.dev.yml down -v
docker compose -f docker-compose.dev.yml up -d

Details zum Schema und Ablauf: Abschnitt unten in dieser README und helpers.php → init_db().

3. Start the Development Server

Option A: PHP Built-in Web Server (Recommended & Easiest)

You do not need to install complex local servers like Apache or Nginx. Simply run the following command in the root folder of the project:

php -S localhost:8000

Then, open your browser and navigate to:

http://localhost:8000

Option B: Local Apache (XAMPP / MAMP / WAMP)

If you prefer running a full local stack:

1. Move or link the project directory inside your local server's document root (e.g., htdocs or www).
2. Ensure URL rewriting is enabled (the included .htaccess file handles caching and custom redirections).
3. Access the site via your custom local virtual host (e.g., http://localhost/flixcooks-website).

---

🗄️ Postgres in diesem Projekt (Kurzüberblick)

FlixCooks nutzt eine Tabelle – kein klassisches „eine Spalte pro Rezeptfeld“-Schema:

Spalte	Typ	Bedeutung
slug	VARCHAR	Eindeutige ID des Rezepts (URL: /recipe.php?slug=...)
data	JSONB	Gesamtes Rezept als JSON (Titel, Zutaten, Schritte, i18n, …)
created_at	TIMESTAMP	Erstellzeit
updated_at	TIMESTAMP	Letzte Änderung (wird beim Update gesetzt)

Warum JSONB? Das Rezept ist in PHP/JSON ohnehin ein Objekt. Statt 20+ SQL-Spalten zu pflegen, speichert ihr ein Dokument pro Zeile. PostgreSQL kann in JSONB trotzdem indexieren und abfragen (data->>'title'), wenn ihr später filtern wollt.

Ablauf beim ersten Aufruf mit leerer DB:

1. config.php liest DATABASE_URL → PDO-Verbindung.
2. init_db() in helpers.php erstellt recipes, falls nicht vorhanden.
3. Ist die Tabelle leer → Import aus data/recipes.json.
4. load_recipes() liest alle Zeilen, dekodiert data zurück zu PHP-Arrays.

Admin speichern: save_recipes() schreibt nach Postgres und aktualisiert data/recipes.json als Backup.

Für Staging/Production setzt du DATABASE_URL in der jeweiligen Hosting-Umgebung – nie Production-Daten in der lokalen Dev-DB mischen.

---

📈 Development Tracking & Progress

All current development tasks, features, and roadmaps are actively tracked and updated in the project’s .agents/TODO.md file. Architectural learnings, conventions, and configuration updates are maintained in the central knowledge base: .agents/brain.md.