W04: Your First App from the Starter

New cooks do not invent a kitchen. They walk into one that already works: the stove is lit, the knives are in the drawer, the fridge is labelled. Their first job is to cook one dish in it and learn where everything lives. The starter is that kitchen. It is a small notes app that already runs, already has tests that pass, and already follows every rule of the stack. You and Pi change it, piece by piece, into your app.

Make Your Copy

The starter lives in the Pi Workbench project, in kit/starter/. A small script copies it into a new folder and adds the pinned libraries (htmx and Basecoat) beside it. In a terminal, from the folder where you downloaded pi-local-harness:

python3 kit/new_project.py ~/Projects/notes

The folder must be new or empty. Then go into it and install what it needs, once:

cd ~/Projects/notes
uv sync

uv reads pyproject.toml, the list of what the project needs, and installs it into a private .venv folder (T45 explains uv).

Run It

Two commands: one builds the styles, one starts the server.

TAILWINDCSS_VERSION=v4.3.3 uv run tailwindcss -i styles/input.css -o static/app.css --minify
uv run uvicorn app.main:app --reload

Open http://127.0.0.1:8000. Add a note. Delete it. Click 日本語 and the page switches to Japanese. Stop the server with Ctrl+C.

Now run the checks:

uv run pytest
uv run pyright

pytest runs the tests. pyright checks the types (W09). Both should pass before you change anything. That is your baseline.

Give It to Pi

In the workbench, choose Add Existing Folder… and pick ~/Projects/notes. Open it. In the Plan section you will see "No roadmap or tasks in this folder" and a Create Roadmap button. Click it: it adds ROADMAP.md and tasks/001-first-task.md, nothing else. The harness needs those two to keep its paperwork.

The folder is already a git repository: kit/new_project.py made it and saved a first commit, "Start from the Pi Workbench starter", so the harness can commit verified work from the very first request (W11 explains this). Check with git log --oneline.

Pi Workbench will do this step for you soon: New Project… will offer a "Web app" kind that makes all of this in one click, and a Preview beside the chat will run the app and the styles for you, so you can watch each change appear.

A Walk Through the Folders

notes/
  app/
    main.py          the routes: which address shows what
    db.py            the data: open the database, one function per question
    i18n.py          the two languages: t("key")
    logic/
      notes.py       the rules, as pure functions
    templates/
      base.html      the frame every page shares
      pages/         whole pages
      fragments/     pieces htmx swaps into a page
  migrations/
    001-notes.sql    the database's shape, one numbered step at a time
  messages/
    en.json          every visible word, in English
    ja.json          the same keys, in Japanese
  static/            files sent as they are: htmx, the built CSS, the icon, the PWA files
  styles/input.css   the Tailwind and Basecoat entry point
  tests/             test_app.py, test_logic.py, test_i18n.py
  pyproject.toml     what the project needs

The big idea is that each kind of thing has one home:

This is why the app stays maintainable. You, Pi, or another person can open it in a year and know where to look.

Follow One Note

Here is what happens when you type "buy milk" and click Add Note:

sequenceDiagram participant B as Browser + htmx participant M as app/main.py participant L as app/logic/notes.py participant D as app/db.py B->>M: POST /notes (title=buy milk) M->>L: check_title("buy milk") L->>M: ("buy milk", no problems) M->>D: add_note(...) D->>M: the new Note M->>B: the form again + the new note (a fragment)

The route in main.py is short on purpose. It asks the logic whether the title is fine, asks the database to save it, and renders a fragment. Each piece does one thing. The next lessons open each piece in turn.

Your First Request

Back in the workbench chat, try a small, safe change:

"Change the app's name from Notes to My Notes, in English and Japanese (マイメモ)."

Watch the "Pi sees:" line, wait for the answer, then open the task file (W03). Restart the server and reload the page to see it. If it says "Not verified", read why. Here the likely reason is that the tests pass without the change too: nothing tests the name yet. The fix is a follow-up request: "Add a test that checks the page title says My Notes."

This Week's Exercise

  1. Make your copy of the starter, run it, and run uv run pytest and uv run pyright.
  2. Add the folder to the workbench, click Create Roadmap, and look at the first commit with git log --oneline.
  3. Open each file in app/ once. For each, write one sentence: what is it for?
  4. Send the "My Notes" request, then read its task file and its commit with git log --oneline.

Key Takeaways

  • Pi never starts from nothing: kit/new_project.py copies the starter, a working notes app with tests
  • uv sync installs; Tailwind builds the CSS; uv run uvicorn app.main:app --reload runs it on port 8000
  • uv run pytest and uv run pyright must pass before you change anything
  • In the workbench: Add Existing Folder…, then Create Roadmap; the repository and its first commit come with the starter
  • Each kind of thing has one home: routes in main.py, rules in logic/, data in db.py and migrations/, words in messages/