Under the Hood

Cue is an event scheduling app that uses AI to help groups of friends coordinate plans through natural language. Someone proposes a few times, friends reply however they want — “Wednesday works but I’d prefer Thursday” — and Gemini figures out the best option.

Behind that simple idea sits a monorepo with eight modules, written in four languages, running on personal servers connected to the world through Cloudflare Tunnels. No Kubernetes. No GitHub Actions. No cloud functions. Just Docker containers, a load balancer, and a Fish shell script.

Around the scheduling core the surface has grown: a live group chat with optional AI participants, 1:1 direct messages, standalone topic channels, group decisions the whole party settles together with AI, Trips that gather events and decisions into one timed arc, a per-user library of photos and short videos that doubles as chat attachments and event covers, AI weather reports, AI commentary, push notifications, home-screen widgets, calendar sync, and one search platform that reaches all of it from a ⌘K palette. They all share the same backend, the same SSE channel, and the same deploy pipeline.

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

Everything lives in a single monorepo. This was a deliberate choice — it lets the AI agent see the full picture when working across boundaries, and keeps documentation, deploy scripts, and configuration in one place.

Each module uses the language that fits its domain best. No universal compromise — just the right tool for each job.

On top of that: ~1,500 lines of SQL across 73 Flyway migrations, ~120 lines of Fish for deploy automation (a dev and a prod entrypoint over a shared lib), and a pile of YAML/TOML for Docker Compose and GoReleaser configuration. The codebase has more than tripled since the first version of this page — the original scheduler is now a small fraction of the surface; chat, DMs, channels, group decisions, Trips, the media library, and the iOS, Android and macOS apps account for most of the new lines.

Every request to Cue travels the same path: from the client, through a Cloudflare Tunnel, into an nginx load balancer, and finally to one of two backend instances.

The nginx load balancer distributes traffic between two cue-core instances with automatic failover. If one goes down, the other picks up immediately. SSE connections get a 24-hour read timeout so they can stay alive for as long as the user has the app open. Media reads are 302-redirected straight from cue-core to a 15-minute presigned R2 URL, so the bytes never round-trip through the application server — and large video uploads go directly to R2, bypassing the load balancer’s body limit entirely.

In total, eight containers run in Docker Compose, plus one external store for media. Here’s the complete picture:

Cue needs to feel instant. When someone responds to an event, everyone else should see it immediately — on web, iOS, Android, macOS, and the CLI. Instead of WebSockets or polling, Cue uses Server-Sent Events (SSE), a simple, HTTP-native protocol for one-way real-time streaming.

How it works

The client opens a long-lived HTTP connection to /api/sse/stream. The server keeps that connection open and pushes events down whenever something happens. It’s beautifully simple.

Signal-based, not payload-based

This is a key design choice. SSE events in Cue are signals, not data payloads. When the backend sends an event-updated signal, it doesn’t include the event data. Instead, the client refetches the relevant data through the normal REST API. This keeps authorization logic centralized in one place and the SSE layer paper-thin.

Multi-instance broadcasting

With two backend instances behind a load balancer, a signal produced by instance 1 needs to reach clients connected to instance 2. Cue solves this with a Valkey pub/sub relay. When a service publishes a signal, it goes to Valkey first, and every backend instance picks it up and broadcasts to its connected clients.

Transactional safety

Signals are only sent after the database transaction commits. This is enforced through Spring’s TransactionSynchronization.afterCommit(). If a transaction rolls back, no signal is ever sent. No phantom updates. No race conditions.

Heartbeats and reconnection

A heartbeat is sent every 20 seconds to keep connections alive and detect dead ones. On the client side, if the connection drops, an exponential backoff kicks in — starting at 1 second and capping at 30. A 401 response stops the retry loop entirely and redirects to login instead of hammering the server.

One channel, many signal types

Everything realtime in Cue rides this same channel. The wire format is uniform — a named SSE event plus a tiny JSON body identifying what changed — and adding a new signal type is a one-line change in the broadcaster. The signal types, grouped by domain:

AI isn’t just a development tool for Cue — it’s embedded in the product itself. The backend talks to Gemini through Google’s Vertex AI. Where the original Cue had a single AI feature (the suggested-time resolver), the product now uses Gemini in six distinct places.

Every one of them runs on Gemini 3.7 Flash — the suggested time, the AI comment, the weather read, the Trip Brief, the whole decision brain (recommendation, Option Insights, and decision commentary), the live chat participants in event and decision chats alike, and the option brainstormer that seeds a new decision. The analytical work and the conversational work stay on separate config keys, so the latency-critical half can be split onto its own model whenever that trade is worth making.

