🍳 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 and the PostgreSQL data access layer for recipes and site settings.
  • config.php: Environment-independent configuration loader which reads runtime secrets from .env.
  • assets/fc-local.js: Browser-side storage for favorites and dietary goals.
  • scripts/seed-data.php: One-time seed data for recipes, imprint, and privacy settings.
  • scripts/schema.sql: Relational table definitions for recipes and site settings.

---

💻 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 only. DATABASE_URL is required; without a working external DB connection the site returns HTTP 503.
• 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. Set DATABASE_URL in .env (required). See Local Postgres (Docker) below.
3. Seed the external database once: php scripts/db-seed.php (imports recipes and legal/site settings into SQL tables).

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 recipe_slug, title FROM recipe_translations WHERE lang = 'en';
SELECT section, lang, setting_key FROM site_settings ORDER BY section, lang, setting_key;
\q                           -- beenden

DB komplett leeren und neu seeden:

docker compose -f docker-compose.dev.yml down -v
docker compose -f docker-compose.dev.yml up -d
php scripts/db-seed.php

Verbindung prüfen: php scripts/db-check.php

Details zum Schema: Abschnitt unten und scripts/schema.sql.

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. Configure the virtual host or Apache server config to use DirectoryIndex index.php; this repo does not rely on .htaccess overrides.
3. Access the site via your custom local virtual host (e.g., http://localhost/flixcooks-website).

---

🗄️ Postgres in diesem Projekt (Kurzüberblick)

Rezepte und Site-Daten liegen in normalisierten SQL-Tabellen. Es gibt keinen JSONB-Blob, keinen Datei-Fallback und kein Laden von data/*.json zur Laufzeit.

Tabelle	Inhalt
recipes	Slug, Zeiten, Hero-URL, Nährwerte, featured, coming_soon
recipe_translations	Titel, Beschreibung, Kategorie, Schwierigkeit (EN/DE)
recipe_tags	Tags pro Sprache
recipe_ingredients	Zutatenzeilen
recipe_utensils	Werkzeugzeilen
recipe_steps	Schritte inkl. Video-URL und Timer
site_settings	Impressum- und Datenschutzfelder pro Sprache

Schema: scripts/schema.sql. PHP baut daraus dieselben Arrays wie früher (i18n.en, nutrition, …), damit Templates unverändert bleiben.

Ablauf:

1. DATABASE_URL in .env → Verbindung über config.php.
2. Beim ersten Request: Tabellen anlegen (ensure_recipe_schema()).
3. php scripts/db-seed.php einmalig ausführen → Rezepte und Site-Daten werden in Postgres geschrieben.
4. load_recipes() und load_site_settings() lesen per SQL; ohne DB → HTTP 503 (maintenance/db-unavailable.php).
5. Admin: save_recipe(), delete_recipe() und save_site_settings() schreiben direkt in die Tabellen.

Einmalig Daten laden: php scripts/db-seed.php (aus scripts/seed-data.php, ohne JSON-Dateien).

Für Staging/Production muss eine externe Postgres-Datenbank vorhanden sein. Setze nur DATABASE_URL in der Hosting-Umgebung und mische nie Production-Daten in die lokale Dev-DB.

Docker / Coolify

Production-Image: Dockerfile im Repo-Root. Ausführliche Schritte: docs/COOLIFY.md.

docker compose build && docker compose up -d   # lokal testen → http://127.0.0.1:8080

---

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