One page load, end to end

Let's trace exactly what happens when a signed-in user opens the log page. Everything else in this book hangs off this one journey; if you internalize it, no file in the repo will ever feel mysterious.

The journey of GET /log

browser                      server (one Docker container)
   │
   │ 1. HTTPS request ──────▶  reverse proxy (Caddy, or Render's LB)
   │    GET /log                  │  terminates TLS, adds X-Forwarded-* headers
   │    Cookie: session=…         ▼
   │                           gunicorn: 1 worker process, 8 threads
   │                              │  speaks WSGI to the app
   │                              ▼
   │                           Flask routes the path → log_page() in app.py
   │                              │  @approved_required reads the users table
   │                              │  render_template('log.html', …) fills in Jinja
   │ 2. HTML response ◀──────     ▼  → one big HTML string
   │
   │ 3. parses HTML → builds the DOM tree
   │ 4. applies the CSS in <style> → paints the page shell
   │ 5. runs the <script> blocks
   │      │
   │      │ 6. fetch('/api/meals?days=7&anchor=…') ──▶ same path as step 1,
   │      │                                             but returns JSON
   │      ▼ 7. JSON ◀─────────────────────────────────  from DynamoDB queries
   │ 8. JavaScript builds meal cards out of the JSON and
   │    inserts them into the DOM — now you see your meals

Two round trips, two kinds of response. The first returns HTML: the page's structure, styling, and code, rendered on the server with everything the server already knows (who you are, which nutrient you track, whether AI is configured). The second returns JSON: pure data, which JavaScript running in the browser turns into visible elements.

Three languages, one page

The browser natively runs exactly three languages, and they have strictly separated jobs:

Language	Job	Chapter
HTML	Structure and meaning — "there is a form here, with a text area and a save button"	HTML
CSS	Appearance and layout — "cards have rounded corners; in light mode the background is cream"	CSS
JavaScript	Behavior — "when the save button is clicked, POST the form to /api/meals and reload the list"	JavaScript

There is a fourth language in this repo that never reaches the browser: Jinja, the server-side template language that generates the HTML (the Jinja chapter). View the source of any page (Ctrl+U) and you will find no Jinja in it — only its output.

Where everything lives

File	Layer	What's in it
app.py	backend	Every route (URL → Python function). The table of contents of the whole app.
config.py	backend	Environment loading, constants, the nutrient catalog, the fiber guide.
auth.py	backend	Google OAuth, session → user resolution, the access guards.
db.py	backend	All DynamoDB and S3 access, plus the photo cache.
ai.py, autolog.py	backend	OpenAI estimators; the async photo pipeline (the capstone chapter).
templates/base.html	both	The shared page skin: theme tokens, menu, the blocks pages fill in.
templates/log.html etc.	frontend	One template per page: its HTML, its page-specific CSS, its JavaScript.
tests/	both	Plain-script stub tests that run the real app against fakes — no AWS, no network.

Notice what is absent: no JavaScript framework (React, Vue), no build step, no node_modules, no CSS preprocessor, no bundler. Each page's CSS and JS live inside its template. That is a deliberate choice at this scale — the entire frontend toolchain is a text editor, and "view source" in the browser shows you the truth.

Server-rendered shell + JSON data

Web apps sit on a spectrum. At one end, classic server rendering: every click reloads a full page, forms POST and the server responds with new HTML. At the other, the single-page app (SPA): the server serves one near-empty HTML file plus a megabyte of JavaScript that renders everything and talks JSON from then on.

Ndiro deliberately sits in the middle. The server renders each page's static shell — headers, the form, anything derived from config or identity — and JavaScript fetches only the dynamic data (meals) as JSON. You get fast first paint and simple code, without a framework. Watch for the seam as you read templates/log.html: everything inside {{ … }} was decided on the server at render time; everything built by document.createElement was decided in the browser afterwards.