🍳 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.
  • 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/recipes.json: Optional seed file only (php scripts/db-seed.php), not used at runtime.
  • scripts/schema.sql: Relational table definitions for recipes.

---

💻 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 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 recipes once: php scripts/db-seed.php (imports data/recipes.json 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 slug, data->>'title' AS title FROM recipes, jsonb_to_record(data) AS x(title text);  -- optional
\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 to serve index.php as the directory index.
3. Access the site via your custom local virtual host (e.g., http://localhost/flixcooks-website).

---

🗄️ Postgres in diesem Projekt (Kurzüberblick)

Rezepte liegen in normalisierten SQL-Tabellen (kein JSONB-Blob, kein Laufzeit-Fallback auf Dateien):

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

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()). Alte JSONB-Tabelle wird einmalig migriert.
3. load_recipes() liest per SQL; ohne DB → HTTP 503 (maintenance/db-unavailable.php).
4. Admin: save_recipe() / delete_recipe() – direkt in die Tabellen.

Einmalig Daten laden: php scripts/db-seed.php (aus data/recipes.json).

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

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.