● xodhiambo.com · nairobi · UTC+3 v.2026.08
xavier@nairobi:~$ cat projects/kandili/README.md

Kandili: know about a planned power cut before the lights go

What it is

Kenya Power announces planned power cuts days ahead, in PDF notices on its website, and most people still find out when the fridge goes quiet. Kandili reads those notices, matches the places they list to the estates people follow, and sends an alert on Telegram or by email when a cut is announced, a reminder at 06:30 on the day, and a busy block in their calendar. It's free, and independent of Kenya Power: every alert links the notice it came from.

Shape

One FastAPI app serves the landing and outage pages, the Telegram webhook, the calendar feeds and the admin. A Procrastinate worker, with its queue in the same Postgres, does everything on a clock: the hourly poll of Kenya Power's notices page from 06:00 to 22:00, parsing, a sweep that sends pending alerts every minute, and the morning reminders.

kplc.co.ke   notices page, robots.txt respected, each PDF fetched once
     |
     v
  worker  Procrastinate   PDF text -> parse -> validate
     |                    \
     | valid               doubtful --> admin review
     v
 Postgres 16   notices · outages · places · subscriptions · alerts · jobs
     |
     | match outages to followed places, sweep pending alerts
     v
  channels   Telegram · email (Resend) · ICS calendar feeds

Reading a notice without guessing

A weekly notice is an A3 page laid out in two columns. Plain text extraction reads straight across the page and interleaves them, which attaches places to the wrong area without failing any check. So each page is read as two columns when no word crosses the middle, read whole when words cross but no AREA or DATE line starts in the right half, and refused as a changed layout otherwise. Region and county headings carry over from one column and page to the next.

The notices are typed by hand, and it shows: AREA;, AREAS:, four ways to punctuate a time, and a place list that starts with "Area," and isn't a header. The parser accepts the variants it has seen. What it won't do is publish anything doubtful. An outage is held for review if its date doesn't exist, its weekday doesn't match its date, it starts after it ends, or it has no area or no places.

Across the eight notices on the site in October 2026, 346 outages were parsed and five were held. All five were mistakes in the notices themselves: two had the wrong weekday ("Wednesday 11.10.2026" is a Sunday), two had a date with no area, and one had an area with no readable date. Held outages go to a review queue in the admin, with the raw text and a link to the PDF, and the admin gets a Telegram message for each notice that needs a look.

Sending each alert at most once

A duplicate alert is worse than a missed one, so a send is claimed before anything reaches Telegram: one UPDATE … WHERE status = 'pending', committed first. A retried or duplicated job finds nothing to claim.

What came backThenWhy
connection failed, 429, token rejectedretry with backoff, or after Telegram's retry_afterTelegram certainly didn't get the message
read timeout, 5xxfailed, "may have been delivered"the message may already be on the phone
bot blocked, chat deletedfailed, channel switched offthe person's next message switches it back on

Nothing goes out between 22:00 and 06:00. The sweep queues nothing then, and the send checks the clock again, because a retry can come due at night. Alerts held overnight go out with the first sweep after 06:00.

Calendar feeds that update in place

Each person gets a private ICS feed, keyed by a 256-bit token, and every place has a public one. An event's UID comes from the outage and the place, so when Kenya Power revises a notice, calendars replace the event instead of adding a second. The feed asks for hourly refreshes. Apple Calendar honours that; Google Calendar refreshes every 12 to 24 hours whatever the feed says, so a notice posted late can miss the calendar but not the Telegram alert.

Deploys that can't take the site down

Every merge to main runs CI, builds the image, pushes it to GHCR tagged with the commit, and deploys it with Dokku's git:from-image. Migrations run in the release phase while the old containers are still serving, and each one waits at most five seconds for a table lock. A migration that would queue behind live traffic fails the deploy instead, and the old containers keep serving.