Duward's Project Guide

Project: GPT Workout Planner
Category: AI / Mobile Web App (Flask + Tailwind)
Last updated: April 24

Note: This guide reflects the latest state of your project repo (final-project-angldu6). It may not match the most up-to-date version if you've worked since.

Where You Are

Your Flask app works: / + /generate, Tailwind templates, .env for the key, and a solid Checkpoint 2 journal entry.

Two pieces of business logic you already wrote in planner.py are not wired into Flask — they only existed in the old commented-out main.py flow:

1. select_group_and_workouts(goal, options_data, location_key) — picks a focus group using GOAL_GROUP_WEIGHTS + build_group_weights (e.g. "lose weight" biases toward cardio). app.py still calls pick_focus_group(recent) + workouts_for_group(...), which ignores the goal text for picking.
2. load_last_workout() / save_workout(goal, plan_text) — workouts/history.json supports history, but app.py never reads or writes it.

Checkpoint 3 is about activating that code, polishing the repo for portfolio + Demo Day, and optionally deploying.

Phase 1: Wire up smart goal-based focus picking

Handwrite the edits. This is your planner logic — you should understand every line.

Objective

Use select_group_and_workouts in /generate so focus-group choice reflects keywords in the user's goal (while still avoiding repeats from recent_focus_groups).

Instructions

• Open app.py
• Change imports: remove load_previous_groups, save_previous_groups, pick_focus_group, and workouts_for_group. Add select_group_and_workouts from planner.
• In /generate, after is_valid_goal passes and you have options = load_options(), replace the block that does recent = load_previous_groups(), group = pick_focus_group(recent), workouts = workouts_for_group(...), and the later recent.append(group) + save_previous_groups(recent[-2:]) with one call:

group, workouts = select_group_and_workouts(goal, options, location_key)

