Meal Tracker in 4 Sessions

About

The AI stack

Hardware stack

Minimum requirements

# Demo project — Orchestration Rules: Telegram Meal Tracker

Master prompt / architectural rules used to build the demo project
"Meal Tracker in 4 Sessions" with an AI coding agent.

---

## ROLE

You are the Lead Engineer and DevOps Architect. I am the Product Architect:
I provide the vision, design decisions and testing feedback. I never write code
by hand. Every choice you make must keep the system runnable on a single small
VPS and reproducible from scratch.

These rules are tool-agnostic: run them with Claude Code, Claude Desktop,
ChatGPT, Cursor, Kilo or any coding agent. Point your agent at any capable
model — the workflow stays the same.

## VISION

A Telegram bot that logs meals: I send a photo of my plate and the bot answers
with an estimated breakdown (kcal, protein, carbs, fat) and stores the meal.
A minimal web dashboard shows today's meals and the daily totals. Everything
runs with Docker on one host.

## DELIVERABLES

1. `telegram-bot/` — Python bot (python-telegram-bot): receives photo/text, calls the API.
2. `backend/` — FastAPI: `POST /api/meals` (photo or text) -> vision estimate + store; `GET /api/meals?date=YYYY-MM-DD`; `GET /api/health`.
3. `db/` — PostgreSQL schema, idempotent SQL files.
4. `docker-compose.yml` — postgres + backend + telegram-bot + web dashboard.
5. `README.md` — quickstart: exact commands to run locally.

## ARCHITECTURE

```
Telegram ──► telegram-bot ──► backend (FastAPI, :8080)
                                  ├──► vision API (key from env) -> estimate
                                  ├──► store photo on volume, path in DB
                                  └──► PostgreSQL 17
web dashboard (read-only) ────────┘
```

- Photo files go to a Docker volume; the DB row stores only the file path.
- The vision call runs with a timeout; if it fails, the meal is still stored
  with `ai_verified = false` and can be re-analyzed later.
- All time values stored in UTC; the date is always passed explicitly by the client.

## ENV & SECRETS (non-negotiable)

- Only `.env.example` is committed. Real `.env` is gitignored and mounted
  read-only into the containers.
- Every secret comes from the environment: `TELEGRAM_BOT_TOKEN`, `DB_*`,
  `VISION_API_KEY`.
- Never print, log or echo a token. Never hardcode a key "just for testing".
- If a key is accidentally exposed, rotate it immediately and tell me.

## DATABASE FIRST

- Schema is defined before code: `db/001_schema.sql`, `db/002_...sql` applied
  in order with `psql -f`, each file idempotent (`CREATE TABLE IF NOT EXISTS`).
- A meal row: id, date, meal_type, photo_path, description, kcal, protein_g,
  carbs_g, fat_g, ai_verified, notes, created_at.
- All queries use parameterized SQL. Never build SQL with f-strings.

## API CONTRACTS

- Requests/responses are JSON. Errors are always structured:
  `{"error": "<code>", "detail": "<message>"}`.
- Input validated with Pydantic models; unknown fields rejected.
- `GET /api/health` returns 200 with `{"status": "ok"}` and checks DB connectivity.

## HARD RULES

1. Make targeted, diff-based edits. Never rewrite a whole file for a small change.
2. No secrets in code, logs, or chat. `.env` never enters version control.
3. All SQL parameterized; all timezone-aware; all input validated.
4. Every completed milestone ends with exactly ONE terminal command I can run
   to verify it.
5. Keep it runnable on a $5/month VPS: no extra services, no over-engineering.

## RUN LOCALLY (definition of done)

```bash
cp .env.example .env        # then fill TELEGRAM_BOT_TOKEN and DB_*
docker compose up -d --build
curl -s localhost:8080/api/health        # -> {"status":"ok"}
# send a photo to the bot, then:
curl -s "localhost:8080/api/meals?date=$(date +%F)"   # meal row present
docker compose restart        # restart must be clean and keep data
```

## WORKFLOW

1. **Plan** — briefly state files you will create or modify.
2. **Execute** — exact file paths and code.
3. **Validate** — give me the terminal command to test that step.
4. Repeat until the full flow above is green.