Snapshot · · catch-up for anyone who has been away

CURRENT
PROGRESS

The map is demoable. The API is live. Persistence is the work in flight.

Two repos, two hosts. The site is static on GitHub Pages. The API is FastAPI on Cloud Run in London, version 0.1.3, building again on Python 3.13 pack. They only meet when the browser fetches window.HACKATHON_API. Noah is wiring that API to Firestore. Next product slices still live on the map: a job list, a demo seed, and saving routes in the browser.

Open the map → Kanban Architecture Ping the API Get running
API Cloud Run · snapshot 0.1.3
Site Pages · hackathon.tyneside.software
Map Waypoints + OSRM · ready to demo
Persistence Noah · Firestore in progress

Sixty seconds

Read this first

If you only have a minute, this is the whole picture.

  1. 01
    Two repos, two hosts. hackathon-site is HTML on GitHub Pages. hackathon-api is FastAPI on Cloud Run. Clone them as siblings. .\start.ps1 starts both.
  2. 02
    The map does not call our API. Leaflet + OSM tiles + public OSRM, with a straight-line fallback. You can demo routing tonight even if Cloud Run is quiet.
  3. 03
    Cloud Run builds again. GitHub → Cloud Run uses buildpacks (pack on ubuntu2404), not the Dockerfile. Pinning Python 3.12 failed the build. Pin is 3.13. Live health is 0.1.3.
  4. 04
    Noah is on persistence. Card 31: the API should write a field to Firestore/Datastore and read it back. /health must stay cheap if the database is down. Card 11 (persist routes) waits on this.
  5. 05
    Next product is still the map. Job list (Connor), demo seed (Reeve), localStorage routes (Lewis), then a display name. That is the show-and-tell path while Firestore lands.
  6. 06
    New JavaScript is Alpine.js 3. CDN, defer, no npm. This page pings /health that way. Docs live at /docs/. Board source of truth is scripts/cards.json, not hand-edited HTML.

Board, distilled

Now, next, later

The kanban has the briefs. This is the order that matters if you just walked in.

Ready + product

Next

Demo the map, then fill it

04 · 🧭 Reeve · Ready Clickable / draggable waypoints Live on app/. Polish and a teammate can add two pins without a briefing. 05 · ⚡ Connor · Ready Route calculation OSRM driving, haversine fallback. Sidebar shows distance, time, and engine. 07 · ⚡ Connor Job list beside the map Five Howden-shaped seed jobs. Click a job, something visible happens. 08 · 🧭 Reeve Demo seed: five Tyneside stops One button loads a named run so nobody clicks the map five times in a demo. 06 · 🌱 Lewis Save routes in localStorage Refresh must not wipe a demo. Fallback until the API can persist.

The room

Who is on what

Hours are the board totals. Focus is what to pick up tonight.

🔧 Noah 6 hrs Firestore · card 31 3 done · 1 in progress. Machine is up. This is the persistence path. 🧭 Reeve 8.75 hrs Map polish · demo seed 4 done · 1 ready · 2 to do. Waypoints are live; seed is the demo unlock. ⚡ Connor 6.75 hrs Routing polish · job list 3 done · 1 ready · 1 to do. OSRM works; jobs make it look like dispatch. 🌱 Lewis 8.75 hrs localStorage · who-am-I · local API 4 done · 3 to do. Front end loop is done. Persistence in the browser is next. 🏗️ Michael 15.25 hrs Persist routes after 31 6 done · 1 to do. Cloud Run, wiki, Alpine test, 3.13 pin. Card 11 waits on Noah.

While you were away

What already shipped

20 cards · 22.25h on Done. Do not redo these.

  1. 3 September · card 30

    Cloud Run builds on Python 3.13 pack

    ubuntu2404 has 3.13 and 3.14 only. A 3.12 pin failed Cloud Build. Root main.py, Procfile, and .python-version 3.13 make pack succeed. Live /health reports 0.1.3.

  2. 3 September · card 29

    Docs wiki, including architecture

    Docs is in the nav. Markdown in docs/, sidebar from pages.json, Alpine + marked. If you do not know how the two repos fit, open Architecture.

  3. 3 September · card 28

    Alpine API test page

    api-test.html calls GET /test_field on Cloud Run. First Alpine island. New UI behaviour goes here, not React/Vue/npm.

  4. Cards 22 · 23 · 25

    Noah’s machine, then VERSION

    Front end and local API are up. VERSION is on / and /health. He moved from onboarding onto Firestore.

  5. Cards 26 · 10

    Push to main deploys both sides

    Site → GitHub Pages. API → Cloud Run. .\start.ps1 is still the local path. Cloud Run CORS allows the live origin and localhost:5500.

  6. Cards 04 · 05 · onboarding loops

    Map + routing are demoable

    Click to pin, drag to move, calculate a driving route. GitHub loops and local FE/BE are done for Reeve, Connor, Michael, Noah; Lewis still has local API on the to-do list.

How it is wired

The stack in one glance

The two hosts never import each other. The browser is the join.

hackathon-site

GitHub Pages

Static HTML, styles.css, Alpine, Leaflet. Live at hackathon.tyneside.software. Local: :5500.

  • Home, this page, map, board, wiki
  • config.js sets window.HACKATHON_API
  • Map talks to OSM + public OSRM only

hackathon-api

Cloud Run · europe-west2

FastAPI + Uvicorn. Live health 0.1.3. Local: :8080. Buildpacks, not the Dockerfile, on GitHub CD.

  • GET / · /health · /test_field
  • POST /create_field (Firestore work)
  • Python 3.13 · do not pin 3.12

Do not spend the session on these

  • Do not pin Python 3.12 for pack — ubuntu2404 cannot resolve it.
  • Do not open HTML as file:// — the browser will block the API and the wiki.
  • Do not hand-edit <!-- BOARD:… --> HTML. Change scripts/cards.json and run python scripts/update_board.py.
  • Do not import the Datastore/Firestore client at module top on Cloud Run — lazy import or 503.
  • Do not wait for the API to demo the map. OSRM is public; our API is not in that path.

Your next hour

Pick up from here

Choose a length. Then open the matching surface — do not start a third plan.

Ten minutes

See it working

Open the map, drop two pins, calculate a route. Hit API test and confirm JSON comes back. Skim architecture if the two-repo split is fuzzy.

Thirty minutes

Cold machine

Follow onboarding: clone both repos as siblings, run .\start.ps1, pull main. Home, map, and board must load on http://127.0.0.1:5500/. Then take a to-do card with your name on it.

A session

Ship a slice

Noah: Firestore round-trip on the live API. Reeve: demo seed. Connor: job list. Lewis: localStorage or local /health. Michael: persist routes only after 31 is green. Push origin/main — that deploys.

Map → Board → To do → Done → Docs → API test → Onboarding → Site repo → API repo →