All of them share the same pattern: a service publishes a Spring ApplicationEvent after the database transaction commits, an @Async listener calls Gemini, and the result is broadcast back to every connected client over SSE. Independent entities, independent listeners, independent SSE signal types, independent rate-limit checks — one feature can never block another.

The user sees their write saved instantly; moments later, the AI response arrives over SSE without a page refresh. Every AI call is logged with token counts and cost. The admin dashboard tracks daily, weekly, and monthly Gemini spend against configurable caps — one user can’t torch the month’s budget.

Chat started as an organizer-toggled feature on individual events. It grew into a full messaging surface with five kinds of conversation: the live chat bolted onto an event, a 1:1 direct message, a standalone topic channel, the chat a decision grows, and a trip’s own room. The hub at /chat lists all five together, sorted by activity, with unread badges per conversation and a total badge in the top nav.

The hub is two-pane — conversation rail on the left, the selected thread on the right. On mobile it collapses into list↔detail navigation. Opaque conversation IDs (event-{id}, dm-{otherUserId}, channel-{id}, decision-{id}, trip-{id}) keep routing forward-compatible — the frontend never assumes their shape beyond passing them through to the API, and a client that doesn’t recognize a kind simply drops that row.

What every conversation has

Media stacks

When someone fires off several photos or videos in a row, the client collapses them into a stack — two or three render as a tidy collage, four or more as a fanned pile with a “+N” badge. This is purely presentational: each message still carries at most one attachment, and the stack just groups consecutive media from the same sender so the thread doesn’t become a wall of thumbnails.

Channels: a room of its own

Channels are standalone group chats — #oslo, #fotball — that aren’t tied to any event. They reuse everything above (composer, reactions, read cursors, typing, edits, media) and add the machinery 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 adminless or staging 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 that keeps them out of the hot fan-out path entirely, rather than smearing a “was-removed” check across every query.
• Human-only — unlike event and decision chats, channels don’t take AI participants.

AI participants (event & decision chats)

Any invitee can drop an AI into an event or decision chat (up to five per room). The user picks a name (or accepts a randomized one), a free-form personality string, and an interaction mode:

• proactive — reads every new message and decides whether to respond.
• mention_only — speaks only when its name is mentioned.
• event_driven — nudges around event state changes (someone responds, organizer finalizes, etc.).

An @-mention forces the named AI to weigh in regardless of mode. AIs added by a user are removable by that user or the organizer; removed AIs disappear from the participants strip and stop responding, but their past messages stay, attributed to the now-removed AI by name so history reads correctly.

Data model & limits

Every kind runs on its own parallel family of tables, all cut to the same shape: messages, a read cursor, reactions. chat_messages, chat_read_state, chat_message_reactions for event chats; their dm_* twins plus a dm_threads row for DMs; a seven-table channel_* family for channels; and decision_* and trip_* sets for the two newest rooms. 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 HTTP-level limits — OTPs, per-user writes, uploads, IP ceilings — not message posting.)

Scheduling settles when; the third pillar settles 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 that into a recommendation: a picked option, per-option fit scores, and a written rationale that re-runs whenever the options or preferences change. It’s the decision analog 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 query set 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 signal carries every change; and all of the decision AI paths meter against the same Gemini budget as everything else. An optional deadline gives the group a decide-by instant — purely informational, nothing auto-finalizes, but a nightly job 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, its own notes, documents and album, that gathers events and decisions into one timeline. Dates are optional and may sit 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. Ahead of the dates the page is a countdown over a date-ordered itinerary of the linked pillars; during, it’s a “happening now” state; behind, 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 zero 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, with typed-nullable FKs and two CHECKs enforcing exactly one pillar (event xor decision) against exactly one container (trip xor channel). Three rules make it safe:

• Link ≠ access — being in a trip never grants access to a linked event. A non-invitee sees an inert discoverable card and joins through the event’s own invite flow. Authorization stays per-resource.
• Link ≠ ownership — unlinking is non-destructive, deleting a container drops its link rows and never the pillar, and zero links is just a standalone pillar.
• Per-viewer chips — the “part of” chips on a pillar list only 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 became the second container kind — growing the power to organize pillars, spawn trips from their roster, and render the same itinerary — without reshaping a single shipped contract.

Thirteen tables, every pattern reused

trips and trip_members, the three invite paths (direct, link, email) on the same tables Events uses, a trip_* chat family on the shared chat core, trip_notes / trip_documents / 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.

