MealForge

A meal planning web app that helps you build weekly meal plans from templates and track how well you follow them. Built as ***plain specifications, ready to be rendered into production code via Codeplain.

What It Does

• Meal Library — Store meals with macros (protein, carbs, fat, fiber) and tag them with slot types (e.g., "pre-workout", "light lunch")
• Day & Week Templates — Define reusable day structures (ordered meal slots) and combine them into week templates ("Normal Work Week", "Vacation Week")
• Auto-Generated Plans — Pick a week template on Sunday, and the app fills every slot from your meal library via round-robin assignment
• Outcome Tracking — Log each meal as Followed, Skipped, Changed, Deviated, or Social
• Adherence Statistics — See how well you stuck to the plan, broken down by slot type, weekday, and week (30/60/90 day views)
• AI Meal Suggestions — Use Claude API to populate your meal library with meals that fit specific slot types

Tech Stack

Layer	Technology
Backend	Python 3.12, FastAPI, SQLAlchemy, Alembic
Frontend	React, TypeScript, Vite, TailwindCSS, React Query
Database	PostgreSQL
AI	Anthropic Claude API
Testing	pytest (backend), Vitest (frontend)

Project Status

The project is fully specified in .plain files and ready to be rendered into code. No code has been generated yet.

Repository Structure

backend.plain                  # Backend API specs (17 functional specs)
frontend.plain                 # Frontend UI specs (17 functional specs)
template/
  mealforge.plain              # Shared definitions and implementation reqs
config.yaml                    # Codeplain renderer configuration
test_scripts/
  run_unittests_python.sh      # Backend unit test runner
  run_conformance_tests_python.sh      # Backend conformance test runner
  run_unittests_typescript.sh          # Frontend unit test runner
  run_conformance_tests_typescript.sh  # Frontend conformance test runner
.claude/
  docs/PLAIN_REFERENCE.md     # ***plain language reference
  skills/                     # Spec-writing skills for Claude Code
  rules/                      # Validation rules for spec sections

Spec Overview

Modules

Module	File	Specs	Description
Shared	template/mealforge.plain	8 concepts, 13 impl reqs	Core entity definitions and tech stack
Backend	backend.plain	17 functional specs	REST API, database models, plan generation, statistics
Frontend	frontend.plain	17 functional specs	React SPA with 6 pages (Today, Week, Templates, Meals, Stats, Settings)

Build Chain

template/mealforge.plain (imported by both)
        |
   backend.plain  ──requires──>  frontend.plain

The backend renders first. The frontend requires the backend, inheriting its API specs as context.

Rendering

To generate the code from specs, use the Codeplain renderer:

# 1. Render the backend (config.yaml already points to Python test scripts)
codeplain backend.plain

# 2. Switch config.yaml to TypeScript test scripts, then render the frontend
codeplain frontend.plain

Generated code will appear in plain_modules/backend/ and plain_modules/frontend/.

Modifying Specs

This project uses Plain Forge skills for spec authoring via Claude Code. To add features or modify behavior:

1. Start a Claude Code session in this directory
2. Use /add-feature to add a new feature through a guided interview
3. Or edit .plain files directly following the rules in .claude/rules/
4. Re-render with codeplain to regenerate the code

Key rules:

• Each functional spec must imply max 200 lines of code change
• Specs are rendered top-to-bottom — earlier specs cannot reference later ones
• Never edit generated code in plain_modules/ — fix the .plain specs instead

License

See LICENSE for details.