smacksandClaude Sonnet 4.6
86fbd8e4bb
All content (recipes + imprint/privacy settings) now lives exclusively in Postgres. The app no longer requires a seed step on first deploy. Changes: - helpers.php: load_site_settings() returns defaults when site_settings table is empty instead of throwing DatabaseUnavailableException; removes legacy JSONB migration path - data/recipes.json, data/site.json: deleted (content already in DB) - scripts/db-seed.php: deleted (no longer needed) - docker-compose.yml: remove RUN_DB_SEED env var and data/ volume mount - docker/entrypoint.sh: remove RUN_DB_SEED seed block - docs/COOLIFY.md: update deployment guide to reflect seedless workflow - .claude/launch.json: add dev server configurations for preview tool Fresh deploys now start with placeholder legal pages and an empty recipe list; the admin fills in real content via /admin.php without any CLI step. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
132 lines
6.2 KiB
Markdown
132 lines
6.2 KiB
Markdown
# FlixCooks Project Brain
|
|
|
|
This document summarizes architectural knowledge, conventions, and learnings for humans and AI agents working on this repo.
|
|
|
|
## 1. Project Architecture & Stack
|
|
- **Backend:** Vanilla PHP. No heavy frameworks.
|
|
- **Database:** PostgreSQL required (`DATABASE_URL` in `.env`). Normalized tables in `scripts/schema.sql`; `load_recipes()` / `save_recipe()` and `load_site_settings()` / `save_site_settings()` in `helpers.php`. No runtime JSON files. One-time import: `php scripts/db-seed.php` from `scripts/seed-data.php`.
|
|
- **Site settings (legal pages):** Stored in Postgres table `site_settings`; no flat-file fallback.
|
|
- **Admin Panel (`admin.php`):** Lightweight CMS. Textareas use one line per array element (`ingredients`, `steps`, `step_videos`, `step_timers`).
|
|
- **Frontend:** Server-rendered PHP (`index.php`, `recipe.php`, …), Vanilla JS/CSS. Profile/favorites via `assets/fc-local.js`.
|
|
- **Config:** `config.php` loads `.env`, `get_db_connection()`. Never commit `.env` (see `.gitignore`).
|
|
|
|
## 2. Design & Aesthetics
|
|
- **CSS:** Custom properties (`var(--ease-out-expo)`, `var(--surface-1)`), glassmorphism, `FloemaLayoutGrid`.
|
|
- **Lenis:** Call `lenis.stop()` when opening fullscreen overlays (e.g. Cooking Mode); `lenis.start()` on close.
|
|
- **Preloader:** `CapitoliumPreloader` on homepage; once per session via `sessionStorage('flixcooks_preloader_seen')`.
|
|
|
|
## 3. Antigravity Agent Configuration
|
|
- **Workspace Rules:** `.agents/rules/` with `always_on: true` and `glob: "*"` in frontmatter.
|
|
- **Custom Skills:** `.agents/skills/` (e.g. `close_feature.json` for Git merge workflow).
|
|
|
|
## 4. GitHub Actions & CI/CD
|
|
- **Gemini PR review:** `petarzarkov/gemini-code-review-action`; secrets via `env:` not `with:`; pin action versions; use full model names (e.g. `gemini-2.0-flash-lite`).
|
|
|
|
---
|
|
|
|
## 5. PostgreSQL — Schema & Data Flow
|
|
|
|
### Relational schema (`scripts/schema.sql`)
|
|
Created by `ensure_recipe_schema()` on first DB use. Legacy JSONB/file fallbacks are not supported.
|
|
|
|
| Table | Role |
|
|
|-------|------|
|
|
| `recipes` | slug, hero, times, servings, nutrition columns, featured, coming_soon |
|
|
| `recipe_translations` | title, description, category, difficulty (en/de) |
|
|
| `recipe_tags`, `recipe_ingredients`, `recipe_utensils`, `recipe_steps` | Ordered lists per language |
|
|
| `site_settings` | imprint/privacy fields per language |
|
|
|
|
PHP still exposes the same nested arrays (`i18n`, `nutrition`, …) via `hydrate_recipes_from_db()`.
|
|
|
|
### Runtime flow
|
|
1. `DATABASE_URL` required → `require_database()` or HTTP 503 (`maintenance/db-unavailable.php`).
|
|
2. `load_recipes()` → SQL → PHP arrays for templates.
|
|
3. Admin: `save_recipe()`, `delete_recipe()`, `clear_featured_recipes()`.
|
|
4. One-time import: `php scripts/db-seed.php` from `scripts/seed-data.php`.
|
|
|
|
### `config.php` functions
|
|
- `load_env()` — parses `.env`.
|
|
- `get_db_connection()` — PDO or `null`.
|
|
- `DatabaseUnavailableException` — thrown when DB is required but missing.
|
|
|
|
---
|
|
|
|
## 6. Local Development — Docker Postgres
|
|
|
|
### Files
|
|
- `docker-compose.dev.yml` — Postgres 16 Alpine, container `flixcooks-postgres-dev`, port `5432`.
|
|
- `.env.example` — template including local `DATABASE_URL`.
|
|
- `scripts/db-check.php` — CLI: connect, `init_db()`, print recipe count + sample slugs/titles.
|
|
|
|
### Docker credentials (dev only)
|
|
```
|
|
POSTGRES_USER=flixcooks
|
|
POSTGRES_PASSWORD=flixcooks_dev
|
|
POSTGRES_DB=flixcooks_dev
|
|
DATABASE_URL="postgresql://flixcooks:flixcooks_dev@127.0.0.1:5432/flixcooks_dev"
|
|
```
|
|
|
|
### Commands
|
|
```bash
|
|
docker compose -f docker-compose.dev.yml up -d # start
|
|
docker compose -f docker-compose.dev.yml ps # health
|
|
docker compose -f docker-compose.dev.yml down # stop (data kept)
|
|
docker compose -f docker-compose.dev.yml down -v # stop + wipe volume → re-seed on next hit
|
|
|
|
docker exec -it flixcooks-postgres-dev psql -U flixcooks -d flixcooks_dev
|
|
# psql: \dt , \d recipes , SELECT slug FROM recipes; , \q
|
|
```
|
|
|
|
### PHP requirements (WSL/Linux)
|
|
- Extension **`php-pgsql`** (or `php8.5-pgsql`) required; without it the site cannot connect.
|
|
- Install interactively: `sudo apt install php8.5-pgsql` (sudo in non-interactive agent shells may timeout).
|
|
- Verify: `php -m | grep pgsql` → expect `pdo_pgsql`, `pgsql`.
|
|
|
|
### App server
|
|
```bash
|
|
php -S localhost:8000
|
|
php scripts/db-check.php # after .env + pgsql OK
|
|
```
|
|
|
|
### `.env` rules for agents
|
|
- Copy from `.env.example`; never commit `.env`.
|
|
- **Local:** use `127.0.0.1` Docker URL above.
|
|
- **`DATABASE_URL` is mandatory** for recipe pages; omitting it shows the DB unavailable page.
|
|
|
|
### Environment separation (important)
|
|
- One database per environment (local Docker / staging / production).
|
|
- Never point a dev branch `.env` at production Postgres.
|
|
- Export/import between envs: `pg_dump` / `psql` when needed; document URLs in hosting secrets, not in repo.
|
|
|
|
---
|
|
|
|
## 7. Troubleshooting (known issues)
|
|
|
|
| Symptom | Cause | Fix |
|
|
|--------|--------|-----|
|
|
| HTTP 503, database unavailable | No `DATABASE_URL` or Postgres down | Fix `.env`, start Docker, `php scripts/db-check.php` |
|
|
| Log: `could not find driver` | `php-pgsql` not installed | `sudo apt install php8.5-pgsql` |
|
|
| DB OK but 0 recipes | Empty tables | `php scripts/db-seed.php` |
|
|
|
|
---
|
|
|
|
## 8. Completed Milestones
|
|
- **Phase 3 (Nutrition):** `calories`, `protein`, `carbs`, `fat` on recipes; admin + UI.
|
|
- **Phase 4 (Cooking Mode):** `step_videos`, `step_timers`; fullscreen overlay.
|
|
- **Phase 6 (Postgres):** Normalized SQL tables; `db-seed.php`; no runtime JSON recipes.
|
|
- **Local dev Postgres:** `docker-compose.dev.yml`, README section, `scripts/db-check.php`, `.env.example` with `DATABASE_URL`.
|
|
- **Local profile data:** Favorites/goals via `assets/fc-local.js` (`localStorage`). Newsletter via `mailto:`.
|
|
|
|
## 9. Next Steps
|
|
See `.agents/TODO.md` (e.g. PWA & offline support). README `Local Postgres (Docker)` and `Postgres in diesem Projekt` sections mirror setup for humans.
|
|
|
|
## 10. Key file map (data layer)
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `config.php` | `.env`, Firebase config, PDO |
|
|
| `helpers.php` | `init_db`, `load_recipes`, `save_recipe`, site settings |
|
|
| `scripts/seed-data.php` | Seed arrays for recipes and site settings |
|
|
| `docker-compose.dev.yml` | Local Postgres |
|
|
| `scripts/db-check.php` | Connection + seed smoke test |
|
|
| `partials/head.php` | Firebase init via `get_firebase_config()` |
|