Every user has a single library; the same item — a photo, a short video or an uploaded document — can be attached to chat or DM messages and used as an event cover image. A photo_usages table tracks every place each item lives, so deleting it cleanly detaches it from every message and cover that referenced it. All three share one table; a media_kind column (image, video or document) is the only thing that distinguishes them at the row level. The grid endpoints return what a thumbnail can draw; a separate files surface returns the whole library, documents included.

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 through Cloudflare, so R2 was a natural fit: zero egress fees, S3-compatible API, and the buckets stay private. Every read is a 302 redirect to a 15-minute presigned URL, minted only after cue-core verifies the requester’s session. R2 honors HTTP Range requests, so video seeking and scrubbing work natively — no separate 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 encode). Compared to Java’s ImageIO, libvips is 10–20× faster and uses 10× less RAM across HEIC, AVIF, and WebP. It runs as a CLI subprocess per upload — simple, isolated, and upgradeable without touching the JVM.

The video pipeline

Video can’t ride the same synchronous path as a photo — 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 the nginx load balancer — and Cloudflare’s 100 MB Tunnel ceiling — to let clips up to 200 MB through), then calls finalize. That commits a processing row and fires an event; a background worker, bounded to two concurrent transcodes, does the heavy lifting with ffmpeg.

The poster frame is grabbed at min(1s, duration/2) (so it skips a black intro), then fed through the exact same image ladder — which means a video shows a real still plus a BlurHash placeholder before it ever plays. ffmpeg emits a baseline 720p video_720 rendition always, and a video_1080 only if the source is at least 1080p (never upscaled). 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 is transcoding the client shows its BlurHash and a spinner, then flips to the player on the media-ready signal (with a poll as 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 is removed. The library page reads this table to render 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 delete UX: if an item has live usages, soft-delete detaches them server-side and the detached messages render as “(image removed)” client-side.

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, and the caller’s own library 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 ops 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 rather than 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 — 90-day half-life for entities, 30 for messages, because among the near-identical lines of a busy conversation the recent one is almost always the wanted one. The whole request is a single SQL statement: each kind’s branch is one UNION ALL arm, capped and ordered inside itself. No fan-out, no post-merge fetches. Deliberately non-obvious: 'simple' rather than a language config, because Cue’s text is mixed 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 and never as 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 off-Mac) 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 is also the “show more” affordance, raising the per-kind cap from 5 to the API’s ceiling of 20. Keystrokes debounce at 150 ms, superseded requests are aborted, 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 OTP. The frontend handles OAuth flows via NextAuth v5, while the backend validates JWT tokens from all three providers on every request.

Users can link multiple providers to one account through verified email matching — no account fragmentation, 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 bearer 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.

Each refresh rotates: the presented token is revoked and a fresh pair issued. Every rotation descended from one sign-in shares a family ID, so if a stolen token is ever replayed after it was consumed, the whole chain dies in a single update. Only a SHA-256 digest of the refresh token is stored — there is no low-entropy secret to brute-force. A one-minute grace window covers the honest case where a client rotated but never received the response.

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.

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 lower than earned — 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 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 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, so a third dimension would light up as another meter on apps already in the App Store.

The whole thing is quiet. A user sees their level and room in exactly two places — their own profile, and the admin dashboard. Never in 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 entities match the schema but never touches the DDL. Schema changes go through migration files, reviewed and intentional.

Some notable choices: enum-shaped fields use VARCHAR with CHECK constraints and a custom JPA AttributeConverter on the Kotlin side (no @Enumerated(EnumType.STRING)) so the wire-format and DB-format share one fixed pattern and never drift. AI resolution scores, weather forecasts, and AI-comment metadata are stored as JSONB for flexible structure. Profile pictures live in a separate table to keep the users table lean. Message edits are tracked in-row with edited_at / edit_count columns rather than 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 has grown to 73 Flyway migrations across 63 tables, which group cleanly by domain:

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

No Kubernetes, by choice

Kubernetes is incredible technology, but it’s designed for problems Cue doesn’t have. Two backend instances behind nginx, managed by Docker Compose, is all the orchestration needed. The entire infrastructure fits in a single compose file. If traffic ever outgrows this setup, scaling up is a matter of adding another instance and a line in the nginx config.

Cloudflare Tunnels

Both environments are exposed to the internet through Cloudflare Zero Trust tunnels. No open ports, no public IPs, no traditional reverse proxy chain. The cloudflared daemon runs as a Docker container and connects outbound to Cloudflare’s edge, which then routes traffic to the local services. It’s elegant and secure.

Cue doesn’t use GitHub Actions or any CI/CD platform. Instead, the entire build and deploy pipeline is a Fish shell script called omni-deploy. It’s faster, simpler, and gives complete control.

Steps 1–6 are the omni-deploy script itself; /cue-deploy-verify wraps it and adds the seventh, exercising the live API contract before the deploy is called done.

Zero-downtime in production

The production deploy script goes further. Instead of restarting everything at once, it updates containers one by one — waiting for each to pass its health check before moving to the next. Nginx is reloaded after each backend instance updates, so there’s always at least one healthy instance serving traffic. Users never see downtime.

