328 lines
7.2 KiB
Markdown
328 lines
7.2 KiB
Markdown
# 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
|
|
|
|
# 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
|
|
- [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.
|
|
|
|
---
|
|
|
|
## 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.
|