# 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](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`](docs/orchestrator.md)

---

## Quick Start

### Prerequisites
- Node.js 22+
- Docker & Docker Compose (for deployment)
- npm or pnpm

### Development Setup

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

# Install dependencies
npm install

# Initialize local database schema + starter sample recipes
npm run migrate
npm run seed

# 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):

   ```bash
   docker-compose up -d
   ```

2. **Check running services:**

   ```bash
   docker-compose ps
   ```

3. **View container logs:**

   ```bash
   docker-compose logs -f
   ```

4. **Access the app:**
   - Frontend: http://localhost:8080 (default)
   - Backend API: http://localhost:3000

5. **Stop services:**

   ```bash
   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](PROJECT.md) — Why we're building this
- [Architecture Guide](ARCHITECTURE.md) — Technical decisions & patterns
- [Roadmap](ROADMAP.md) — Planned features & milestones
- [Planning Terminology](docs/planning-terminology.md) — Execution Board vs Roadmap vs Backlog
- [Agent Instructions](AGENT_INSTRUCTIONS.md) — How AI agents contribute
- [API Docs](docs/api.md) — Endpoint reference
- [User Guide](docs/user-guide.md) — 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.

### Workflow Automation (local)

Use these scripts for periodic harness execution:

```bash
# 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](RUNBOOK.md#workflow-periodic-execution-cron--systemd).

---

## Contributing

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

### For Humans
1. Read [PROJECT.md](PROJECT.md) and [ARCHITECTURE.md](ARCHITECTURE.md)
2. Check [ROADMAP.md](ROADMAP.md) for open tasks
3. Follow patterns in [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md)
4. Submit PRs with tests + documentation

### For AI Agents
Read [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) — it's your operating manual.

---

## Testing

```bash
# 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
```bash
npm run dev
```
Access at http://localhost:5173 (frontend) and http://localhost:3000 (API).

### Production (paje.ca)
```bash
# On server
docker-compose up -d

# Check status
docker-compose ps

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

### Backup & Restore
```bash
# 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:

```env
# 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
```bash
# Check for stale locks
fuser data/recipes.db
# Kill if needed, then restart
docker-compose restart
```

### Port already in use
```bash
# Find process using port 3000
lsof -i :3000
# Kill it
kill -9 <PID>
```

### Tests failing
```bash
# 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](ROADMAP.md) for details.

---

**Questions?** Check [docs/](docs/) or ask Paul.