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](https://github.com/darkroomengineering/lenis) for premium, inertia-driven page physics.
- **Animations**: [GSAP (GreenSock Animation Platform)](https://greensock.com/gsap/) 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:
   ```bash
   cp .env.example .env
   ```
2. Open `.env` and optionally set **local Postgres** (see [Local Postgres (Docker)](#local-postgres-docker) below).

### 2. Local Postgres (Docker)

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

```bash
# 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`):

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

**PHP-Extension (WSL/Ubuntu, einmalig):**

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

**Datenbank-Shell (zum Lernen / Inspizieren):**

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

Nützliche SQL-Befehle in `psql`:

```sql
\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):

```bash
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:
```bash
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:///.agents/TODO.md) file.
Architectural learnings, conventions, and configuration updates are maintained in the central knowledge base: [.agents/brain.md](file:///.agents/brain.md).