luisgonc.

← blog ·  July 31, 2026  ·  5 min read

Your utility bills are a dataset

Portinhola is a self-hosted dashboard for Portuguese household utilities. It reads the bills, pulls the 15-minute meter data from E-Redes, and replays my real consumption against every tariff to find out what switching actually saves.

$ bloat--level 3▰▰▰▱▱Bloatin'

0 words at this level · written by AI, throttled by you

Every invoice issued in Portugal carries a QR code in the corner. It is mandated by law, it is printed on everything from a coffee receipt to an electricity bill, and it holds the issuer’s tax number, the date, the totals and the full VAT breakdown. Machine readable, standardized, sitting right there. Nobody scans it.

Mine were rotting in email. Three electricity suppliers in four years, because switching is how you get the good price, and every switch resets your history to zero. The old portal stops working, the PDFs stay behind in some folder, and the one question that actually matters, “am I on the right tariff for how this house actually uses energy”, gets answered by a comparison site asking me to guess my monthly spend.

So I built Portinhola. The name means “little door”, and that is the pitch: your utility data comes home through it, and nothing goes out.

The dashboard: cost history, contract facts, yearly totals

It is a self-hosted dashboard for Portuguese household utilities, electricity, gas and water. FastAPI and SQLite on the back, SvelteKit on the front, one container, one data folder. It runs on a Raspberry Pi class machine at home. AGPL, on GitHub.

The bills come out of the drawer

Upload a PDF and Portinhola decodes that fiscal QR for the totals and VAT, then a per-supplier extractor parses the line items: energy by period, standing charges, the levies, meter readings, contract details. I dug 77 bills out of years of email archives across four suppliers (EDP, Iberdrola, G9 and the local water company), and that pile of PDFs became a continuous cost history of the house, surviving every supplier switch that originally fragmented it.

The extractors are the part I most want other people to steal. Each supplier’s PDF layout is its own small puzzle, the contributing guide shows how to write one from an anonymized fixture, and once an extractor exists, everyone with that supplier gets line-level history for free.

The meter knows more than the bills do

E-Redes, the national distribution operator, records every meter in the country at 15-minute resolution, and you can see your own curve in their portal. Getting it out of the portal is the annoying part. Portinhola does it honestly: you log in, in your own browser, copy the session token and paste it in. No embedded browser, no captcha games. The token only lives about 91 minutes, so there is no unattended daily sync, and that is a deliberate trade. It syncs history in 31-day windows, saving each one as it lands, so an interrupted run resumes instead of starting over.

Four years of my house came through that little door: around 131 thousand intervals. That curve is where the interesting answers live.

Replay, don’t estimate

This is why the project exists.

The switch calculator, with the first-year promo toggle

Every tariff comparator has the same weakness: it estimates from a monthly total. But whether bi-horário beats simples depends entirely on when you use energy, and that is exactly the information a monthly total destroys. Portinhola has the real curve, so it does not estimate anything. It replays your actual consumption, interval by interval, through each tariff’s full price sheet: energy per period, the daily standing charge, every levy, VAT per component. Calibrated against my latest real bill, it reproduces it within cents, which is what lets me trust the rest of the ranking.

What it told me about my own house:

  • The regulated gas tariff wins, by a lot. The boring, default, state-regulated gas price beats my market-rate plan by about 260 euros a year. Nobody advertises that one.
  • My electricity plan was fine all along. Within about 30 euros a year of the best offer on the market. Years of vague “should I switch?” anxiety, answered.
  • My contracted power is not oversized, it is undersized. Real 15-minute peak: 4.82 kW, against 4.6 kVA contracted. The common advice is that everyone over-contracts. Not this house.

About 290 euros a year, found by paperwork. It also prices promotional phases properly: a “minus 15% for the first year” offer gets a separate first-year total next to the steady-state one, so a plan that is cheap for twelve months and expensive forever after cannot hide.

Wrong prices are worse than no prices

The first tariff seeds came from price comparison sites, and they were wrong. Not subtly wrong: the daily standing charges were roughly half the real value, consistently, across suppliers. A calculator built on those numbers is a machine for confident bad advice.

So the data got rules. Every tariff file carries the official source URL and a retrieval date. The loader refuses any standing charge below the regulated network access floor, because a price below what the supplier itself pays for the wire cannot be real. And a weekly GitHub workflow re-parses the suppliers’ official price sheets and opens a pull request when a number moves. The prices are data, and data you cannot audit is rumor.

Why it never phones home

There are services that will do some of this if you forward them your bills. Think about what a utility bill is: your name, your address, your tax number, your bank reference, and a running log of when you are home. A centralized service holding that for thousands of households is one acquisition away from being a data broker, and you have no way to check.

Portinhola’s answer is structural, not a promise: it runs on your hardware, the data lives in one SQLite file you can back up by copying a folder, and there is no telemetry, no account, no cloud calls and no LLM anywhere in it. The code is open precisely so you do not have to take my word for any of that.

The dashboard on a phone

Try it

docker compose up and a browser is the whole install; the README covers the rest. All screenshots here are generated demo data, for the obvious reason.

If your supplier is not covered, that is the fun part: extractors and tariff seeds are designed to be contributed by the people who actually receive those bills. Bring your drawer of PDFs.