Under the Hood

Cue is a lightweight app for getting a group of friends to agree. Events settle when: someone proposes a few times, friends reply however they like — “Wednesday works, but I’d prefer Thursday” — and Gemini reads the replies and keeps proposing the best time. Decisions settle what: where to travel, what to name the band. Chats carry the conversation in between.

Behind that simple idea sits a monorepo of ten modules in four languages, running on personal servers that reach the internet through Cloudflare Tunnels. No Kubernetes. No GitHub Actions. No cloud functions. Just Docker containers, a load balancer, and a Fish script.

Around the three pillars sits everything a group needs: Trips that gather events and decisions into one timed arc, Cue Notes for markdown the group writes together live, standalone channels and 1:1 direct messages whose links open into cards, a per-user library of photos, short videos and files that doubles as chat attachments and event covers, AI weather reports and commentary, push notifications, home-screen widgets, calendar sync, and one search engine that reaches all of it from a ⌘K palette. Every piece shares one backend and one deploy pipeline, and everything but the live typing in a note rides one SSE channel.

If you read Norwegian, there’s a companion piece about the personal journey of building Cue: the Cue story.

Everything lives in one monorepo. That was deliberate: the AI agent sees the whole system when a change crosses a boundary, and the documentation, deploy scripts, and configuration sit next to the code they describe.

Alongside them sits one piece of tooling, cue-static-users: a small Kotlin CLI that keeps the fixed-code test accounts that agents and scripts sign in with.

Each module is written in the language that fits its domain. No universal compromise — the right tool for each job.

On top of that: about 2,200 lines of SQL across 99 Flyway migrations, about 200 lines of Fish and 900 of bash for deploys, and a handful of YAML and TOML files for Docker Compose and GoReleaser. The original scheduler is now a small fraction of the codebase; chat, direct messages, channels, decisions, Trips, Cue Notes, the media library, and the five native apps account for most of it.

