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.

How the parts of Kuc-kuc are connected Three Cloud Run services, web, voice and engine, talk to each other only through a Pub/Sub topic and Cloud Tasks queues. Voice is the only one that reaches the phone network. Cloud Run · every box scales to zero Pub/Sub · topic “events” Browser visitor trying the demo Twilio phone calls and recordings Telegram messages to the family Open-Meteo weather forecast web public · site and demo voice talks to the phone network Cloud Tasks · calls, timers engine private · one state machine forecast-scan job · every 3 h, Cloud Scheduler loadtest job · thousands of simulated calls Vertex AI · Text-to-Speech Gemini understands, Chirp 3 HD speaks Firestore · Cloud Storage state and audio, used by every service HTTPS calls notices forecast check.requested call.completed every event, pushed alert.created check.requested × n audio → JSON

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

  1. 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 publishes alert.created when heat, frost, wind or snow crosses its line. The same alert is never created twice.
  2. 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.
  3. 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.
  4. The phone rings. Cloud Tasks calls voice with an identity token. Before dialling, voice synthesises 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.
  5. 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.
  6. What happens next is another event. voice publishes call.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.
  7. 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

web Cloud 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.
engine Cloud 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 step inside a Firestore transaction, then queues calls and sends notices.
voice Cloud 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-scan Cloud Run job
Runs for a few seconds every three hours, started by Cloud Scheduler, and exits.
watchdog Cloud 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.
loadtest Cloud 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.

What keeps it safe

What it costs

ItemCost
Google Cloud on a quiet dayabout nothing: zero instances
One phone numberabout $1.15 a month
A call to a landline in Serbia$0.60 a minute
One dangerous day for one personabout $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 demoabout 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.

Try it on your phone