Architecture
Three small services that sleep until someone needs them.
Dangerous weather is rare. On an ordinary day Kuc-kuc has nothing to do, so it runs nothing: every part is on Cloud Run with a minimum of zero instances. When a call has to be made, the parts wake up, hand the work to each other through a queue and a topic, and go back to sleep.
The picture
This page describes what is deployed right now, nothing more.
No service calls another service directly. Whatever happens is published as an event; whatever has to happen later is a task with a time on it.
One check, step by step
- The forecast crosses a threshold.
Every three hours Cloud Scheduler starts
forecast-scan, a Cloud Run job. It groups the people under watch into cells of about 10 km, asks Open-Meteo for 48 hours of forecast per cell, and publishesalert.createdwhen heat, frost, wind or snow crosses its line. The same alert is never created twice. - The engine decides.
Pub/Sub pushes every event to
engine. All decisions live in one pure function,step(episode, event), which returns the episode as it is now plus a list of things to do. It has no clock and touches nothing outside itself, so every rule of the service is a unit test. - A call is queued, not made.
The engine writes a call record to Firestore and puts a task in the Cloud Tasks queue
calls. The queue releases at most one new call per second, whatever the backlog. - The phone rings.
Cloud Tasks calls
voicewith an identity token. Before dialling,voicesynthesises every sentence the call might need with a Chirp 3 HD voice and stores the audio in Cloud Storage, so the person never waits in silence while speech is being made. Then it asks Twilio to dial. - A few seconds of answer. The greeting plays, up to 8 seconds are recorded, and the recording goes to Gemini on Vertex AI: audio in, a small JSON object out (is a live person speaking, what did they mean, what did they say). The recording is deleted at the phone company at once and kept in our bucket for 7 days.
- What happens next is another event.
voicepublishescall.completed. “I am fine” closes the episode. No answer becomes a task ten minutes in the future, at most three times. Anything else starts the neighbour chain, and the question “how is she?” twenty minutes later is, again, just a task with a time on it. - The family hears at every step. The engine sends a Telegram message when an alert is created, after every call, when a neighbour is sent, and at the end. Urgent ones say so in the first word.
The parts
webCloud Run service, public- This site and the demo API. It verifies a visitor's phone number, enforces the demo's limits, publishes one event, and serves the live timeline. It never dials.
engineCloud Run service, private- The state machine. Internal ingress only: Pub/Sub and Cloud Tasks can reach it, the internet cannot.
It reads an event, runs
stepinside a Firestore transaction, then queues calls and sends notices. voiceCloud Run service, reachable by the phone company- The only code that touches telephony. Every webhook is checked against Twilio's signature; the request that starts a call must carry a Google identity token from our own queue. It is the one place that holds the phone credentials.
forecast-scanCloud Run job- Runs for a few seconds every three hours, started by Cloud Scheduler, and exits.
watchdogCloud Run job- Every ten minutes, a few seconds long. Any message or timer can be lost on the way; a check that has stopped moving is closed and the family is told at once, instead of waiting in silence for a neighbour nobody called.
loadtestCloud Run job- Creates thousands of simulated people in a heatwave and lets the real engine and the real queues handle them, with telephony replaced by a simulation. Its numbers are below.
- Pub/Sub topic
events - Everything that happens:
check.requested,call.completed,call.blocked,alert.created. Delivery can repeat, so each episode remembers the events it has already handled and each call can be completed only once. - Cloud Tasks queues
calls,timers - Every wait in the system. “Call again in 10 minutes” and “ask the neighbour in 20” are tasks, not sleeping processes. This is what lets every service scale to zero in the middle of an escalation.
- Firestore
- People, episodes, calls and the timeline. Demo data carries an expiry and deletes itself after 24 hours.
- Cloud Storage
- Synthesised speech, cached by content, and recorded answers, deleted after 7 days by a lifecycle rule.
- Vertex AI and Text-to-Speech
- Gemini listens to the recorded answer; a Chirp 3 HD voice speaks, in Serbian or English.
- Secret Manager
- Phone credentials. Each service has its own service account and can read only the secrets its code uses.
Why scale to zero matters here
A service like this is needed on perhaps eight days a year per person. If it cost money on the other 357, nobody's family could keep it running. So the design rule was: nothing may need to stay awake.
- Waiting is stored, not held. A retry or a follow-up is a Cloud Tasks task with a delivery time. The service that will handle it can be at zero instances until that moment.
- State lives in Firestore, never in memory. Any instance can pick up any step.
- Cold starts are paid where nobody is listening. Starting a call from zero takes about twelve seconds, and all of it happens before the phone rings. Once someone has picked up, the slowest step, understanding their answer, takes about three seconds.
- The queue protects the phone line. However many alerts arrive at once, calls leave at a fixed, gentle rate.
What keeps it safe
- One rule above the others: any doubt counts as a problem. Silence, a recorded message, a failed download, a model error or a confused answer is “unclear”, and unclear sends someone to the door. It is never “fine”.
- At most 6 calls a day to any one person, checked before the first call of a check; an escalation that has started is never cut off by it. One switch stops all new calls. Whenever a real call is blocked, the family gets an urgent message.
- A watchdog every ten minutes: a check that has stopped moving is closed and the family hears about it at once. A message that did not reach the family is shown as not delivered.
- The demo only calls a number its owner has just verified, in four countries, a few times a day, within a daily budget in dollars. Its limits never block a call to a real person.
- Phone numbers never appear in logs, on public pages or in the repository.
- It is not an emergency service, and says so wherever it speaks.
What it costs
| Item | Cost |
|---|---|
| Google Cloud on a quiet day | about nothing: zero instances |
| One phone number | about $1.15 a month |
| A call to a landline in Serbia | $0.60 a minute |
| One dangerous day for one person | about $1.20; about $1.60 more if a neighbour is called |
| One person for a year, about 8 such days | $10 to $15 |
| One run of this demo | about 9 cents |
Telephony is nearly the whole bill. A local carrier would cut it several times over; that is for later.
Right now
- Calls today
- 0
- Calls so far
- 7
- People under watch
- 1
Under load
The latest load test simulated 2000 people in a heatwave at once. The engine and the queues handled 3008 simulated calls and closed every episode in 213 seconds, at a peak of 14 instances. Then everything went back to zero.