Every request comes in through one of two doors. Browsers load getcue.net, served by the Next.js front-end, which proxies its /api/* calls onward; the native apps and the CLI call api.getcue.net directly. Both hostnames arrive through the same Cloudflare Tunnel and meet at an nginx load balancer in front of two backend replicas.

nginx round-robins the two cue-core replicas and retries the other one when a request fails, so either can restart without anyone noticing. SSE connections get a 24-hour read timeout, so a stream stays open for as long as the app does, and the notes WebSocket gets a location of its own that carries the upgrade. Media never passes through the application server: reads are 302-redirected to a 15-minute presigned R2 URL, and large video uploads go directly to R2, bypassing the load balancer’s body limit entirely.

Eight containers run under Docker Compose, plus one external store for media. Only the load balancer and the two web apps publish ports, and those bind to localhost for the tunnel alone — there is no other way in.

Cue has to feel instant. When someone responds to an event, everyone else should see it immediately — on the web, on iOS, Android, and macOS, and in the CLI. Instead of polling, Cue uses Server-Sent Events: a simple, HTTP-native protocol for one-way streaming. The one thing that needs traffic both ways — typing into a shared note — gets a WebSocket of its own, and leaves this channel untouched.

How it works

The client opens one long-lived HTTP connection to /api/sse/stream, and the server pushes an event down it whenever something changes. That’s all there is to it.

Signal-based, not payload-based

This is the key design choice. An SSE event in Cue is a signal, not a payload: it names what changed and nothing more. The client then refetches through the normal REST API, so authorization lives in exactly one place — the REST controllers — and the SSE layer stays paper-thin.

Multi-instance broadcasting

With two replicas behind the load balancer, a signal produced on one has to reach clients connected to the other. So every signal goes through a Valkey pub/sub channel: each replica subscribes, and each pushes what it hears to its own connected clients.

Transactional safety

Signals go out only after the database transaction commits, through Spring’s TransactionSynchronization.afterCommit(). If a transaction rolls back, no signal is ever sent: no phantom updates, and no clients refetching data that doesn’t exist.

Heartbeats and reconnection

The server sends a heartbeat every 20 seconds, which keeps connections alive through the tunnel and flushes out dead ones. When a connection drops, the client reconnects with exponential backoff. The stream carries no history, so after a reconnect the client simply refetches what it’s showing. A 401 stops the retry loop instead of hammering the server: the client refreshes its session and resubscribes, or, if the session is truly gone, asks the user to sign in again.

One channel, many signal types

Everything real-time in Cue but note editing rides this one channel. The wire format is uniform — a named SSE event plus a tiny JSON body identifying what changed — so adding a signal type needs no change to the broadcaster: the service names it when it publishes. The signal types, grouped by domain:

AI isn’t only a development tool for Cue — it’s part of the product. The backend talks to Gemini through Google’s Vertex AI in nine distinct places.

In production every text call runs on Gemini 3.8 Flash — the suggested time, the AI comments, the weather read, the Trip Brief, the whole decision brain (recommendation, Option Insights, and commentary), the live chat participants, the option brainstormer that seeds a new decision, Clean up, the photo descriptions, the digests that read a shared file once, and the cover’s art director. The text work splits into two profiles, each its own model, thinking level and time limit: the analytical profile thinks at a medium level, while the chat profile, where someone is waiting on the answer, thinks at a low one and gives up after twelve seconds. A third, the image profile, names no model of its own: the person’s painter picks it — Nano Banana 2.1 by default, or Nano Banana Pro for the finest detail. Every call goes through one gateway that routes it, checks the answer — a feature that wants structure hands the model a schema to fill — and meters it. Each event, decision or trip has at most one call per feature in flight: a burst of edits collapses into one trailing run, and unchanged inputs cost nothing. The dev server runs the faster Gemini 3.5 Flash-Lite behind the same two text profiles and Gemini 3.1 Flash-Lite Image behind both painters, so its test suite stays quick while production keeps the stronger models.

All but one share one shape: a service publishes a Spring ApplicationEvent once its transaction commits, an @Async listener calls Gemini, and the result reaches every connected client over SSE. Independent entities, listeners, signal types, and rate-limit checks — one feature can never block another. Clean up is the exception: a person asks, and the proposal comes back in the response, private to them until they accept it. A photo’s description starts the same way but sends no signal: it waits on its row for the next read. A cover is a session of steps — read, direct, paint — each run once the request that asked for it commits, and signalled to its requester alone.

The user sees their write saved instantly; moments later the AI’s answer arrives over SSE, with no refresh. Every AI call is logged with its token counts, latency and cost, priced from a dated catalog of each model’s rates, and the admin dashboard tracks daily, weekly, and monthly Gemini spend against configurable caps — no single user can burn through the month’s budget.

Chat is a full messaging surface with five kinds of conversation: the live chat on an event, a 1:1 direct message, a standalone channel, the chat a decision grows, and a trip’s own room. The hub at /chat lists all five together, sorted by activity, with an unread badge per conversation and a total in the top navigation.

The hub is two-pane — the conversation rail on the left, the selected thread on the right — and collapses to list-and-detail navigation on mobile. Conversation IDs are opaque (event-{id}, dm-{otherUserId}, channel-{id}, decision-{id}, trip-{id}), which keeps routing forward-compatible: the web client never assumes their shape beyond passing them to the API, and a client that doesn’t recognize a kind simply drops that row.

What every conversation has

Channels: a room of its own

Channels are standalone group chats — #oslo, #fotball — not tied to any event. They reuse everything above (composer, reactions, read cursors, typing, edits, media) and add what a public room needs: membership, roles, and visibility.

• Three visibility tiers — public (anyone can find it in the directory and join), private (listed, but joining takes an approved request), and secret (invite-only, hidden from the directory).
• Roles — owner, admin, member. A partial unique index enforces exactly one owner per channel, so a room can never end up ownerless, or stage a quiet coup.
• Join requests & blocks — private channels gate entry behind a request an admin approves. Removing someone records a block in a side table, which keeps the check out of the hot fan-out path instead of smearing a “was removed” condition across every query.
• Human-only — unlike event and decision chats, channels don’t take AI participants.

AI participants in event & decision chats

Any invitee can add an AI to an event or decision chat (up to five per room), choosing a name — or accepting a random one — a free-form personality, and an interaction mode:

• proactive — reads every new message and decides whether to respond.
• mention_only — speaks only when it’s named.
• event_driven — reacts to state changes: a new response, the organizer finalizing, and so on.

An @-mention makes the named AI weigh in, whatever its mode. An AI can be removed by the person who added it or by the organizer; it then leaves the participant strip and stops responding, but its past messages stay, attributed to it by name, so the history still reads correctly.

Data model & limits

Each kind runs on its own family of tables, all cut to the same shape: messages, a read cursor, and reactions.

Posting is capped by an in-memory sliding window — a ConcurrentHashMap of timestamp deques per (conversation, user), pruned on a timer. The Valkey Lua limiter described later guards the HTTP-level limits — OTPs, per-user writes, uploads, IP ceilings — not message posting.

Every URL in a message is tappable on the web, iOS and Android, in all five kinds of conversation, and the first link in a person’s message gets a lean card: a thumbnail, a title, and the domain you will actually land on, after every redirect. cue-core finds the links and ships them on each message as UTF-16 spans, so no client guesses what a link is. A link to Cue itself — an event, decision, trip, channel, note, profile or invite — gets a Cue card instead, drawn from what the viewer may see.

It is not an embed system: no inline players, no iframes, no third-party scripts. The server fetches, once, for everyone. A reader’s device never contacts the linked site, so no IP address or read time reaches a tracker, every client draws the same snapshot, and every image comes from Cue’s own URL with its size known before the row renders.

One fetcher, hardened

A link preview is the textbook server-side request forgery: someone names a URL, and the server fetches it. So one class is Cue’s only way to read the web for a link — the page, its oEmbed endpoint, the thumbnail and the favicon all go through it — and it trusts nothing it hasn’t checked itself.

1. 1
   Check every address

   Each hop's host is resolved by Cue and refused unless every address it names is public: loopback, private, link-local (the cloud metadata address among them), carrier-grade NAT, multicast and reserved ranges are out, in IPv4, IPv6 and every IPv6 form that wraps an IPv4. A host written as a bare integer or a short dotted form is read the way a browser reads it.

2. 2
   Connect to that address

   The JDK's HTTP client resolves names on its own, so the unfurler opens its own socket to the address it checked and speaks HTTP/1.1 over it, with the URL's host as Host and SNI and TLS verified against it. A DNS answer that changes between the check and the connect reaches nothing.

3. 3
   Follow redirects by hand

   Up to five hops, each checked again. Only http and https on their default ports, and never a URL that carries credentials.

4. 4
   Read the head, then stop

   OpenGraph, then Twitter cards, then the title and description tags; a few media sites fill the gaps from an allowlisted oEmbed endpoint, and YouTube, which walls crawlers from data-centre addresses, is read from its oEmbed alone. Reading stops at </head>, inside 1.5 MiB and five seconds, under one honest user agent.

5. 5
   Clean and re-host

   Control, bidi and zero-width characters go and every field is clamped; nothing from a page is kept as markup. The thumbnail and favicon go through libvips, like a photo, into one upright WebP stripped of metadata, with a BlurHash, stored in R2.

6. 6
   Keep the snapshot

   One immutable row per fetch in link_snapshots, keyed by the URL with its tracking parameters stripped. The newest row is fresh for three days; a failure is a row too, so a dead link isn't fetched again on every pause in typing.

Decided at post

The rule every client is held to: the reader never moves. A card’s height follows from its layout and the width, never from its content or an image loading, and a card is decided when the message posts. A post never waits on a fetch: it attaches only a fresh snapshot the cache already holds. The composer makes that the common case, resolving the draft’s first link on each pause in typing and showing the card as a chip the sender can dismiss. A post that beats it goes out plain, and the server fetches the link once the post commits: if the card lands within 30 seconds, the message gets it then, signalled like an edit. Only that just-sent row grows, and every client holds the reader’s place across it.

A Cue card is never snapshotted. It is hydrated for each viewer at read time, a few IN-queries per page, in one of three tiers: member for someone who can open the target, preview for someone the URL itself lets in — an invite token, a listed channel, a public profile — and none, which names the kind and nothing else. A card never shows more than opening its URL would, and the none type has no title field to fill, so a leak would take a deliberate change of type.

An author can take a card down at any time, past the 10-minute edit window, because removal only subtracts. It rides the kind’s existing *-message-edited signal — no new signal type — and never marks the message edited. Two profile switches turn previews off: one for the links you send, so Cue never fetches them, and one for the cards you see.

Events settle when; Decisions settle what — where to travel, which flat to rent, what to name the band. A decision holds a set of candidate options and one free-text preference per person (“somewhere warm, but Tromsø would be magical”), and Gemini turns them into a recommendation: a pick, a fit score per option, and a written rationale that re-runs whenever the options or preferences change. It’s the decision twin of the event resolver: recommendations is to a decision what resolutions is to an event.

Two AI extras opt in per decision. Option Insights gives each option a grounded pros-and-cons brief, sourced from a live Google Search, with the queries and source links kept alongside for transparency. An AI commentator — Funny or Serious — adds a running take on the deliberation. And a decision grows the same chat an event can — messages, reactions, read receipts, typing, and AI participants — reusing the event-chat machinery wholesale.

Under the hood it borrows every earlier pattern. Thirteen tables — decisions, decision_options, decision_participants, recommendations, option_insights, a decision_* chat family, plus invite links and email invites — mirror the scheduling, AI, and chat domains one for one; a single decision-updated SSE envelope carries every change; and every decision AI path meters against the same Gemini budget as everything else. An optional deadline gives the group a decide-by date. It’s purely informational — nothing auto-finalizes — but a job that wakes every five minutes nudges once as it approaches and once when it passes.

Events, chats, and decisions each settle one question. A Trip settles none — it organizes them. It’s a container: a named, dated thing with its own roster (roles guide and traveler), its own chat, notes, documents, and album, that gathers events and decisions into one timeline. Dates are optional and may lie in the past, so the same entity covers a trip you’re planning for next month and one you took years ago.

That arc is the whole design. Before the dates, the page is a countdown over a date-ordered itinerary of the linked pillars; during, it’s a “happening now” page; afterwards, it’s a memory timeline and a photo album. One continuous entity — nothing to archive or re-create when the trip ends. A memory-only trip with no linked pillars is a first-class citizen, not a degenerate case.

Links, not ownership

A pillar joins a container through a soft link in one table, container_links: typed, nullable foreign keys, with two CHECKs enforcing exactly one pillar (event xor decision) and exactly one container (trip xor channel). Three rules keep it safe:

• A link isn’t access — being in a trip never grants access to a linked event. A non-invitee sees an inert card and joins through the event’s own invite flow; authorization stays per resource.
• A link isn’t ownership — unlinking is non-destructive, deleting a container drops its link rows and never the pillar, and zero links is simply a standalone pillar.
• Per-viewer chips — the “part of” chips on a pillar list only the containers the viewer can actually see, filtered in the service layer, so a secret channel’s name never leaks through a linked event.

The API is deliberately kind-agnostic: POST /api/events/{id}/links takes a containerKind string rather than naming trips. That one decision is why channels could become the second container kind — organizing pillars, spawning trips from their roster, and rendering the same itinerary — without reshaping a single shipped contract.

Thirteen tables, every pattern reused

trips and trip_members; the three invite paths (direct, link, and email), shaped like the ones Events uses; a trip_* chat family on the shared chat core; trip_notes, trip_documents, and trip_media riding the existing photo library; and the two AI companions in trip_briefs and trip_ai_comments. Trip chat is human-only — a trip’s AI voice lives on the trip page, not in the room.

Cue Notes is shared markdown a group writes live: collaborators see each other’s carets and words as they type, anyone can go a week offline and merge on return, and an AI Clean up turns a brain-dump into a tidy note. A note is neither a pillar nor a container — it settles nothing and organizes nothing; it holds writing, and reaches the rest of Cue only through links it renders as chips. On the web it lives at /notes, on the iPhone and on Android in apps of their own, on the Mac as a section of the Cue app, and in the terminal as cue notes; its API is part of the same frozen, additive-only contract as everything the store apps read.

One CRDT, with the server as its authority

A note’s body is a single Automerge text object holding plain markdown — no conflict dialogs, no locks, no last-write-wins. Automerge because it alone has official bindings on every runtime Cue runs: JavaScript on the web, Java on the server and Android, Swift on Apple platforms. Cue runs them as released, and a shared conformance suite — text-position vectors across emoji, CJK and combining marks, and sync transcripts replayed across eight runners — is how it knows they agree. cue-core is a peer in every note and its authority: it reads each incoming change’s bytes itself and admits only plain text splices, written under the sender’s own actor and within the note’s size, before anything reaches the document.

A socket of its own

Keystrokes and carets are high-frequency and two-way, which is exactly what the signal-only SSE stream isn’t for. So Notes has its own transport: one WebSocket per client at /api/notes/live, multiplexed by note, beside an SSE layer it never touches. A client mints a single-use ticket over REST and opens the socket with it. Any replica serves any note, with Valkey relaying changes, presence and roster moves between replicas on channels of their own, and every open document is confined to one single-threaded lane, because the native binding admits one caller at a time. On the web, the editor is CodeMirror 6 on Cue’s own binding to Automerge, rendering formatting in place as you type; it and the Automerge wasm load only on /notes pages, so no other page grows.

Never lose an acknowledged keystroke

The server writes every change to an append-only log and commits before it acknowledges it, and folds the log into a snapshot from the store as it grows. That promise is tested by breaking things: a drill kills a replica mid-typing and checks every acknowledged state against the store, and a randomized fuzz — simulated peers, emoji and CJK splices, reordered delivery, dropped connections — runs with the backend’s tests. On the web, unacknowledged changes wait in IndexedDB, so a tab closed offline loses nothing.

Every user has a single library, and the same item — a photo, a short video, or an uploaded document — can be attached to chat and DM messages or used as an event cover. A photo_usages table tracks every place each item appears, so deleting it cleanly detaches it from every message and cover that referenced it. All three kinds share one table; a media_kind column (image, video, or document) is the only row-level difference. The grid endpoints return what a thumbnail can draw; a separate files surface returns the whole library, documents included. A cover Cue paints joins the library through the same upload path the moment someone keeps it, its origin marked generated.

Storage isn’t on the application server: media lives in Cloudflare R2 buckets (cue-photos-dev and cue-photos-prod). Cue already terminates all public traffic at Cloudflare, so R2 was a natural fit: zero egress fees, an S3-compatible API, and buckets that stay private. Every read is a 302 redirect to a 15-minute presigned URL, minted only after cue-core has checked the requester’s session. R2 honors HTTP Range requests, so video seeking and scrubbing work natively — no streaming server, no HLS.

The image pipeline

The cue-core container ships with libvips: the vips CLI from libvips-tools, plus libheif-plugin-aomenc for AVIF encoding and libheif-plugin-libde265 for HEIC decoding. Compared to Java’s ImageIO, libvips is 10–20× faster and uses a tenth of the memory across HEIC, AVIF, and WebP. It runs as a subprocess per upload: simple, isolated, and upgradeable without touching the JVM.

1. 1
   Magic-byte sniff

   Validate the format from the bytes themselves, not the Content-Type header. HEIC, JPEG, PNG, WebP, AVIF, and GIF are accepted; TIFF, BMP, SVG, and RAW are not.

2. 2
   SHA-256 dedup

   Hash the raw upload. A re-upload returns the existing photo (HTTP 200); a soft-deleted match comes back to life, unless an admin took it down — that row stays behind as a tombstone that refuses the same bytes.

3. 3
   Read EXIF, keep metadata

   DateTimeOriginal is parsed into its own column; the EXIF/XMP block (GPS, camera, timestamps) rides through the re-encode onto every variant. Orientation is baked into the pixels.

4. 4
   Generate variants

   thumb (256w), preview (1024w), display (2048w), and full (up to 4096w), each in AVIF (primary) and WebP (fallback). No JPEG fallback: every supported browser decodes WebP.

5. 5
   Animated GIFs kept whole

   No transcode, no dropped frames. The original GIF is stored as-is, with one static WebP thumbnail for grids and previews.

6. 6
   BlurHash placeholder

   A 28-character string computed from a 64w intermediate and stored on the photo row. Clients paint it instantly as a soft placeholder while the variant loads.

7. 7
   Upload to R2

   Each variant lands at {owner_id}/{photo_id}/{label}.{format}. A failed upload rolls back the database transaction; orphaned objects are swept by a nightly job.

The video pipeline

Video can’t take the photo’s synchronous path: a clip is too big to push through the load balancer, and transcoding takes seconds, not milliseconds. So video uses a three-step, asynchronous flow. The client asks for an upload ticket, PUTs the raw bytes straight to R2 — sidestepping the 55 MB body cap at nginx and Cloudflare’s 100 MB tunnel ceiling, so clips up to 200 MB get through — then calls finalize. That commits a processing row and fires an event; a background worker, limited to two concurrent transcodes, does the heavy lifting with ffmpeg.

The poster frame is grabbed at min(1s, duration/2), which skips a black intro, and fed through the exact same image ladder — so a video shows a real still and a BlurHash placeholder before it ever plays. ffmpeg always emits a 720p video_720 rendition, and a video_1080 only when the source is at least 1080p (it never upscales). Both are H.264/AAC MP4 with the moov atom moved to the front (+faststart) for instant playback, and source metadata copied through (-map_metadata 0), matching the EXIF retention on the photo path. While a clip transcodes, the client shows its BlurHash and a spinner, then flips to the player on the media-ready signal (with a poll as a fallback).

Photos vs. video at a glance

Where-used tracking

Every place a media item appears writes a photo_usages row when the link is created and deletes it when the link goes. The library reads this table to draw chips on each item (“Event chat: Saturday hike”, “DM: Anna”, “Cover: BBQ at the lake”, “Trip album: Lisbon”). It’s also the source of truth for deletion: if an item has live usages, the soft-delete detaches them server-side, and the detached messages render as “(image removed)”.

Every surface above answers “what is this?”. One endpoint answers “where in my Cue is the thing I half-remember?” GET /api/search sweeps events, decisions, trips, channels, people, chat messages, the caller’s own library and — when a client asks for them — notes, in one ranked, membership-scoped answer — fast enough to call on every keystroke.

Postgres does the searching. There is no Elasticsearch, no OpenSearch, no vector store: Cue’s scale doesn’t justify one, and the operational cost would outlive the benefit. Two built-in mechanisms carry it: full-text search over generated tsvector columns for word matching, and pg_trgm word similarity for typos. Nothing is indexed separately — each searchable table carries its own generated column, which is constitutionally incapable of drifting out of sync with the row it summarizes. A denormalized search table would need syncing forever, and its staleness would read to a user as “search is broken”.

Two arms, one round trip

The typed text is folded into a prefix tsquery — every token suffixed :*, so each keystroke narrows the match instead of losing the word mid-type — OR’d with a trigram-similarity arm that carries misspellings (lisbn still finds Lisbon). Ranking is one tunable formula per kind: full-text rank, plus trigram similarity against the primary text, plus an exponential recency decay — a 90-day half-life for entities and 30 days for messages, because among the near-identical lines of a busy conversation, the recent one is almost always the one you want.

The whole request is a single SQL statement. Deliberately non-obvious: the text-search configuration is 'simple' rather than a language, because Cue’s text is a mix of Norwegian and English, and wrong-language stemming is worse than none.

Reach parity

The rule that makes search safe: search never returns what browsing wouldn’t show, and the scope predicate lives inside each SQL branch rather than as a filter applied afterwards in Kotlin. Each branch mirrors the exact membership query behind its list endpoint, so a scoping bug shows up as a missing result, never a leaked one. Messages are one kind spanning five chat tables, so that branch is itself five arms, each re-joining its own conversation’s read gate — a secret channel keeps its messages to its members, and a silently declined DM stays as quiet in search as it is in the thread list. The live API suite proves the negatives directly: searching the exact title of someone else’s private trip returns nothing.

The command palette

The engine’s first consumer is a ⌘K palette (Ctrl+K elsewhere) in the web app, with a native twin in the macOS app, search screens in the iOS and Android apps, and a cue search command in the CLI. It multiplexes three row types: go to (navigation), do (create an event, decision, trip, or channel; switch theme), and jump to (server hits). The first two filter client-side at zero latency, so something useful appears on the first character while server hits stream in behind them. Tab enters a kind scope, worn as a chip — which doubles as “show more”, raising the per-kind cap from 5 to the API’s ceiling of 20. Keystrokes debounce at 150 ms, superseded requests are aborted, the previous results stay on screen so the panel never blanks mid-type, and answers are cached per (query, scope) for as long as the overlay is open — so backspacing through a word costs no round trips at all. Zero new dependencies: no cmdk, no hotkey library.

Consumers hold presentation and keyboard grammar and own no search logic — every future search box adds a consumer, never a second engine.

Cue supports three sign-in methods: Google, Apple, and email one-time codes. The web client runs the OAuth flows through NextAuth v5; the backend verifies credentials from all three on every request.

Users can link several providers to one account through verified email matching — no fragmented accounts, no “which provider did I use?” moments.

Cue’s own sessions

On top of the three providers sits a first-party session: a 1-hour access token plus a 90-day opaque refresh token. There is deliberately one mint endpoint rather than one per provider: POST /api/auth/session takes whichever sign-in credential the caller already holds and lets the existing decoder verify it, so nothing about Google or Apple is re-implemented, and a future provider is covered for free. The one bearer it refuses is a Cue access token, so a session can never re-mint itself.

Every refresh rotates: the presented token is spent and a fresh pair issued. Every token descended from one sign-in shares a family ID, so if a stolen token is replayed after its successor was spent too, the whole family dies in a single update. Only a SHA-256 digest of each refresh token is stored, so a database read never yields a usable credential. A replay whose successor is still unused is the honest case — a client that rotated but never received the response, a second or a week ago — and it simply gets a fresh successor.

Two things about Cue cost real money as it grows: stored bytes and the fan-out of created entities — every event, decision, and trip drags invites, notifications, and AI calls behind it. Rate limits protect the service from bursts; they say nothing about a patient uploader who fills a bucket one photo at a time. So every user carries an effective level that gives them absolute room on those two dimensions — and on a third, the AI images Cue paints for them on demand, each costing about as much as dozens of text calls.

Room grows with tenure automatically. A level is computed, never stored: catalog rows carry a threshold in days since the account was created, and the earned level is simply the highest rung the account’s age clears. No promotion job, no drift, nothing to get out of sync. Admins can also pin a user to a level, which wins even when it sits below the earned one — so generosity and abuse control are the same lever, pointed in two directions.

The ladder is data, not a Kotlin enum — a deliberate exception to the wire-enum rule used everywhere else, because enums are for closed sets and this one is open by design. Adding a tier or retuning a number is an UPDATE, never a contract change that shipped clients have to be checked against. Levels cross the wire as an opaque slug plus server-provided copy, and the allowances ride as an array, which is how the third, AI images, shows as another meter on apps already in the stores.

The whole thing is quiet. Users see their level and room in exactly two places: their own profile, and the admin dashboard. Never on a public profile, a roster, a member list, or any payload another person can read; the level endpoint is self-scoped, which makes leaking structurally hard rather than merely discouraged. Hitting a limit is private too: the acting user gets a warm explanation with numbers and a date, and everyone else sees nothing. And shrinking room never destroys data — the allowance is floored at what a user has already stored, so a downgrade means zero room, never negative.

The database is PostgreSQL 18, managed exclusively through Flyway SQL migrations. Hibernate runs in validate mode — it checks that the entities match the schema but never touches the DDL. Schema changes go through migration files, reviewed and intentional.

A few notable choices. Enum-shaped fields use VARCHAR with CHECK constraints and a custom JPA AttributeConverter on the Kotlin side (never @Enumerated(EnumType.STRING)), so the wire format and the database format share one fixed pattern and never drift. Per-slot resolution scores, recommendation fit scores, Option Insights’ cited sources, and cover crops are stored as JSONB for flexible structure. Profile pictures live in their own table to keep users lean. Message edits are tracked in-row with edited_at and edit_count rather than in a history table. Search adds no tables of its own: every searchable row carries a generated tsvector column plus a pg_trgm index, so the index can never drift from the row it describes.

The schema spans 83 tables, built up over 99 Flyway migrations, and groups cleanly by domain:

Cue deliberately avoids the big cloud providers. No AWS, no GCP compute, no Azure. It runs on physical and rented servers instead — a conscious choice to keep things simple, affordable, and European.

No Kubernetes, by choice

Kubernetes is incredible technology, but it’s built for problems Cue doesn’t have. Two backend replicas behind nginx, managed by Docker Compose, is all the orchestration needed, and the whole production stack fits in a single compose file. If traffic ever outgrows it, scaling up means adding another replica and a line in the nginx config.

Cloudflare Tunnels

Both environments reach the internet through Cloudflare Zero Trust tunnels: no open ports, no public IPs, no reverse-proxy chain. The cloudflared daemon connects outbound to Cloudflare’s edge, which routes each hostname back to its local service. Every published port binds to localhost, so the tunnel is the only way in — which is also what makes the client IP Cloudflare reports trustworthy enough to rate-limit on.

Cue doesn’t use GitHub Actions or any other CI/CD platform. The whole build-and-deploy pipeline is a Fish entry point, omni-deploy, that commits and pushes, then pipes a bash script to the server over SSH. It’s faster, simpler, and entirely under my control.

1. 1
   Git sync

   Commit anything pending and push main to GitHub.

2. 2
   Remote run

   Pipe the deploy script to the server over SSH. It runs detached from the connection, one deploy at a time, and fast-forwards the checkout to exactly the commit pushed.

3. 3
   Validate

   Test the new nginx.conf (production also the compose file) before anything is built.

4. 4
   Build images

   cue-core, cue-front-end, and cue-admin build in parallel. A failed build stops before any container is touched.

5. 5
   Restart

   Recreate only what changed, then reload nginx so it re-resolves the backends.

6. 6
   Health check

   Wait until both backend replicas answer healthy through nginx, and check every container runs the revision just built.

7. 7
   Prune

   Clear dangling images and build cache older than a week.

8. 8
   Verify

   /cue-deploy-verify runs the API test suite against the freshly deployed server, then checks nothing crashed under it.

Steps 1–7 are omni-deploy itself; /cue-deploy-verify wraps it and adds the eighth, exercising the live API contract before a deploy counts as done.

Zero-downtime in production

The production deploy goes further. Instead of restarting everything at once, it recreates the two backend replicas one at a time, waits until each answers healthy through nginx, and reloads nginx before moving on — so a healthy replica is always serving. If the new build won’t come up, the roll stops and both replicas go back to the previous image. The two web apps are single containers, restarted only when they changed, at the cost of a few seconds each.

Why not GitHub Actions?

Building on the server skips the cloning, caching, and artifact transfers a CI runner pays for on every run. The script SSHes into the server, pulls the latest code (most of which is already there from the previous deploy), and builds. The whole pipeline is a handful of readable scripts.

A few honest reasons beyond raw speed:

• More uptime — GitHub Actions has gone down on me more often than my own setup ever has, and a deploy should never wait on someone else’s status page.
• Nicer to write — I got tired of wrangling GitHub’s YAML, and I genuinely enjoy Fish more.
• Fewer ties to one vendor — I’d rather not bake a hard dependency on GitHub into the deploy path; the pipeline runs anywhere I can SSH.

Each service image comes from a multi-stage Dockerfile, tuned for fast rebuilds and minimal runtime images.

All three images build in parallel during a deploy. Thanks to Docker’s layer cache, when only the backend changed, the web images rebuild in seconds — there’s nothing for them to do.

The iOS app is a native SwiftUI application distributed through the App Store. That has a profound effect on the backend: users can’t be force-updated, so every endpoint the app touches is treated as a stable public API.

Adding an optional response field? Safe. Removing a field or renaming an endpoint? Forbidden without a migration plan. That discipline keeps the whole system honest.

The iOS app matches the web for everything that ships: events, decisions with their AI recommendation and Option Insights, Trips with their itinerary, brief, and album, the chat hub — reactions, typing indicators, read receipts, edits, AI participants — 1:1 DMs, channels, the media library, and event cover images. The Codable models in cue-ios/Cue/Models/ mirror the cue-core wire format, and every new field lands as optional so older versions still decode — which is exactly why video shipped as plain optional fields (mediaKind, durationMs, videoUrl) rather than new required ones.

The media viewer

The most polished corner of the app is the full-screen media viewer. Photos pinch to zoom and pan, and pulling down to dismiss fades the backdrop as you drag. Videos play inline with AVKit, handed the same presigned R2 URL the web uses (the app reads the 302 target and cancels the body fetch, so no bearer token ever reaches R2). A floating glass chrome — a close button and a counter — toggles on tap, and neighboring items are prefetched so paging is instant. In chat, runs of media collapse into stacks with play overlays and duration badges; tapping one opens the pager at the right position.

The app supports push notifications through the Apple Push Notification service (APNs), calendar sync for finalized events, home-screen widgets — upcoming events, a trip countdown, and a Chats inbox that puts whoever is waiting on you first, on the Lock Screen too — a Live Activity while a trip is underway, a share extension, and home-screen quick actions. Device tokens are registered at sign-in, live exactly as long as that sign-in, and are cleaned up automatically when APNs reports them invalid. The widgets live in a separate CueWidget target, version-pinned to the main app so they ship together.

The Chats widget keeps itself current while the app is closed. Whenever someone’s Chats rail moves — a message, their own read on another device — cue-core sends a WidgetKit push, coalesced per user in Valkey so a busy group can’t drain the widget’s daily reload budget, and the widget fetches its own rail. That fetch is the push’s receipt: APNs accepting a push doesn’t mean the phone got it, so a push no fetch answers is sent again, up to three times, from seconds to minutes apart. The widget fetches with a credential of its own: the app’s refresh tokens rotate with reuse detection, so a third process spending one could sign the app out. The widget’s credential never rotates, works on its own endpoints and nowhere else, and dies with the sign-in that minted it.

Universal Links tie the web and the app together: tapping a /events/<id> link on iOS opens the event directly in the app if it’s installed, and falls back to the web otherwise. It’s powered by an apple-app-site-association file served by the Next.js front-end, with separate app IDs for the dev and prod builds.

The macOS app

The Mac gets its own SwiftUI app (Swift 6), built for macOS Tahoe. It lives in the menu bar and the Dock, so the next get-together is always a click away. Unlike iOS, it ships outside the App Store — signed, notarized, and delivered as a Homebrew cask and a direct DMG download, with Sparkle handling silent in-app updates. It speaks the same wire format and SSE stream as every other client, so chat, channels, DMs, and the media library all worked the day it shipped. A dedicated /release-macos skill builds, signs, notarizes, and publishes a release — DMG, GitHub Release, Homebrew cask, and Sparkle appcast — in one pass.

Cue Notes lives inside it as a section rather than a separate app: live carets, notes in windows of their own, Spotlight and Handoff, on a local Swift package, CueNotesKit, that shares no code with the iPhone app and is held to the same conformance suite.

The Android app

cue-android is Kotlin and Jetpack Compose, Material 3 with dynamic color, shipped through Google Play. Like iOS it’s a store client, so it consumes the same additive-only API contract — and it’s a pure API client, sharing no code with the Kotlin backend; every model is decoded defensively from the wire. Push arrives through FCM (the backend routes each device token to APNs or FCM by platform), home-screen widgets are drawn with Glance, and the parity-locked domain logic — the trip arc engine, chat grouping, read-receipt pinning — is a verbatim port held to the same golden tests as the web and iOS versions. A /release-android skill builds the signed bundle and publishes it to a Google Play track through the Play Developer API.

Cue Notes for iPhone

Cue Notes has an App Store listing of its own: cue-notes-ios, SwiftUI over TextKit 2, carrying nothing of Cue but its notes. It is written fresh rather than borrowed from cue-ios, and it reads the same data-only conformance suite as the web and the server, so automerge-swift is held to the exact text positions and sync transcripts every other binding is. The app is offline-first: every note’s document lives in a SQLite store on the device, so an airplane-mode round trip loses nothing, and the socket merges it on return. Markdown renders in place as you type, and the system’s reach comes along — a share extension, a pinned-note widget whose checklist ticks from the Home Screen, Spotlight, and Shortcuts. Snapshot goldens, XCUITest flows against dev, and accessibility audits cover every screen.

Cue Notes for Android

Android gets the same app in its own idiom: cue-notes-android, Jetpack Compose over the platform text editor, written fresh rather than borrowed from cue-android or the iPhone app. Gradle modules enforce its layering — an engine and a markdown layer in plain Kotlin that run the conformance suite on the host in seconds, then design, editor, screens, and the app — wired by a hand-written composition root rather than a DI framework. Each open note’s document lives on a lane of its own, never on the main thread, so typing stays quick in a full 64 KB note. Phones and foldables are both first-class: list and note side by side when the fold opens, a split in tabletop posture, and one note open in several windows as one string. And it reaches past the screen: a share target with Direct Share, a pinned-note widget that ticks straight into the document, a Quick Settings tile, and a background sync that delivers words written offline without the app ever being opened.

The CLI is a good example of how AI accelerates development. With the project context already established — API contracts, auth flows, the SSE protocol — Claude Code generated its first version from a single prompt: “Build a CLI for the app in Go, look at the other modules for functionality.”

Today it covers events and responses, decisions, trips, channels, every kind of chat, photos and files, notifications, search, and your profile, plus cue watch, which streams live SSE updates to the terminal. cue notes reads and writes Cue Notes as plain markdown the server merges three-way — sharing, history, and Clean up included — and cue notes watch follows them live over the notes socket. It’s built with Cobra for command structure and the Charmbracelet suite for polished terminal UIs, and emits clean JSON when piped. Tokens live in the system keyring. GoReleaser builds binaries for macOS and Linux (AMD64 and ARM64), generates shell completions, creates a GitHub release, and updates the Homebrew cask — all from a single make release.

Perhaps the most interesting part of Cue’s architecture is how it was built. The entire project was developed with Claude Code, Anthropic’s command-line tool for agentic software development. Claude doesn’t just write the code: it SSHes into servers, runs deploys, checks health, and runs the test suites.

CLAUDE.md: the project brain

At the root of the repo sits CLAUDE.md, the standing instructions every session starts from. It carries the non-negotiables — the iOS API stability contract, the wire-format enum pattern, Flyway-only schema changes, no hardcoded secrets, never confusing dev with prod — alongside a routing table that points the agent to the right deeper doc for whatever it’s working on. AGENTS.md and GEMINI.md are symlinks to the same file, so Codex and Gemini CLI read exactly the same text.

doc/: the deeper map

Beyond CLAUDE.md, the doc/ directory holds the long-form material. doc/components/ has one file per component (cue-core, cue-front-end, cue-admin, cue-cli, cue-ios, cue-android, cue-macos, cue-notes-ios, cue-notes-android, cue-core-api-test, and cue-static-users) covering its layout, build commands, and the rules specific to it, plus a design-system companion for each web app. doc/architecture/ covers the cross-cutting designs — the API surface, SSE, the database schema, infrastructure, each chat kind, decisions, containers, the advanced event features, media, search, user levels, Cue Notes, rich links, image generation, and the AI plumbing.

Keeping CLAUDE.md a lean hub rather than a brain-dump is deliberate: less context per session, more accuracy per task. A standing rule keeps the docs honest — when a change alters what a doc describes, the doc changes in the same commit.

Skills: complex workflows as commands

The real leverage comes from custom skills: workflows defined in .claude/skills/, each a markdown file describing a multi-step operation the agent runs as a slash command. Thirty-eight of them cover the whole lifecycle:

A typical session: write a feature, run /cue-deploy-verify to deploy and test it, iterate on feedback, then /deploy-prod when it’s ready. The whole cycle — from code change to a verified production deploy — happens without leaving the terminal.

Memory: learning across sessions

Claude Code also keeps a persistent memory across conversations: preferences, project context, and workflow feedback are stored and recalled automatically. Here it’s kept deliberately small — most knowledge belongs in the code, the docs, or a skill, where the next session will actually read it.