Week 1.
Orientation, setup, and
understanding the system.
Quick check: where is everyone starting from?
No wrong answers. This helps us calibrate pairing and pacing.
Git / version control
Have you used git before? Branches? Pull requests?
Python / web dev
Comfortable with Python? Ever built or worked on a web app?
LLMs / AI tools
Used ChatGPT, Copilot, Claude? For coding specifically?
Team codebases
Ever worked on code someone else wrote? Reviewed a PR?
Raise your hand for each: never used it / used it a little / use it regularly
What the project does,
why it matters,
how it's built.
Three parts. Every week. For six weeks.
-
01
Group session — about two hoursShort lesson plus a demo of a new LLM workflow pattern, then guided work on assigned issues with scaffolded guides.
-
02
Solo work — async, later in the weekYou apply the week's pattern independently. This is where the real learning happens. We give you a hunting ground; you choose what to work on.
-
03
PR (pull request) review and issue creation — asyncReview each other's pull requests. File issues for anything you discover. Issues are the heartbeat of this team — and starting today, you own the backlog.
This is FEAST. Let's look at it live.
What you're seeing
A map of Brown County, WI (Green Bay area). Each colored dot is a household. Each shape is a store. Colors show food access scores.
Try it right now
Open the URL on your laptop. Click a household to see its data. Click "Step" to run one simulation tick. Watch the colors change.
What you'll build locally
By the end of today's setup, you'll have this same app running on your machine, connected to your own database.
Improve FEAST to make it more usable, flexible, and performant — using modern tooling.
Understanding
the system.
Food access:
the problem.
Not just “is there a store nearby.”
Food access is the ability of a household to regularly obtain adequate, affordable, nutritious food. Four factors determine whether they can.
How far to a store?
Supermarkets and convenience stores count very differently — proximity to the right kind of store is what matters.
How do they get there?
A vehicle, a bus route, or just walking distance — each one expands or restricts the set of reachable stores.
Can they afford the trip?
Lower-income households make fewer trips, and tend to use the closest store regardless of what it stocks.
What's actually for sale?
A supermarket with fresh produce isn't the same as a convenience store with packaged food. Quality drives the score.
Low food access correlates with poor diet, higher rates of obesity and diabetes, and other health outcomes.
It disproportionately affects low-income communities and communities of color. Better tools for measuring access make it easier for cities, public health researchers, and community organizations to do their work.
Real questions, asked by real cities, every year.
Should we subsidize a new grocery store in this neighborhood?
Tax break, zoning change, public-private partnership — what's the modeled lift in access scores?
What happens if this Walmart closes?
A chain pulls out of a low-income area. Which households are most affected, and where should a replacement go?
Where should we add public transit?
A bus route connecting one neighborhood to a distant supermarket — does it close the access gap for carless households?
How does a farmers' market change the area?
A seasonal store, smaller footprint, different shopping patterns — what's the modeled effect on its surroundings?
Five audiences. One tool.
Urban planners
Evaluating proposed grocery store locations or transit improvements.
Public health
Studying the link between food access and health outcomes across demographics.
Policy analysts
Modeling the impact of store closures and policy interventions.
Community orgs
Advocating for food access improvements with data-driven arguments.
Students & researchers
Learning about spatial modeling, food systems, and agent-based simulation.
Agent-based
modeling: the
approach.
Many simple agents → complex emergent behavior.
Instead of one big equation describing food access for a whole city, we create thousands of household agents that each independently figure out where to shop. Four properties define an ABM:
Every agent is different
Each household has its own income, location, vehicles, workers — captures real-world diversity instead of an average.
Agents only see what's near them
No agent has a global view. Global patterns emerge from many local decisions made independently.
Time advances in discrete ticks
Every step, each agent re-evaluates its situation. You can model change over six months, a year, a decade.
Worlds are easy to swap
Add or remove a store, re-run from the same state, compare outcomes. The whole point of the technique.
Two kinds of agents. That's it.
From Census data
Income, household size, vehicles, number of workers, geographic location inside a census tract. Pulled from the US Census API.
From OpenStreetMap
A food store — supermarket, convenience, grocery, butcher. Each has a type, name, and location. Pulled from OSM via the Overpass API.
What every household does, every step.
-
01
Calculate distance to every storeA distance map keyed by store ID, computed once per step.
-
02
Identify the closest supermarket and the closest non-supermarketTwo reference stores — one for "best quality nearby," one for "easiest stop."
-
03
Decide where to shop this monthTrip count depends on has_resources(): 7 with income+vehicle, 8 with income but no vehicle, 6 without resources. Income thresholds vary by household size ($10k/single, $15k/2-person, $25k/3+).
-
04
Compute MFAI score and pick a colorAverage of the trip scores. Red if low, green if high — that's what the map renders next.
MFAI: a weighted average of monthly trips.
From Koh et al., 2019. The arithmetic is intentionally simple — most of the interesting behavior is upstream, in which store the household actually picks.
Fresh produce, broad selection, full grocery — high food availability.
Smaller footprint, more packaged food — limited food availability.
Minimal selection, emergency use. Low-income households may prioritize these. bc_pantries branch only.
Varies by resources: 7 with car & income, 8 without car, 6 with low income.
Same neighborhood. Different access.
Mesa: Python's ABM library.
You don't need deep Mesa knowledge to contribute. The key idea: when GeoModel.step() runs, it calls Household.step() on every household — that's where all the food access math happens.
Holds the agents, runs steps
FEAST extends this as GeoModel.
Defines per-agent behavior
Household and Store both extend Mesa's GeoAgent.
Spatial operations
From mesa-geo. Distance calculations between agents on a map.
Scheduler
Calls step() on every agent in random order each tick.
This is what the agents look like, on a map.
High access score. Reaching supermarkets often.
Mid-range. Mixed trips, partial supermarket access.
Low access. Mostly convenience stops; few supermarket trips.
Click to inspect. Drag in new ones to test what-if.
An ICICLE project, built for any US county.
FEAST originated through the NSF-funded ICICLE AI Institute (OAC 2112606).
The current implementation is focused on Brown County, Wisconsin as a proof of concept. The goal is to make it work for any US county — that generalization is one of the larger arcs in the backlog you'll be working from.
How the three
layers fit
together.
Frontend → Backend → Database.
Frontend
- Leaflet map
- User controls
- Score visualization
- Add / remove stores
Backend
- API routes
- Mesa ABM model
- MFAI calculation
- Census + OSM pipeline
Database
- simulation_instances
- households
- food_stores
- one row per step
When you're debugging, ask first: which layer? Map not rendering — frontend. Score wrong — backend. Data missing — database. That single question cuts debugging time in half.
Frontend — React app, Leaflet map.
What it does
- Renders household markers, colored by access score (clustered at low zoom, individual at zoom 17+)
- Renders store markers — hexagons for supermarkets, triangles for convenience stores
- Add stores (click map), multi-select and remove (Ctrl/Cmd+click)
- API base URL hardcoded in src/shared/client.js — not an env var
- Deployed via Docker (multi-stage Node build + Nginx) separately from backend
Where it lives
- ICICLE-ai/FASS-Frontend / fass-react/
- Branch: Brown-County-Frontend
- React 19 · Vite · Leaflet · Axios · Bootstrap + Tailwind (legacy mix)
- State: React Context API + window globals (anti-pattern, on backlog)
- MapComponent.js (526 lines) — raw DOM, not declarative react-leaflet
Backend — FastAPI plus Mesa.
What it does
- Serves the REST API under /api/
- Holds the Mesa GeoModel and runs simulation steps via multiprocessing
- Preprocessing pipeline pulls Census data + OSM store locations
- Currently hardcoded to Brown County, FIPS 55009
- A default_simulation instance is protected from deletion — base dataset for new runs
Where it lives
- ICICLE-ai/Food-Access-Model/, branch minimum_viable_product
- Entry: food_access_model/main.py via run_local.py
- Three entry points exist — use run_local.py only. api_server.py and server.py are legacy.
- abm/household.py · abm/geo_model.py · preprocessing/get_data.py
- FastAPI · Mesa + mesa-geo 0.8.0 · asyncpg · shapely · osmnx
PostgreSQL — three tables, one row per step.
One row per run
Name, ID, timestamps. The "outer container" for everything else.
One row per household per step
Location, income, household_size, vehicles, workers, transit/walk/bike/drive times, food_score, stores_within_1_mile, closest_store_miles.
One row per store per step
store_id, name, shop type, geometry (WKT), simulation_instance, simulation_step.
Coordinate gotcha — mixed CRS across tables
Household coordinates are stored in EPSG:4326 (lat/lon). Store geometries are in EPSG:3857 (Web Mercator, meters). This inconsistency means different coordinate handling per table, and the frontend uses proj4 to reproject stores for display. On the backlog as #67.
When a user clicks "Step" — what actually happens.
That whole loop, end to end, is the product. Student D will trace this in detail. Every PR you write touches some piece of it.
Three files that keep a project on track.
Project context
What the project is, how to work in it, what conventions to follow. Read by humans and AI agents.
What's done, what's next
A living document. Milestones, dependencies, critical path. Updated after each milestone, not written once and forgotten.
Why we chose what we chose
Architecture Decision Records. Document the reasoning, not just the result. You'll start writing these in Week 2.
This curriculum repo (FEAST_edu) uses all three. We practice what we teach.
How we
work.
You understand the system. Now: agentic coding tools, the rules for working with them, getting the app running, and your first assignments.
Agentic coding
tools: the
landscape.
You must be able to explain every line in your PR without looking at your chat history.
Write code for future you.
What makes a tool an agent?
Your focus shifts.
Without agents
With agentic engineering
The agent handles syntax. You handle engineering. This curriculum teaches the right column.
Know the landscape, not just one tool.
CLI agents
Run in your terminal, read the whole codebase, execute commands. Conversational interface.
AI-native IDEs
Full editors with AI in every interaction. Code completion, inline chat, multi-file editing.
Inline assistants
Plugins for VS Code, JetBrains. Autocomplete and inline suggestions. Lightest-weight.
We recommend a CLI agent because its conversational interface matches how we want you to work: asking questions, not accepting autocomplete. Claude Code is our first choice if access is available; Gemini CLI is a free alternative. Both use project context files that double as documentation.
One file,
two
audiences.
FEAST is a food access simulation
tool. Backend: FastAPI + Mesa ABM.
Frontend: React + Leaflet.
# Code Style
- Always use type hints
- Use flake8, ignore E501
- Use descriptive names
# Git Workflow
- main is stable; dev is integration
- Feature branches off dev
Demo: same question, with and without a context file
Reading first.
Generating
later.
A freshman who learns to generate code in week 1 will never learn to read code. We build the muscle of reading and thinking first. Generation comes later, when you can spot when the tool is wrong.
"Write me a function that does X."
Skips learning. You ship code you don't understand. Review fails.
"Walk me through what this function does and why."
Accelerates learning. You understand what you ship. Review passes.
"Is this the simplest way? What could I remove?"
Use the tool to push toward clarity. Simpler code is almost always better code.
Your tools are installed. Use them to ask questions.
- "What does this function do and why?"
- "Walk me through this control flow."
- "What does this error message mean?"
- "Why is this written with async?"
- "Explain this Mesa concept to me."
- Compare responses across tools
- Code generation of any kind
- Writing tests for you
- "Fix this bug for me"
- Generating commit messages
- Writing your endpoint trace
We unlock more capability week by week. By week 6 you'll have full access. The restriction is the point: you're building the skill of reading code first. The tool will still be there when you're ready.
Setup —
get it running.
Git: your time machine for code.
Git tracks every change to every file. You can always go back. When multiple people work on the same project, git keeps everyone's changes organized.
Repository
Your project folder, tracked by git. Contains every file and the full history of changes. You have a local copy; GitHub holds the remote copy.
Commit
A snapshot of your files at a moment in time. Each commit has a message describing what changed. Like a save point you can return to.
Branch
A named line of development. FEAST uses main (stable), dev (integration), and feature branches (your work). You work on your branch without affecting anyone else.
Five commands. That's all you need today.
Download a repo from GitHub to your machine.
Once, during setup.
Switch to a different branch.
When moving between branches.
Stage your changes, then save a snapshot with a message.
After you make changes.
Upload your commits to GitHub so the team can see them.
After committing.
Your "where am I?" command. Shows branch, changed files, staged files.
Constantly. When in doubt, git status.
Six things on your machine.
Python
3.11 or later.
Node + npm
Node 18 or later.
PostgreSQL
Local instance, or shared.
Git + GitHub
SSH key set up, repo access granted.
uv
Python package manager.
CLI agent
Claude Code (preferred), Gemini CLI (free), or Copilot as baseline.
Don't sweat order. Get one machine working per pair.
Clone both repos
git clone ICICLE-ai/FASS-Frontend
Backend env
git checkout minimum_viable_product
cp .env.example .env
uv sync
Agentic tool
# or install Gemini CLI / Copilot
# verify it works, then exit
Run backend
# port 8000, NOT api_server.py
Frontend env
git checkout Brown-County-Frontend
npm install
# edit src/shared/client.js:3
# baseURL → localhost:8000/api
Run frontend
# open localhost:5173
Senior students: if you solve something non-obvious during setup, write it down. Those notes become part of CONTRIBUTING.md in a couple of weeks.
A Leaflet map. Colored households. Clickable stores.
curl localhost:8000/api/simulation-instances returns a JSON list. Health: /api/health
Map loads at localhost:5173 centered on Brown County (Green Bay area).
Click a household — popup with income, vehicles, score. Click Step — colors change. Add a store — Step again — nearby scores improve.
Common problems, and what they actually mean.
Connection refused
Is PostgreSQL running? Are your .env credentials correct? Is backend on port 8000 (run_local.py)? Make sure client.js matches.
No data in the DB
You may need to run the preprocessing pipeline or restore a database dump. Use insert_stores.py with a CSV for stores.
Wrong entry point
food_access_model/main.py allows localhost:5173. If you used api_server.py by accident, it only allows a Tapis staging URL.
Wrong branch
Make sure you're on minimum_viable_product (backend) and Brown-County-Frontend (frontend). The main branch has different code.
Today's work,
and what you
do solo.
Use the app before you read the code.
Understanding what the tool does is a prerequisite to understanding how it works. Don't skip this.
-
01
Create a simulation instanceThrough the UI if it supports it, or via curl. Look at the request and response.
-
02
Click on households. Read the popup data.Income, vehicles, MFAI score, stores within 1 mile, closest store distance. Match it to the concepts we just covered.
-
03
Click "Step" — watch the colors changeThe full lifecycle runs behind that button: frontend to backend to Mesa to DB and back.
-
04
Add a store near red households. Step. Scores improve?Then remove a store. Step. What happens? This is the what-if loop in action.
Each of you traces one endpoint through the full stack.
| Student | Endpoint | What to focus on |
|---|---|---|
| Student AJ | GET /simulation-instances | Simplest endpoint. How does a request become a SQL query become a JSON response? |
| Student BJ | GET /households | How is household data structured? What do the column names mean? |
| Student CJ/S | POST /stores | How does a lat/lon become a polygon? What's the coordinate transform doing? |
| Student DS | POST /sim-instances/{id}/advance | The core simulation loop. How does one "Step" actually work end to end? |
| Student ES | POST /simulation-instances | What happens when you create a new simulation? Where does the data come from? |
Two deliverables. One PR.
Reviewed by a peer before the Week 2 session. Write for future you.
When the frontend calls this endpoint,
routes.py:98 handles the request. It
opens a connection from the asyncpg
pool and runs the query defined in...
[3-5 paragraphs total]
Explore. Create.
File issues.
Build the backlog.
Explore the parts you didn't trace.
Read the frontend
Match what you see in the browser to what's in the code.
- — Which component renders the map?
- — Which one handles "Add Store"?
- — Where do household colors come from?
- — Start with App.jsx, follow the imports.
Read household.py carefully
Especially get_mfai(), has_resources(), step().
- — What do 95, 55, 0.8 mean?
- — What about 10000, 15000, 25000?
- — Then read get_data.py.
- — How does Census data become synthetic households?
Use the LLM to explain things you don't understand — but verify against the actual code. The LLM can be confidently wrong.
Create a project context file in your FEAST repo.
Use the template in FEAST_edu/templates/CLAUDE.md as a starting point. Name it for your tool: CLAUDE.md, GEMINI.md, or .cursorrules. Customize it based on what you learned from the architecture overview and your endpoint trace.
Keep it under 50 lines. You'll update it as you learn more. This is your first project management artifact.
Open a PR for it alongside your endpoint trace.
- What does this project do?
- How do I run it locally?
- What conventions should I follow?
- What are the key files to know about?
What should an improved FEAST look like?
Not a redesign from scratch. The same app, built the way a professional team would build it today. Then work backwards: what are the biggest gaps, and in what order should a team close them?
Investigation areas (pick by tier):
Use the template:
templates/vision-plan-template.md
Your plan covers:
- — The end state: what does good look like?
- — Gaps: current state vs. target, per area
- — Sequence: what to fix first and why
- — Open questions: what you couldn't figure out
Turn everything you noticed into a GitHub issue.
This is not busywork. This is how the team builds a real backlog. By week 3 you'll be triaging it. By week 5 you'll be shaping it.
A good issue includes:
- — A clear, specific title
- — What you observed (quote the code)
- — Where it is (file + line number)
- — Why it's a problem
- — Optionally: what the fix might be
- — A type label: bug, enhancement, or refactor
- — An area label: area:frontend-state, area:backend-entry-points, etc.
from repository.db_repository ...
routes.py:
from food_access_model.repository...
Things you'll probably find. File them.
Inconsistent imports
Package-relative in one file, shorthand in another.
CORS hardcoded
Tapis URL, not relevant locally. Should be env-driven.
Python version drift
pyproject.toml says 3.11.11. Dockerfile says 3.12.
profiling import missing
Imported in api_server.py but the module doesn't exist.
print() instead of logging
Multiple files. Should use the standard logging module.
Magic numbers in household.py
95, 55, 0.8, income thresholds. No constants, no docstring.
Deprecated on_event
FastAPI moved to lifespan handlers. routes.py still uses startup events.
Raw DOM in MapComponent
Bypasses React, hard to debug, fights re-render cycle.
Bootstrap + Tailwind
Two CSS frameworks. Pick one. (Probably Tailwind.)
Stretch goals, and how seniors help juniors.
Find it. File it. Fix it.
Found something fixable in 30 minutes — the CORS hardcoding, a print-to-logging conversion?
Open a PR. Link it to the issue. That's your first taste of the full cycle.
Walk a junior through one file.
If a J student is struggling to spot issues, sit with them over chat or a call.
Point things out. The junior files the issue — they need the practice. You help them see what to look for.
Next session, we compare your vision plans.
-
01
Silent read (5 min)Read one other student's plan. Mark: something you also identified, something you missed, something you'd sequence differently.
-
02
Round-robin (8 min)Each student shares: #1 priority, one thing from the reviewed plan you missed, one sequencing disagreement.
-
03
Converge (2 min)"Everyone noticed" items anchor the team's shared priorities.
What success looks like — six weeks from now.
Linting + CI pipeline
Type hints across
First test suite
3-layer review pipeline
Store-counting bug fix
Optimized step function
Better MFAI algorithm
Reporting API + metrics
Cleaner logging
Input validation + CORS
Documented decisions
Issues you'll file this week
That's a lot. We get there one week at a time. The foundation is what we build today.
Questions —
then setup.
Bring laptops to the front so we can debug together. Anything that's confusing now will come up later — better to ask now.