Why not GitHub Actions?

Building locally on the server skips the overhead of cloning, caching, and transferring artifacts. The Fish script SSHes directly into the server, pulls the latest code (which is already mostly there from the previous deploy), and builds. The whole pipeline is a single readable script.

A few honest reasons, beyond the raw speed:

• Faster on my own boxes — the code already lives on the server, so a build skips the clone, cache-warm, and artifact shuffle a fresh GitHub runner pays for every time.
• More uptime — GitHub Actions has gone down on me more often than my own setup ever has; 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 module has a multi-stage Dockerfile optimized for fast rebuilds and minimal runtime images.

All three images build in parallel during deploys. Docker layer caching means that if only the backend code changed, the frontend images rebuild in seconds (nothing to do).

The iOS app is a native SwiftUI application distributed through the App Store (currently version 1.30). This has a profound impact on the backend architecture: since users can’t be force-updated, every API endpoint the iOS 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. This discipline keeps the system honest.

The iOS surface matches the web for everything that ships: events, group decisions with their AI recommendation and Option Insights, Trips with their itinerary, brief and album, the chat hub — reactions, typing indicators, read receipts, message edits, AI participants — 1:1 DMs, standalone channels, the media library, and event cover images. The Codable models in cue-ios/Cue/Models/ mirror the cue-core wire format; every new field lands as optional so older shipped versions decode without error — 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 pull-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 crosses to R2). A floating glass chrome — close button and counter — toggles on tap, and adjacent 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 Apple Push Notification service (APNs), calendar sync for finalized events, home-screen widgets in three sizes, and quick actions from the home screen. Device tokens are registered on login and stale tokens are automatically cleaned up when APNs reports them as invalid. There’s a separate CueWidget target for the home-screen widgets, version-pinned to the main app so they ship together.

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

The macOS app

The Mac has 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 through a Homebrew Cask and a direct DMG download, with Sparkle handling silent in-app updates. It speaks the same cue-core 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 /deploy-macos skill builds, signs, notarizes, and publishes a release — DMG, GitHub Release, Homebrew cask, and Sparkle appcast — in one pass.

The Android app

The newest native client is cue-android: 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 frozen-additive API contract — and it’s a pure API client, sharing zero 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 the web and iOS versions answer to. A /release-android skill builds the signed bundle and publishes it to a Google Play track through the Play Developer API.

The CLI was the last module added, and it’s a great example of how AI accelerates development. With the full project context already established — API contracts, auth flows, SSE protocol — Claude Code generated the entire CLI from a single prompt: “Build a CLI for the app in Go, look at the other modules for functionality.”

It covers events, responses, notifications, and user profile from the terminal, plus a cue watch command that streams live SSE updates. It’s built with Cobra for command structure and the Charmbracelet suite for beautiful terminal UIs, and emits clean JSON when piped. Authentication tokens are stored securely in the system keyring. Distribution happens through GoReleaser, which builds binaries for macOS and Linux (both AMD64 and ARM64), generates shell completions, creates a GitHub release, and updates the Homebrew formula — 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 using Claude Code — Anthropic’s CLI tool for agentic software development. Claude doesn’t just write code; it SSHes into servers, runs deploys, verifies health checks, and runs test suites.

CLAUDE.md: the project brain

At the root of the repo sits a CLAUDE.md file that acts as persistent instructions for Claude. It carries the non-negotiables — the iOS API stability contract, Kotlin-only backend, Flyway-only schema changes, the wire-format enum pattern — alongside a navigation map that points the agent to the right deeper doc for whichever component or area is in play. Every session starts by reading this file. Thin AGENTS.md and GEMINI.md pointer files at the same level mean gemini-cli and Antigravity sessions land on the same instructions.

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-core-api-test, cue-static-users) covering its layout, build commands, and the rules specific to it. doc/architecture/ covers cross-cutting designs — the API surface, SSE, the database schema, infrastructure, each chat kind, decisions, containers, the advanced event features, the media system, search, and user levels. CLAUDE.md routes to whichever doc is relevant rather than restating their contents.

CLAUDE.md was originally a flat brain-dump. It’s now structured as a navigation hub: short non-negotiables at the top, then a “working on X? read Y” routing table that points the agent to the right deeper doc. Less context per session, more accuracy per task.

Skills: complex workflows as commands

The real power comes from custom skills — parameterized workflows defined in .claude/skills/. Each skill is a markdown file that describes a multi-step operation Claude can execute as a slash command. Twenty-six of them now cover the whole lifecycle:

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

Memory: learning across sessions

Claude Code has a persistent memory system that carries knowledge between conversations. Feedback about preferred approaches, project context, and workflow preferences are stored and recalled automatically. The agent gets better at working with this specific project over time.