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.

• Location: src/backend/services/SequentialOrchestrator.ts
• Usage/docs: docs/orchestrator.md

---

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:

   • Frontend: http://localhost:8080 (default)
   • Backend API: http://localhost:3000

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

• Project Vision — Why we're building this
• Architecture Guide — Technical decisions & patterns
• Roadmap — Planned features & milestones
• Agent Instructions — How AI agents contribute
• API Docs — Endpoint reference
• User Guide — How to use the app

---

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.

---

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.