BoroughBook.UK: Hammersmith & Fulham
An independent, open view of a London borough's money and promises, built for residents. Live as a public alpha at https://boroughbook.uk: your council tax bill by band, the council's budget, how this year's gap was closed, a tool to balance next year, 18 manifesto pledges from both parties with their status, your ward and its councillors (find it by postcode), and every payment over £500 the council publishes. Every figure links to its source. Not run by or affiliated with the council.
Corrections, and replies from anyone named on a promise card: [email protected]. Made by Pavel Guzhikov. Separate project from LedgerGov.UK (the national version), sharing its ideas and later its code. Called Borough Ledger until 8 Oct 2026; the code packages and Vercel project keep that name. The repo is xternal/boroughbook.uk since 20 Oct 2026 (xternal/boroughbook.uk before; the old address redirects).
Where things stand and what is still open: docs/PRE_SHIP_REVIEW.md. The reference prototype in prototype/ still runs on test data; the site does not.
1. The idea
Your council tax bill is the only statement most residents ever get from their council, and it says almost nothing. BoroughBook.UK turns it into a readable account:
- Your bill (
/bill). Pick your band, see what you pay, how much goes to the council and how much to the Mayor of London, and what your share pays for.
- The budget (
/budget). Where the council's money comes from (council tax, business rates, government grants, reserves) and what it pays for.
- The gap (
/gap). Each year costs rise faster than funding. One chart shows what opened the gap and how it was closed: council tax, savings, reserves.
- Balance it (
/balance). Next year's gap, with the real levers a council has. Residents see the trade-offs councillors face, including the 4.99% referendum limit and the one-off nature of reserves.
- Promises (
/promises, each card at /promise/<id>). Every pledge from the administration and the opposition, costed per Band D home, with a timeline that ends in delivery or in silence.
- Payments over £500 (
/payments). The council's monthly transparency files, searchable.
- Make your case. Who decides (the law, the government or the council), how the council compares, and a letter to councillors in the reader's own words, never seen or sent by the site.
- The council tax decoder (boroughbook.uk/council-tax). Every one of England's 296 councils that send bills: a postcode in, the Band D bill out, split between the council, the county council or the Mayor of London, police, fire, combined authorities and parish councils, with the change on last year.
2. Why a borough, and why this one
- People feel it. Bins, parking, potholes, care for parents and council tax are more personal than national debt.
- The data is standardised. Every English council publishes payments over £500 under the Local Government Transparency Code and files the same revenue returns with central government. A product built for one borough can be switched on for others.
- The council is a clean test. Labour has run H&F since 2014 and held it in May 2026 with Stephen Cowan as leader, so the 2026 manifesto runs to 2030. The opposition has its own pledges to cost.
- There's a hook. In 2010 the council said it wanted to be "Britain's most transparent council".
3. What is different from the national version
| National (LedgerGov.UK) | Borough (this project) |
|---|
| The gap | Borrowed, adds to debt | Must be closed every year by law. Failure means a section 114 notice |
| Visual of the gap | Hatched borrowing flow | Waterfall: pressures → gap → council tax, savings, reserves |
| Who controls the levers | Government (and Bank of England) | Council controls council tax (capped), fees, savings, reserves. Government controls most funding |
| Your share | Income tax and NI | Council tax by band, with single person discount |
| Promise cost unit | £ per household | £ per Band D home and % of the council's budget |
| Opposition pledges | Costed | Costed and marked "Opposition pledge": cannot be delivered from opposition |
| Extra modules | Demography, macro | Payments over £500, ward view, council decisions, the building programme and council homes, more boroughs |
4. MVP
In:
- Your bill, budget flow, gap waterfall for the current year, sourced from the budget report and government returns.
- Balance-it for next year with a 3-year medium-term view, so reserves visibly come back as a gap.
- Promise ledger: both parties' 2026 manifestos, costed, with timelines. Free home care as the first fully sourced card.
- Payments over £500 explorer from the monthly files, with service mapping and a redaction filter.
- Follow (RSS, email) and Contribute (send a leaflet photo, a link or evidence), no accounts.
- Methodology and sources page. Every figure labelled sourced, approx or test.
Out for v1: ward view (postcode → ward, councillors, local spend), council decisions tracker, other boroughs, accounts.
5. Roadmap
| Stage | Time | Result |
|---|
| M0 | 3 days | App scaffold, prototype ported, engine tests |
| M1 | 1 week | Real budget data: budget report tables, government revenue returns, council tax, settlement |
| M2 | 3 days | Balance-it with 3-year view and shareable scenarios |
| M3 | 1 week | Promise ledger with both manifestos and councillor pages |
| M4 | 4 days | Payments explorer on real monthly files, supplier pages, redaction rules |
| M5 | 4 days | Follow and Contribute (leaflet photos) |
| M6 | 4 days | Ward view: postcode lookup, councillors, ward promises, local reports |
| M7 | 4 days | Council decisions tracker from committee papers, linked to promises |
| M8 | 3 days | Second borough from the government returns alone |
Estimates are low-confidence until M0 is done.
6. Risks in one place
- Looking like the council. No council logo, colours or wording that suggests it is official. "Independent" on every page.
- Local election rules. Rules on third-party spending in local elections are tight. Get advice before the run-up to May 2030.
- Personal data in payments files. Some payments go to individuals (foster carers, direct-payment recipients, sole traders). Councils redact them; we must never re-identify them.
- Being "the resident scoring the council". One standard for both parties, right of reply, evidence for every status.
- Overlap with LedgerGov.UK's political backers. Separate brand, separate entity, funding disclosed.
7. What is in the pack
| File | For | What |
|---|
HANDOVER_PROMPT.md | Claude Code, designer | The kick-off prompts to paste or send |
CLAUDE.md | Claude Code | Rules, stack, invariants |
docs/PRE_SHIP_REVIEW.md | Everyone | What must change before public launch |
docs/PRD.md | Product, engineering | Users, features, acceptance criteria |
docs/DATA_MODEL.md | Engineering | Schemas |
docs/MODEL.md | Engineering | Council finance rules and the balance-it engine |
docs/DATA_SOURCES.md | Engineering | Where every dataset comes from |
docs/PROMISE_STANDARD.md | Editors | How local pledges become cards |
docs/PRIVACY.md | Product, legal | Personal data, follow, contribute |
docs/DESIGN_HANDOFF.md | Designer | Screens, components, tokens |
docs/BUILD_PLAN.md | Claude Code | Milestones with prompts |
docs/SHARED_CORE.md | Engineering | What to share with LedgerGov.UK, and when |
docs/BOROUGHS.md | Engineering, owner | Adding boroughs: what each gets first, what adding Kensington and Chelsea found, the address decision, and a first run of the checks across all 32 |
data/seed/*.json | All | Prototype data, mostly test |
prototype/ | Design, engineering | Clickable prototype; index.html is built by build_prototype.py |
8. Running it
Node 22 (.nvmrc) and pnpm (version pinned in package.json).
pnpm install
pnpm dev # http://localhost:3000, test data allowed and marked
pnpm test # schema, engine and web tests
pnpm typecheck
pnpm build:preview # production build that may render test data, each value underlined in red, noindex
pnpm build:prod # fails while any rendered value has quality "test"
pnpm --filter @borough-ledger/schema report:test-values # every test value still in the data
pnpm --filter @borough-ledger/schema content:build # compile content/ (promises, councillors) into data/build
python3 etl/councillors.py # refresh councillors and wards from the council's ModernGov service
python3 etl/ward_map.py # ward boundaries from the ONS, drawn as SVG for /wards and each ward page
python3 etl/capital_wards.py --draft # new building schemes into data/manual/capital_scheme_wards.csv, located for review
python3 etl/capital_wards.py # building schemes by ward into data/build/ward_spend.json
python3 etl/decisions.py # Cabinet and Full Council decisions from the council's ModernGov web service
pnpm --filter @borough-ledger/schema decisions:suggest out.json # ask Claude about decisions not yet assessed (needs ANTHROPIC_API_KEY)
pnpm --filter @borough-ledger/schema decisions:apply out.json # add suggested links and events to content/ (for a pull request)
pnpm --filter @borough-ledger/schema digest out.md [YYYY-MM-DD] # the weekly digest draft (Claude with ANTHROPIC_API_KEY, else a plain version)
python3 etl/payments.py --fetch # spend files: download archived ones, record hash, rows and total of new ones
python3 etl/payments.py --draft-map # add new service areas to data/manual/payments_service_map.csv for review
python3 etl/payments.py # build data/build/payments (redacted, mapped, reconciled to each file)
| Path | What |
|---|
apps/web | Next.js app. Every number renders through <Num>, which carries its quality and blocks test values in build:prod |
packages/schema | Zod schemas for data/seed and data/config/rules.json, cross-checks, quality helpers |
packages/engine | Bill, budget identity, waterfall, balance-it and costing. Pure functions with Vitest tests |
etl/payments.py | The council's quarterly spend files: privacy rules (docs/PRIVACY.md), service mapping, a JSON file per month and per-supplier totals in data/build/payments/, reconciled to every file |
content/ | Promise cards, parties, councillors and wards in YAML, edited by pull request; see content/README.md |
data/config/rules.json | Band ratios, single person discount, balanced budget rule, referendum limit, instalments, each with its legal source |
Vercel: set the build command to pnpm --filter @borough-ledger/web vercel-build. Production deployments run build:prod; previews run build:preview. NEXT_PUBLIC_SITE_URL on production is the site's own address (https://boroughbook.uk): it sets canonical links, the sitemap and feeds, and when it names a host other than borough-ledger.vercel.app every request to that old address is redirected to it (next.config.ts). NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION is optional: Search Console can verify the whole domain with a DNS record instead.
Page views. apps/web/proxy.ts counts how often each of the site's reading pages is opened, one number per page per UTC day (boroughbook:views:<date> → path → count) in Upstash Redis, after the page is sent, and stores nothing about the reader (apps/web/lib/views.ts; docs/PRIVACY.md "Page views"). The totals are public at /views.json (the last 30 days, the same format as LedgerGov.UK's and RussiaLedger.com's, cached ten minutes) and on /most-read. To switch it on, connect a free Upstash Redis database to the Vercel project (Storage, Upstash, Redis, Production only); Vercel then sets KV_REST_API_URL, KV_REST_API_TOKEN and KV_REST_API_READ_ONLY_TOKEN; redeploy. Without them (previews, laptops) nothing is counted and /most-read says so. Check after the deploy: open a page in a browser, wait ten minutes, and curl -s https://boroughbook.uk/views.json lists it under today's UTC date.
Search and AI search. Every page has its title, description, canonical link, share image and structured data; pledges also have a Markdown version at /promise/<id>.md, and /llms.txt and /llms-full.txt describe the whole site for AI tools. After each production deploy, scripts/indexnow.mjs tells search engines which pages changed (.github/workflows/indexnow.yml).
Alpha. The public site at https://boroughbook.uk is the Alpha: a production build (no test values, open to search engines and AI crawlers, with llms.txt and a sitemap), marked "Alpha" next to the name (STAGE in apps/web/lib/site.ts). Every merge to main deploys it. Switches in "Balance it" whose cost is still a test value are held back by etl/build.py and named on the page as coming later (next_year.pending_toggles); they return once their cost is sourced. Pull request previews stay behind Vercel login.
9. Licence
Code: MIT (LICENSE). Our own text and data tables: CC BY 4.0, credit "BoroughBook.UK (Pavel Guzhikov)". Council, government, ONS and Democracy Club data keep their own licences, and manifesto quotes are not relicensed: see LICENSE-CONTENT.md.
