paulh
/
recipe-manager
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
recipe-manager/README.md

7.8 KiB
Raw Blame History

Recipe Manager

Self-hosted, privacy-first recipe management app

Built with ❤️ by autonomous AI agents for the Huliganga family.

Repository: https://paje.ca/git/paulh/recipe-manager

Status

🚧 In Development — MVP phase
📋 See ROADMAP.md for current milestone

What Is This?

A modern, self-hosted alternative to services like CopyMeThat. Store, organize, and cook from your recipes with full data ownership.

Key Features (MVP)

  • ✅ Manual recipe entry
  • ✅ Tag-based organization
  • ✅ Text search
  • ✅ Cook mode (ingredient checklist + step tracking)
  • ✅ Self-hosted deployment (Docker)

Planned Features

  • Recipe scraping (browser extension)
  • Serving size scaling
  • Meal planning & shopping lists
  • AI-powered ingredient substitutions
  • Integration with Fintrove (cost tracking)

Backend Orchestrator (Phase Execution Utility)

A sequential orchestrator utility is available for robust, checkpointed phase execution with per-phase retries. Useful for automation harnesses or recipe import flows needing durable, restart-safe progress tracking.

Quick Start

Prerequisites

  • Node.js 22+
  • Docker & Docker Compose (for deployment)
  • npm or pnpm

Development Setup

# Clone the repo
cd /home/paulh/.openclaw/workspace/projects/recipe-manager

# Install dependencies
npm install

# Start backend (development mode)
npm run dev:backend

# Start frontend (separate terminal)
npm run dev:frontend

# Run tests
npm test

Production Setup & Deployment

  1. Build and start containers (from project root):

    docker-compose up -d

  2. Check running services:

    docker-compose ps

  3. View container logs:

    docker-compose logs -f

  4. Access the app:

  5. Stop services:

    docker-compose down

Project Structure

recipe-manager/
├── src/
│   ├── backend/          # Express API
│   │   ├── routes/       # API endpoints
│   │   ├── services/     # Business logic
│   │   ├── repositories/ # Database access
│   │   └── types/        # TypeScript types
│   ├── frontend/         # React app
│   │   ├── components/   # UI components
│   │   ├── hooks/        # React hooks
│   │   ├── pages/        # Route pages
│   │   └── services/     # API client
│   └── shared/           # Shared types/utilities
├── tests/
│   ├── unit/             # Unit tests
│   ├── integration/      # API integration tests
│   └── e2e/              # End-to-end tests
├── docs/
│   ├── api.md            # API documentation
│   ├── user-guide.md     # User manual
│   └── ADR-*.md          # Architecture decision records
├── data/                 # SQLite database (gitignored)
├── PROJECT.md            # Product vision
├── ARCHITECTURE.md       # Technical design
├── ROADMAP.md            # Development milestones
├── AGENT_INSTRUCTIONS.md # How agents work on this project
└── docker-compose.yml    # Deployment config

Technology Stack

Backend

  • Node.js + TypeScript — Modern, type-safe JavaScript
  • Express — Minimal, flexible web framework
  • SQLite (better-sqlite3) — Fast, embedded database
  • Zod — Runtime type validation

Frontend

  • React 18 — Component-based UI
  • Vite — Lightning-fast dev server
  • Tailwind CSS — Utility-first styling
  • React Router — Client-side routing

DevOps

  • Docker Compose — Container orchestration
  • Caddy — Reverse proxy with auto-HTTPS
  • Vitest — Fast, modern test runner

Documentation

Development Workflow

This project is built agent-first using OpenClaw autonomous agents:

  1. Agent reads context — PROJECT.md, ARCHITECTURE.md, ROADMAP.md
  2. Agent picks next task — From the current milestone
  3. Agent implements & tests — Following coding standards
  4. Agent commits & documents — Conventional commits + ADRs
  5. Agent reports completion — Or escalates if blocked

Human oversight at milestone boundaries.

Workflow Automation (local)

Use these scripts for periodic harness execution:

# Resume from checkpoint (default mode)
npm run workflow:run

# Force fresh run (ignore checkpoint progress)
npm run workflow:run -- --mode restart

# Scheduler entrypoint: resume workflow + generate morning report
npm run workflow:schedule

# Health check for automations/alerts (exit 0=healthy, 1=failed/blocked/unknown)
npm run workflow:health-check

For cron/systemd examples and failed/blocked troubleshooting, see RUNBOOK.md.

Contributing

This is a personal/family project, but contributions welcome!

For Humans

  1. Read PROJECT.md and ARCHITECTURE.md
  2. Check ROADMAP.md for open tasks
  3. Follow patterns in AGENT_INSTRUCTIONS.md
  4. Submit PRs with tests + documentation

For AI Agents

Read AGENT_INSTRUCTIONS.md — it's your operating manual.

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run specific test file
npm test -- RecipeService.test.ts

# E2E tests (requires app running)
npm run test:e2e

Coverage goal: >80% on core business logic.

Deployment

Local Development

npm run dev

Access at http://localhost:5173 (frontend) and http://localhost:3000 (API).

Production (paje.ca)

# On server
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f recipe-manager

Backup & Restore

# Backup database
cp data/recipes.db data/recipes-backup-$(date +%Y%m%d).db

# Restore
cp data/recipes-backup-20260323.db data/recipes.db
docker-compose restart

Environment Variables

Create .env file:

# Backend
NODE_ENV=production
PORT=3000
DATABASE_PATH=/app/data/recipes.db

# Frontend (build-time)
VITE_API_URL=https://recipes.paje.ca/api

Troubleshooting

Database locked

# Check for stale locks
fuser data/recipes.db
# Kill if needed, then restart
docker-compose restart

Port already in use

# Find process using port 3000
lsof -i :3000
# Kill it
kill -9 <PID>

Tests failing

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
npm test

License

Private project — All rights reserved (for now).
May open-source later.

Credits

Product Owner: Paul Huliganga
Primary Users: Anne & Elizabeth
Development: Autonomous AI agents (Codex 5.2) via OpenClaw
Human Oversight: Paul

Built as a learning project for agentic engineering and modern web development.

Roadmap Highlights

  • MVP (v0.1): Manual entry, tags, search, cook mode ← You are here
  • v1.0: Recipe scraping, advanced search, multi-device sync
  • v2.0: AI features (meal planning, cost tracking, substitutions)

See ROADMAP.md for details.

Questions? Check docs/ or ask Paul.