167 lines
7.2 KiB
Markdown
167 lines
7.2 KiB
Markdown
# 🍳 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](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 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:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
2. Set **`DATABASE_URL`** in `.env` (required). See [Local Postgres (Docker)](#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.
|
||
|
||
```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:**
|
||
|
||
```bash
|
||
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:
|
||
```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)
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
## 📈 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).
|