Sunlight, on the device

In-app, a sunlight is what we call a notification. A leaf catching sunlight first — somebody replied to one of your nodes, somebody proposed a stage move, a personal forest has new activity.

This week sunlight extended to the device. When the app is closed, the same events reach you the same way — quietly, only the things that matter to you, with a tap that lands you exactly where the thing is.

Why we waited

Push is a thing you can’t take back. Ship it too early and you train people to mute you before they’ve decided whether to listen. The in-app sunlight had to mean something first, so the out-of-app version could inherit the same calibration.

What a sunlight says, and doesn’t

A handle, a verb, and where. Marina replied. Acorn proposed Friend. A new root in the forest you care about. The shape on the lock screen is the shape on the Sunlight tab.

What it doesn’t say: no previews of content you’d rather not have on a lock screen, no nagging, no “X people are talking about Y”.

The first prompt

The OS prompt for push is a one-shot — if you say no, you have to dig through settings to undo it. So the Sunlight tab asks first, in our voice, with our framing. If you say yes there, we ask the OS. If you say no, we don’t.

Tech notes

Push delivery has two cost surfaces — the per-notification vendor fee, and the operational cost of running a queue at scale. The path here is direct to the OS-level providers: FCM (Firebase Cloud Messaging) for Android, APNs (Apple Push Notification service) for iOS. Most React Native apps route through an intermediary like Expo’s Push Service or OneSignal, which is convenient but adds a per-push charge at scale. The OS-level APIs themselves are free; the cost is in operating the queue that hands work off to them. This is one of the choices Designing for the day this works was about — keeping per-message-priced services off the critical path so the unit economics still work at a hundred thousand users.

Both providers authenticate with short-lived JWTs the server signs from a private key. Naïvely, every push pays for a key-signing step plus a token-exchange HTTP request before the actual send — three round-trips for one notification. The steady-state cost is reduced to one HTTP call by caching the access token in memory and refreshing it a few minutes before expiry (FCM tokens are valid for an hour; APNs JWTs up to 60 minutes per Apple’s docs). HTTP/2 multiplexing handles parallel sends on one connection — FCM v1 has no multicast, so a fan-out to N devices is N requests, but they share one socket.

The queue is a transactional outbox in Postgres. When the server inserts a sunlight row, it inserts a row into the push-dispatch outbox in the same database transaction. If the transaction rolls back, the push never fires; if it commits, dispatch is guaranteed eventually. The alternative — calling FCM directly inside the request handler — couples the request’s latency to a third-party API and loses durability when the network hiccups.

After each commit, a Postgres LISTEN / NOTIFY channel wakes the dispatch worker in ≤ a few milliseconds. This is Postgres’ built-in pub/sub primitive: any session can issue NOTIFY <channel>, and sessions that have run LISTEN <channel> receive the wake-up. To survive missed notifications — a worker reconnecting, a network split — the worker also runs a 60-second backstop poll. Steady state is push-driven; the poll exists for correctness.

Worker claims use SELECT … FOR UPDATE SKIP LOCKED — Postgres’ standard idiom for safe concurrent queue dequeue. Multiple worker processes can run in parallel with no extra coordination layer; each claims a disjoint set of rows. Each claim also takes a five-minute lease, so if a worker crashes mid-dispatch the row becomes re-claimable once the lease expires. Bounded batch size keeps viral fan-outs (one root in a forest with ten thousand members → ten thousand outbox rows) from materialising as a single monster query; the worker drains in cycles until the claim returns empty.

V1 constraints. The outbox table accumulates “sent” rows forever — no archival job runs yet; that’s a known sweep to add before the table outgrows its partial index. There’s no dead-letter queue: permanently failed rows are marked and left in place for inspection. The database is still a single primary; workers scale horizontally (running more of them is the easy axis), but writes contend on the same instance. Read replicas would help the sunlight-read path, not the outbox write path. Sufficient for private beta and into early growth; needs revisiting before broad public release.