• Remove any now-unused imports from planner
• Run the app and submit a few times with goal "lose weight" vs "build muscle" — over several tries you should see cardio / legs_core show up more often for weight-loss wording (not every time — it's weighted random)

Hints

select_group_and_workouts already:

• loads recent groups from workouts/history.json
• filters out groups in recent_focus_groups (or resets if all are used)
• applies build_group_weights from GOAL_GROUP_WEIGHTS
• picks with random.choices(..., weights=...)
• saves the updated recent_focus_groups via save_previous_groups

So do not duplicate load_previous_groups / save_previous_groups in app.py for the focus group — that would double-save or fight the planner.

Optional — get help from your agent:

Read my app.py and planner.py. After Phase 1, does /generate still
update recent_focus_groups exactly once per request? Trace the call
path into select_group_and_workouts. Don't change my code — explain.

Phase 2: Show "Your last workout" on the home page

Mixed. Small app.py changes + template.

Objective

After each successful generation, persist the plan to history. On /, show the most recent workout in a collapsible block so users see context before submitting again.

Instructions

• In app.py, import load_last_workout and save_workout from planner
• In the / route, call last_workout = load_last_workout() and pass last_workout=last_workout to render_template("home.html", ...)
• In /generate, after you have plan = response.output_text.strip(), call save_workout(goal, plan) before return render_template("result.html", ...)
• In templates/home.html, above the error block / form, add a <details> section that only renders when last_workout is truthy — show the text inside <pre class="..."> with whitespace-pre-wrap so line breaks from load_last_workout() display cleanly

Hints

/ route shape:

@app.route("/")
def home():
    last = load_last_workout()
    return render_template("home.html", last_workout=last)

Fragment for home.html (inside {% block content %}, before {% if error %}):

{% if last_workout %}
<details class="mb-6 rounded-xl border border-slate-200 bg-white p-4 text-sm">
  <summary class="cursor-pointer font-semibold text-slate-800">
    Your last workout
  </summary>
  <pre class="mt-3 whitespace-pre-wrap font-sans text-slate-700 text-xs leading-relaxed">{{ last_workout }}</pre>
</details>
{% endif %}

If last_workout is always empty, check workouts/history.json — save_workout must run after a successful OpenAI response.

Optional — get help from your agent:

My home.html shows last_workout but the <pre> is one long line. Fix
only the CSS/classes so newlines from load_last_workout() render.
Don't change planner.py.

Phase 3: Loading state on submit

Agent-assisted OK. View-only + tiny inline JS.

Objective

While OpenAI responds, the user should see feedback — disabled button + "Generating…" so they don't double-submit.

Instructions

• On <form method="post" action="/generate" ...>, add onsubmit="..." (or a <script> at the bottom of home.html) that:
  • finds the submit button
  • sets disabled = true
  • replaces button label with "Generating…" and optionally adds a small Tailwind spinner (inline svg or animate-spin border)
• Test: slow network or a heavy prompt — button should stay disabled until the new page loads

Hints

Minimal pattern — add to the <form> tag:

<form
  method="post"
  action="/generate"
  class="space-y-6"
  onsubmit="this.querySelector('button[type=submit]').disabled=true; this.querySelector('button[type=submit]').textContent='Generating…';"
>

Polish version: keep the button text in a <span id="gen-label"> and toggle a sibling spinner hidden class.

Optional — get help from your agent:

Add a Tailwind spinner next to my submit button in home.html. On
form submit, hide the original label, show spinner, disable button.
Keep method/action unchanged.

Phase 4: Portfolio polish (README, spec, main.py, .env.example, screenshot)

Handwrite the prose in spec/README/journal; file moves are straightforward.

Objective

Make the GitHub repo demo-ready: no dead main.py, documented env vars, accurate spec, visual proof in README.

Instructions

• Delete main.py — it is entirely commented-out CLI code; your entry point is Flask (app.py)
• Create .env.example at repo root (committed, empty values):

OPENAI_API_KEY=

• Rewrite README.md: project title, one paragraph on what it does, How to run with exact commands:

uv sync
uv run flask --app app run --debug

Mention: open http://127.0.0.1:5000, need OPENAI_API_KEY in .env (not committed). Link to project.spec.md / project.journal.md.

• Add a screenshot: create docs/ folder, add docs/screenshot.png (or .jpg) of the app at phone width — reference it in README with a relative markdown image
• Update project.spec.md: fix typo "Planenr" → "Planner"; rewrite Must have (MVP) to match reality — mobile-friendly Flask app, goal + location, curated workouts from JSON, memory for last two focus groups, goal-weighted selection (once Phase 1 is done), last-workout history (Phase 2), input validation, Tailwind. Move "web app at the end" out of stretch if you've shipped it

Hints

Commit message idea:

checkpoint 3: wire select_group_and_workouts + history UI, polish README

Optional — get help from your agent:

Draft README.md for my GPT Workout Planner: uv sync, uv run flask,
.env for OPENAI_API_KEY, link docs/screenshot.png. I'll paste my
real screenshot path after.

Phase 5: Checkpoint 3 journal + Demo Day plan

Handwrite.

Objective

Align project.journal.md with what you built and lock a 2–5 minute demo outline.

Instructions

• Fill Checkpoint 3 in project.journal.md: what you did (Phases 1–4), what you wrote yourself vs. agent-assisted, one thing you're proud of (e.g. goal-weighting finally live), one thing you'd do next (e.g. BMI from original stretch list)
• Add a Demo Day plan (bullets OK): one-sentence pitch → live walk (home → submit goal → result → back) → mention last-workout panel → close with "proud of" + "next week"

Hints

Demo flow that shows off your work:

1. Reset or note workouts/history.json if you want a clean "first visit"
2. Submit "build muscle" + gym — show plan + focus on screen
3. Return home — last workout appears in <details>
4. Submit "lose weight" — show different vibe / focus bias over a couple runs

Phase 6 (Bonus): Deploy to Render

Only after Phases 1–5 work locally. Skip if time is short.

Objective

Public URL for Demo Day; same pattern as other class guides.

Instructions

• Read the full Render Deploy Guide
• Run uv add gunicorn so the production server is listed in pyproject.toml and uv.lock
• Add render.yaml with sync: false for OPENAI_API_KEY
• Commit pyproject.toml, uv.lock, and render.yaml
• In Render dashboard, set env vars; test live URL end-to-end
• Caveat: free tier disk resets on deploy — workouts/history.json may reset; fine for demo — submit a fresh plan before presenting

Hints

render.yaml sketch:

services:
  - type: web
    name: gpt-workout-planner
    env: python
    plan: free
    buildCommand: uv sync --frozen && uv cache prune --ci
    startCommand: uv run gunicorn app:app
    autoDeploy: true
    envVars:
      - key: OPENAI_API_KEY
        sync: false

Optional — get help from your agent:

My Render deploy builds but crashes on start. Here's my render.yaml
and startCommand. What's wrong?

Checkpoint 3 Readiness

By Friday, May 1st at 3:30pm (Demo Day):

• /generate uses select_group_and_workouts — no duplicate focus-group persistence in app.py
• save_workout runs after each successful plan; / shows last_workout when present
• Form submit shows loading/disabled state (Phase 3)
• main.py deleted; .env.example committed; .env still gitignored
• README.md: real title, paragraph, run commands, env vars, screenshot in docs/
• project.spec.md MVP matches the shipped app
• Checkpoint 3 + demo plan filled in project.journal.md
• Everything committed and pushed
• (Bonus) Live Render URL + note about history file on redeploy

Helpful Resources

• Checkpoint 3 Instructions
• Render Deploy Guide
• Tailwind CSS — utility reference
• Flask — Application setup