Repository Guide

Cookest is a multi-repository project. Each repository is an independent component with its own Git history, CI/CD, and deployment. This page documents what each repo does and how they connect.

Ecosystem Map

Repository Details

api/ — Backend workspace

Purpose: The api/ repo now contains the full backend workspace: the deployed App API, the standalone Food API, shared Rust crates, the legacy monolith source retained for reference, and the Python image-generation microservice.

Key directories:

api/
├── src/                    ← legacy monolith (not the deployed binary)
├── crates/app-api/         ← deployed App API with auth, meal plans, pantry, AI chat, and proxies
├── crates/food-api/        ← standalone food catalog service
├── crates/shared/          ← shared errors, DTOs, and common types
└── image-gen/              ← Python image generation microservice

Crate / service roles:

• crates/app-api — the main deployed API used by mobile and web clients
• crates/food-api — catalog and browse service for recipes and ingredients
• crates/shared — reusable errors and shared Rust types
• image-gen/ — async hero/step recipe image generation service
• src/ — legacy monolith code, kept for migration/reference purposes only

Quick start:

cd api
cp .env.example .env
docker compose up --build

UI/ — Flutter Mobile App

Purpose: Native iOS/Android client for meal planning, shopping, pantry management, and AI chat.

Key directories:

UI/lib/src/
├── core/          ← API client, auth, storage
├── features/      ← Feature modules (auth, recipes, meal_plan, etc.)
└── shared/        ← Reusable widgets, theme, components

Quick start:

cd UI
flutter pub get
flutter run                     # Run on connected device/emulator

web/ — Next.js Landing Page

Purpose: Public-facing marketing site showcasing Cookest features, app download links, and sustainability mission.

Key components:

web/app/components/
├── Nav.tsx, Hero.tsx, Features.tsx
├── Showcase.tsx, HowItWorks.tsx
├── Sustainability.tsx, Download.tsx
├── TranslationProvider.tsx      ← i18n context
└── ShaderCanvas.tsx             ← WebGL effects

Quick start:

cd web
npm install
npm run dev                     # Start on localhost:3000

cookest-ad/ — Remotion video ads

Purpose: Generates polished video ad assets for Cookest marketing campaigns and promos.

Highlights:

• Multi-scene Remotion composition driven by scripted cursor motion
• Automated screenshot capture via Puppeteer for repeatable scene assets
• Separate marketing-focused repo so motion work can iterate independently from app and backend code

etl/ — Python Data Pipeline

Purpose: Extract, transform, and load recipe + nutrition data into the PostgreSQL database.

Pipeline stages:

1. Extract → Read CSV + API responses with rate limiting
2. Transform → Normalize ingredients, deduplicate, convert units, enrich nutrition
3. Load → Bulk upsert into PostgreSQL (idempotent)

Quick start:

cd etl
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env            # Set DATABASE_URL, USDA_API_KEY
python main.py

dataset/ — Recipe Data

Contains MM-Food-100K.csv — approximately 100,000 recipe records with:

• Recipe name, cuisine, cooking method
• Ingredient lists (JSON)
• Nutritional profiles (calories, fat, protein, carbs)
• Portion sizes with gram equivalents
• Image URLs

This CSV is consumed by the ETL pipeline.

docs/ — Documentation Site

Purpose: Centralized documentation for the entire ecosystem. You're reading it now.

See Documentation Architecture for technical details.

.github/ — Organization Profile

Contains the GitHub organization profile README and assets displayed on the Cookest GitHub organization page. Separate Git repository.

How Components Connect

Authentication Flow

Data Flow

Subscription Tiers