FlixCooks Project Brain

This document summarizes the architectural knowledge, conventions, and learnings accumulated during our session.

1. Project Architecture & Stack

Backend: Vanilla PHP. The project intentionally avoids heavy frameworks.
Database: Flat-file JSON database (data/recipes.json). Data is loaded and saved via utility functions in helpers.php.
Admin Panel (admin.php): Acts as a lightweight CMS. It uses simple textareas where each line maps to an array element (e.g., for ingredients, steps, step_videos, step_timers). This keeps the JSON structure clean and parsing straightforward.
Frontend: Server-rendered PHP templates (index.php, recipe.php) with Vanilla JavaScript and Vanilla CSS. No Tailwind or heavy component libraries.

2. Design & Aesthetics

CSS: Highly customized CSS with modern design tokens (e.g., var(--ease-out-expo), var(--surface-1)).
Animations: Employs sophisticated micro-animations, glassmorphism (backdrop-filter: blur), and dynamic layouts (e.g., clip-path for overlays).
Smooth Scrolling: Uses Lenis (LenisSmoothScroll).
- Crucial Rule: Whenever a fullscreen overlay (like the Cooking Mode) is opened, lenis.stop() must be called to prevent background scrolling. When closed, call lenis.start().
Preloader: A custom CapitoliumPreloader runs on the homepage. It is cached in sessionStorage('flixcooks_preloader_seen') so it only fires once per browsing session.

3. Antigravity Agent Configuration

Workspace Rules: Best placed in .agents/rules/ (e.g., AGENT.md). To ensure they are always active, the frontmatter must include:
```
always_on: true
glob: "*"
```
Custom Skills: Can be defined as JSON files in .agents/skills/. We successfully created close_feature.json to automate the Git workflow of checking out main, merging a feature branch, verifying functionality, and deleting the branch.

4. GitHub Actions & CI/CD

Gemini Code Review Automation: We integrated petarzarkov/gemini-code-review-action to automatically review PRs.
- Secrets: Must be passed using env: instead of with: (e.g., GEMINI_API_KEY, GITHUB_TOKEN), otherwise the action fails with unexpected input errors. NEVER hardcode API keys in workflow files.
- Model Naming: Google's v1beta API is very strict. gemini-1.5-flash often fails. You must use the fully-qualified name like gemini-1.5-flash-latest or gemini-2.0-flash-lite.
- Pinning Versions: Always pin GitHub Actions to a specific version tag (e.g., @v1.0.4) rather than @latest to prevent unexpected breaking changes.

5. Completed Milestones

Phase 3 (Nutrition): Implemented. Recipes now store calories, protein, carbs, and fat. Admin panel handles inputs, and the UI displays them beautifully.
Phase 4 (Interactive Cooking Mode): Implemented. Recipes now support step-by-step looping background videos and interactive timers (step_videos, step_timers). The UI utilizes a fullscreen overlay slider with Vanilla JS logic.
Phase 6 (Firestore Database Migration): Migrated recipes database from data/recipes.json to Firebase Firestore.
- Zero-Dependency REST API Read: Server-side read requests in helpers.php use native PHP cURL to query the Firestore REST API /documents/recipes. Complex Firestore nested type maps are dynamically parsed into clean standard associative arrays using custom decoders.
- Dynamic Local Fallback: In case of rate limits, network failures, or missing .env config, all lookup functions automatically fail back to the local recipes.json flat-file, guaranteeing 100% database availability and site resilience.
- Browser-Driven Seeding & Auto-Sync: Admin seeding and real-time updates are executed client-side in admin.php via the authenticated Firebase Client SDK, keeping the local file and Cloud Firestore perfectly in sync without server-side OAuth2 keys.

6. Next Steps

According to TODO.md, the next major feature block is completing the database seeding (by clicking "Seed Firestore" on admin.php in the browser) and verifying all recipe updates reflect in real-time. Afterwards, we can proceed to Phase 5 (PWA & Offline Support).

4.2 KiB Raw Blame History