Mobile notifications for iOS (#210)

* mobile: wire notification registration and listener

* implement backend components for push notifications

* refactor: agentic comment cleanup

* docs: use proper module name for particle processor

* set required env variables for push notifications

* bump version

* fix: always upsert push token on mobile start

* Revert "fix: always upsert push token on mobile start"

This reverts commit 90ff18a788.

* send push notifications regardless of online status

go/cmd/emailnotifierjob/main.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"log/slog"
 	"os"
-	"strings"
 	"time"
 
 	"cloud.google.com/go/firestore"
@@ -21,22 +20,17 @@ import (
 )
 
 const (
-	// Only notify about streams with activity in the last 24 hours
-	maxActivityAge = 24 * time.Hour
-	// Minimum time a message must be unread before we consider notifying
-	unreadThreshold = 10 * time.Minute
-	// Minimum time between emails to the same user
-	emailCooldown = 12 * time.Hour
+	maxActivityAge  = 24 * time.Hour  // ignore streams idle longer than this
+	unreadThreshold = 10 * time.Minute // grace window before a message is "unread"
+	emailCooldown   = 12 * time.Hour   // min gap between emails to the same user
 )
 
 func main() {
 	ctx := context.Background()
 
-	// Initialize Postgres
 	db.Init()
 	defer db.Cleanup()
 
-	// Initialize Firestore
 	gcpProject := utils.MustGetEnv("GCP_PROJECT")
 	firestoreClient, err := firestore.NewClient(ctx, gcpProject)
 	if err != nil {
@@ -45,7 +39,6 @@ func main() {
 	}
 	defer firestoreClient.Close()
 
-	// Initialize aero (email) gRPC client
 	aeroAddr := utils.MustGetEnv("AERO_ADDR")
 	aeroConn, err := grpc.NewClient(aeroAddr, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
@@ -55,7 +48,6 @@ func main() {
 	defer aeroConn.Close()
 	aeroSvc := pbaero.NewPrimaryClient(aeroConn)
 
-	// Initialize pusher gRPC client
 	pusherAddr := utils.MustGetEnv("PUSHER_GRPC_ADDR")
 	pusherConn, err := grpc.NewClient(pusherAddr, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
@@ -65,7 +57,6 @@ func main() {
 	defer pusherConn.Close()
 	pusherSvc := pbpusher.NewPusherServiceClient(pusherConn)
 
-	// Initialize services
 	humanSvc := human.NewService(db.Pool())
 	networkSvc := network.NewReader(db.Pool())
 
@@ -87,13 +78,11 @@ func runNotificationCycle(
 ) error {
 	now := time.Now()
 
-	// Load all networks
 	networks, err := networkReader.ListAll(ctx)
 	if err != nil {
 		return fmt.Errorf("listing networks: %w", err)
 	}
 
-	// Load all humans into a lookup map
 	allHumans, err := humanSvc.ListAll(ctx)
 	if err != nil {
 		return fmt.Errorf("listing humans: %w", err)
@@ -103,11 +92,9 @@ func runNotificationCycle(
 		humansById[h.ID] = h
 	}
 
-	// Track which streams each human is behind on, and the latest activity across those streams
 	behindCounts := map[string]int{}
 	latestActivity := map[string]time.Time{}
 
-	// Get all currently connected humans
 	allOnline := map[string]bool{}
 	onlineResp, err := pusherSvc.GetOnlineHumanIds(ctx, &pbpusher.GetOnlineHumanIdsRequest{})
 	if err != nil {
@@ -119,42 +106,29 @@ func runNotificationCycle(
 	}
 
 	for _, net := range networks {
-		// Build set of all member humanIds for this network (members + admin)
-		networkMembers := make(map[string]bool, len(net.MemberHumanIds)+1)
-		for _, id := range net.MemberHumanIds {
-			networkMembers[id] = true
-		}
-		networkMembers[net.AdminHumanId] = true
-
-		// Query Firestore for open streams in this network
 		streams, err := getOpenStreams(ctx, fsClient, net.ID)
 		if err != nil {
 			slog.Error("failed to query streams", "networkId", net.ID, "error", err)
 			continue
 		}
 
+		// net.MemberHumanIds already includes the admin.
 		for _, stream := range streams {
 			if stream.LastChildCreatedAt == nil {
 				continue
 			}
-			// Skip streams with no recent activity
 			if now.Sub(*stream.LastChildCreatedAt) > maxActivityAge {
 				continue
 			}
-			// Skip if the latest message is too fresh (within threshold)
 			if now.Sub(*stream.LastChildCreatedAt) < unreadThreshold {
 				continue
 			}
 
-			// Resolve members from visible_to
-			members := resolveMembers(stream.VisibleTo, networkMembers)
-
-			for humanId := range members {
+			for _, humanId := range network.ResolveVisibility(stream.VisibleTo, net.MemberHumanIds) {
 				marker, hasMarker := stream.PlaybackMarkers[humanId]
 				if hasMarker && !marker.Before(*stream.LastChildCreatedAt) {
-					continue // up to date
+					continue
 				}
-				// No marker or marker is behind → this human is behind on this stream
 				behindCounts[humanId]++
 				if stream.LastChildCreatedAt.After(latestActivity[humanId]) {
 					latestActivity[humanId] = *stream.LastChildCreatedAt
@@ -164,10 +138,8 @@ func runNotificationCycle(
 
 	}
 
-	// Send notifications
 	sentCount := 0
 	for humanId, count := range behindCounts {
-		// Skip online users
 		if allOnline[humanId] {
 			slog.Info("human online...skipping email", "humanId", humanId)
 			continue
@@ -178,28 +150,24 @@ func runNotificationCycle(
 			continue
 		}
 
-		// Skip if notifications disabled
 		if !h.EmailNotificationsEnabled {
 			continue
 		}
 
-		// Skip if no new activity since last notification
+		// Skip if nothing new since the previous email.
 		if h.LastEmailNotificationSentAt != nil && !latestActivity[humanId].After(*h.LastEmailNotificationSentAt) {
 			continue
 		}
 
-		// Enforce cooldown between emails to the same user
 		if h.LastEmailNotificationSentAt != nil && now.Sub(*h.LastEmailNotificationSentAt) < emailCooldown {
 			continue
 		}
 
-		// Send email
 		if err := sendNotificationEmail(ctx, aeroSvc, h, count); err != nil {
 			slog.Error("failed to send email", "humanId", humanId, "error", err)
 			continue
 		}
 
-		// Update last sent timestamp
 		if err := humanSvc.UpdateLastEmailNotificationSentAt(ctx, humanId, now); err != nil {
 			slog.Error("failed to update last_email_notification_sent_at", "humanId", humanId, "error", err)
 		}
@@ -215,7 +183,6 @@ func runNotificationCycle(
 	return nil
 }
 
-// getOpenStreams queries Firestore for all open stream particles in a network.
 func getOpenStreams(ctx context.Context, client *firestore.Client, networkId string) ([]particle.FirestoreStreamParticle, error) {
 	collPath := fmt.Sprintf("networks/%s/children", networkId)
 	docs, err := client.Collection(collPath).
@@ -239,27 +206,6 @@ func getOpenStreams(ctx context.Context, client *firestore.Client, networkId str
 	return streams, nil
 }
 
-// resolveMembers expands visible_to entries into a set of humanIds.
-// "human:{id}" adds that id directly. "network:{id}" expands to all network members.
-func resolveMembers(visibleTo []string, networkMembers map[string]bool) map[string]bool {
-	members := map[string]bool{}
-	for _, entry := range visibleTo {
-		if strings.HasPrefix(entry, "human:") {
-			humanId := strings.TrimPrefix(entry, "human:")
-			// human can be in visible_to, but no longer a member of the network
-			if _, ok := networkMembers[humanId]; ok {
-				members[humanId] = true
-			}
-		} else if strings.HasPrefix(entry, "network:") {
-			// Expand to all network members
-			for id := range networkMembers {
-				members[id] = true
-			}
-		}
-	}
-	return members
-}
-
 func sendNotificationEmail(ctx context.Context, aeroSvc pbaero.PrimaryClient, h *human.Human, streamCount int) error {
 	streamsWord := "stream"
 	if streamCount != 1 {

go/cmd/memberreconciler/main.go

@@ -1,13 +1,7 @@
-// memberreconciler is a one-shot job (also safe to run on a cron) that makes
-// the Firestore membership mirror (humans/{humanId}.networks) match the
-// authoritative Postgres network_members table.
-//
-// Run on a cron to heal any drift from a dropped mirror
-// write in network.Service.
-//
-// The reconciler reads the current Firestore state and only writes humans
-// whose mirrored networks differ from Postgres. Writes cost ~3x reads, and in
-// steady state drift is rare, so read-first keeps the cron nearly free.
+// memberreconciler reconciles the Firestore membership mirror
+// (humans/{humanId}.networks) against the authoritative Postgres
+// network_members table. Safe to run on a cron — only humans whose mirrored
+// set differs from Postgres are written, so a steady-state run is nearly free.
 package main
 
 import (
@@ -98,8 +92,7 @@ func reconcile(
 	return written, scanned, nil
 }
 
-// snapshotMirror streams the humans collection once and returns a map of
-// humanId -> current networks array. One iterator, N billed reads.
+// One iterator, N billed reads — returns humanId → mirrored networks.
 func snapshotMirror(ctx context.Context, fs *firestore.Client) (map[string][]string, error) {
 	out := map[string][]string{}
 	iter := fs.Collection("humans").Documents(ctx)
@@ -124,9 +117,8 @@ func snapshotMirror(ctx context.Context, fs *firestore.Client) (map[string][]str
 	return out, nil
 }
 
-// sameSet reports whether a and b contain the same elements, ignoring order
-// and duplicates. Firestore array ops don't preserve order, so set equality is
-// the right comparison for the networks array.
+// Set equality (order- and duplicate-insensitive); Firestore array ops don't
+// preserve order.
 func sameSet(a, b []string) bool {
 	if len(a) == 0 && len(b) == 0 {
 		return true

go/cmd/orion/main.go

@@ -18,6 +18,7 @@ import (
 	"github.com/flowy-live/llink/internal/depot"
 	"github.com/flowy-live/llink/internal/handler"
 	"github.com/flowy-live/llink/internal/human"
+	"github.com/flowy-live/llink/internal/human/pushnotify"
 	"github.com/flowy-live/llink/internal/livekit"
 	"github.com/flowy-live/llink/internal/livestore"
 	"github.com/flowy-live/llink/internal/middleware"
@@ -106,9 +107,10 @@ func main() {
 		BucketName:                gcsBucket,
 	})
 	waitlistSvc := waitlist.NewService(db.Pool(), aeroSvc)
+	pushTokenSvc := pushnotify.NewService(db.Pool())
 	livekitClient := livekit.NewClient()
 
-	h := handler.NewHandler(authSvc, humanSvc, networkSvc, particleSvc, depotSvc, waitlistSvc, billingSvc, livekitClient, firestoreClient)
+	h := handler.NewHandler(authSvc, humanSvc, networkSvc, particleSvc, depotSvc, waitlistSvc, billingSvc, pushTokenSvc, livekitClient, firestoreClient)
 
 	withAuth := func(hf http.HandlerFunc) http.Handler {
 		return middleware.Auth(authSvc)(http.HandlerFunc(hf))
@@ -143,6 +145,10 @@ func main() {
 	// Settings
 	mux.Handle("PATCH /humans/me/settings", withAuth(h.UpdateSettings))
 
+	// Push notification tokens (per-device)
+	mux.Handle("POST /humans/me/push-tokens", withAuth(h.RegisterPushToken))
+	mux.Handle("DELETE /humans/me/push-tokens", withAuth(h.UnregisterPushToken))
+
 	// Networks
 	mux.Handle("POST /networks", withAuth(h.CreateNetwork))
 	mux.Handle("GET /networks", withAuth(h.ListNetworks))
@@ -179,8 +185,7 @@ func main() {
 	mux.Handle("GET /waitlist/{email}", withAuth(h.GetWaitlistEntry))
 	mux.Handle("POST /waitlist/invite", withAuth(h.InviteWaitlistEntrant))
 
-	// Apply middleware
-	// nil allows all origins (required for electron app)
+	// nil = allow all origins (Electron app needs it).
 	muxWithCors := middleware.CORS(nil)(mux)
 
 	addr := fmt.Sprintf("0.0.0.0:%s", port)

go/cmd/particleprocessorworker/main.go

@@ -6,11 +6,15 @@ import (
 	"log"
 	"log/slog"
 	"os"
+	"strings"
 	"time"
 
 	"github.com/flowy-live/llink/internal/billing"
 	"github.com/flowy-live/llink/internal/db"
 	"github.com/flowy-live/llink/internal/depot"
+	"github.com/flowy-live/llink/internal/human"
+	"github.com/flowy-live/llink/internal/human/pushnotify"
+	"github.com/flowy-live/llink/internal/network"
 	"github.com/flowy-live/llink/internal/particle"
 	"github.com/flowy-live/llink/internal/speech"
 	"github.com/flowy-live/llink/internal/utils"
@@ -31,13 +35,9 @@ func createClient(ctx context.Context) *firestore.Client {
 	return client
 }
 
-// The purpose of the particle processor worker is to listen for new particles
-// across all streams and perform side effects such as
-//   - generate transcript if the particle is of type media
-//   - send mobile notifications if a client is offline
-//   - update the parent stream's `last_child_created_at`
-//   - generate vector embedding
-//   - synthesize and decide whether ai should generate a particle as a response
+// Listens for new particles and runs per-particle side effects: transcripts,
+// transcode, parent stream's last_child_created_at, freemium usage, and push
+// notifications for offline recipients.
 func main() {
 	ctx := context.Background()
 
@@ -61,6 +61,14 @@ func main() {
 
 	speechSvc := speech.NewSpeechService(ctx)
 
+	humanSvc := human.NewService(db.Pool())
+	networkReader := network.NewReader(db.Pool())
+	pushTokenSvc := pushnotify.NewService(db.Pool())
+	// EXPO_ACCESS_TOKEN is required: Enhanced Security is on for our Expo
+	// project (otherwise anyone holding one of our push tokens could spam users).
+	expoClient := pushnotify.NewExpoClient(utils.MustGetEnv("EXPO_ACCESS_TOKEN"))
+	notifier := pushnotify.NewNotifier(networkReader, pushTokenSvc, expoClient)
+
 	client := createClient(ctx)
 	defer client.Close()
 
@@ -102,13 +110,14 @@ func main() {
 
 			slog.Debug("processing particle", "particleID", particleID, "data", change.Doc.Data())
 
-			// --- Perform side effects ---
-			// All of them do not stop us from marking the particle as processed
-
-			updateParentLastChildCreatedAt(ctx, change.Doc)
-			transcribeMediaParticle(ctx, depotSvc, speechSvc, change.Doc)
+			// Side effects below are best-effort — failures don't prevent
+			// marking the particle as processed.
+			parentDoc := loadParentParticle(ctx, change.Doc)
+			updateParentLastChildCreatedAt(ctx, change.Doc, parentDoc)
+			transcript := transcribeMediaParticle(ctx, depotSvc, speechSvc, change.Doc)
 			particle.Transcode(ctx, depotSvc, change.Doc)
 			recordFreemiumUsage(ctx, billingSvc, change.Doc)
+			notifyForParticle(ctx, notifier, humanSvc, change.Doc, parentDoc, transcript)
 
 			if err := processingRepo.MarkProcessed(ctx, particleID); err != nil {
 				slog.Error("failed to mark particle as processed", "particleID", particleID, "error", err)
@@ -117,35 +126,37 @@ func main() {
 	}
 }
 
-func transcribeMediaParticle(ctx context.Context, depotSvc depot.Service, speechSvc speech.SpeechService, doc *firestore.DocumentSnapshot) {
+// Writes the structured transcript to Firestore and returns the raw text;
+// returns "" for non-media particles or on any error (logged internally).
+func transcribeMediaParticle(ctx context.Context, depotSvc depot.Service, speechSvc speech.SpeechService, doc *firestore.DocumentSnapshot) string {
 	var mediaParticle particle.FirestoreMediaParticle
 	err := doc.DataTo(&mediaParticle)
 	if err != nil {
 		slog.Error("unable to marshal particle data", "error", err)
-		return
+		return ""
 	}
 
 	particleType, err := particle.ParseParticleType(mediaParticle.Type)
 	if err != nil {
 		slog.Error("invalid particle type", "error", err)
-		return
+		return ""
 	}
 
 	if particleType != particle.TypeMedia {
 		slog.Info("received a particle of type", "particle type", particleType)
-		return
+		return ""
 	}
 
 	downloadURL, err := depotSvc.GetDownloadURL(ctx, mediaParticle.Properties.ObjectId)
 	if err != nil {
 		slog.Error("failed to get download URL", "error", err, "object_id", mediaParticle.Properties.ObjectId)
-		return
+		return ""
 	}
 
 	result, err := speechSvc.Transcribe(ctx, downloadURL)
 	if err != nil {
 		slog.Error("failed to transcribe media", "error", err, "particleID", doc.Ref.ID)
-		return
+		return ""
 	}
 
 	transcript := toFirestoreTranscript(result)
@@ -157,10 +168,11 @@ func transcribeMediaParticle(ctx context.Context, depotSvc depot.Service, speech
 	}, firestore.MergeAll)
 	if err != nil {
 		slog.Error("failed to update transcript in firestore", "error", err, "particleID", doc.Ref.ID)
-		return
+		return ""
 	}
 
 	slog.Info("transcribed media particle", "particleID", doc.Ref.ID)
+	return transcript.Transcript
 }
 
 func toFirestoreTranscript(result *speech.TranscriptResult) particle.FirestoreTranscript {
@@ -197,10 +209,9 @@ func toFirestoreTranscript(result *speech.TranscriptResult) particle.FirestoreTr
 	}
 }
 
-// recordFreemiumUsage bumps the network's daily message counter for non-container
-// particles. Idempotent via the surrounding processed_particles guard: the worker
-// only reaches this path on first-seen particles, so a crash/restart won't
-// double-count.
+// Bumps the network's daily message counter for non-container particles.
+// The surrounding processed_particles guard keeps this idempotent across
+// crashes/restarts.
 func recordFreemiumUsage(ctx context.Context, billingSvc billing.Service, doc *firestore.DocumentSnapshot) {
 	rawType, err := doc.DataAt("type")
 	if err != nil {
@@ -217,7 +228,7 @@ func recordFreemiumUsage(ctx context.Context, billingSvc billing.Service, doc *f
 		slog.Error("invalid particle type", "error", err, "particleID", doc.Ref.ID)
 		return
 	}
-	// Containers (stream/folder) don't count as "messages" for the daily cap.
+	// Containers don't count toward the daily message cap.
 	if particleType == particle.TypeStream || particleType == particle.TypeFolder {
 		return
 	}
@@ -233,31 +244,34 @@ func recordFreemiumUsage(ctx context.Context, billingSvc billing.Service, doc *f
 	}
 }
 
-// updateParentLastChildCreatedAt updates the parent stream's last_child_created_at
-// to the child's actual created_at timestamp, so it stays directly comparable with
-// playback markers (which also store child created_at values).
-func updateParentLastChildCreatedAt(ctx context.Context, doc *firestore.DocumentSnapshot) {
+// Returns nil (and logs) if the path has no parent or the read fails.
+func loadParentParticle(ctx context.Context, doc *firestore.DocumentSnapshot) *firestore.DocumentSnapshot {
 	parentChildrenCollectionRef := doc.Ref.Parent
 	if parentChildrenCollectionRef == nil {
-		return
+		return nil
 	}
-
 	parentParticleDocRef := parentChildrenCollectionRef.Parent
 	if parentParticleDocRef == nil {
 		slog.Error("particle has no parent document", "particleID", doc.Ref.ID)
-		return
+		return nil
 	}
-
 	parentParticleDoc, err := parentParticleDocRef.Get(ctx)
 	if err != nil {
-		slog.Error("failed to get parent particle", "error", err)
+		slog.Error("failed to get parent particle", "error", err, "particleID", doc.Ref.ID)
+		return nil
+	}
+	return parentParticleDoc
+}
+
+// Sets last_child_created_at to the child's created_at so it stays directly
+// comparable with playback markers (which also store child created_at values).
+func updateParentLastChildCreatedAt(ctx context.Context, doc *firestore.DocumentSnapshot, parent *firestore.DocumentSnapshot) {
+	if parent == nil {
 		return
 	}
 
-	slog.Info("parent particle is", "parent particle id", parentParticleDoc.Ref.ID)
-
 	var streamParticle particle.FirestoreStreamParticle
-	if err := parentParticleDoc.DataTo(&streamParticle); err != nil {
+	if err := parent.DataTo(&streamParticle); err != nil {
 		slog.Error("failed to parse stream particle", "error", err)
 		return
 	}
@@ -272,21 +286,159 @@ func updateParentLastChildCreatedAt(ctx context.Context, doc *firestore.Document
 		return
 	}
 
-	// Read the child's created_at — this is the same value that playback markers store
 	childCreatedAt, err := doc.DataAt("created_at")
 	if err != nil {
 		slog.Error("failed to read child created_at", "error", err, "particleID", doc.Ref.ID)
 		return
 	}
 
-	slog.Info("going to update the last_child_created_at for parent particle")
-	_, err = parentParticleDocRef.Update(ctx, []firestore.Update{
+	_, err = parent.Ref.Update(ctx, []firestore.Update{
 		{
 			Path:  "last_child_created_at",
 			Value: childCreatedAt,
 		},
 	})
 	if err != nil {
-		slog.Error("unable to update parent particle `last_child_created_at`")
+		slog.Error("unable to update parent particle `last_child_created_at`", "error", err)
 	}
 }
+
+// Skips containers and particles whose parent isn't a stream — notifications
+// are scoped to stream messages today. The transcript arg becomes the preview
+// body for media particles when available.
+func notifyForParticle(
+	ctx context.Context,
+	notifier *pushnotify.Notifier,
+	humanSvc human.Service,
+	doc *firestore.DocumentSnapshot,
+	parent *firestore.DocumentSnapshot,
+	transcript string,
+) {
+	if parent == nil {
+		slog.Info("notify: skip — no parent", "particleID", doc.Ref.ID)
+		return
+	}
+
+	typeStr, _ := doc.DataAt("type")
+	typeName, _ := typeStr.(string)
+	pType, err := particle.ParseParticleType(typeName)
+	if err != nil {
+		slog.Info("notify: skip — unparseable particle type",
+			"particleID", doc.Ref.ID, "type", typeName, "error", err)
+		return
+	}
+	if pType == particle.TypeStream || pType == particle.TypeFolder {
+		slog.Info("notify: skip — container particle",
+			"particleID", doc.Ref.ID, "type", pType)
+		return
+	}
+
+	var parentStream particle.FirestoreStreamParticle
+	if err := parent.DataTo(&parentStream); err != nil {
+		slog.Error("notify: failed to parse parent stream", "error", err)
+		return
+	}
+	parentType, err := particle.ParseParticleType(parentStream.Type)
+	if err != nil || parentType != particle.TypeStream {
+		slog.Info("notify: skip — parent isn't a stream",
+			"particleID", doc.Ref.ID, "parentType", parentType, "parseErr", err)
+		return
+	}
+
+	networkID, err := particle.NetworkIDFromParticlePath(doc.Ref.Path)
+	if err != nil {
+		slog.Error("notify: failed to derive network id", "error", err, "path", doc.Ref.Path)
+		return
+	}
+
+	senderHumanID := parentStream.CreatedByHumanId
+	if v, err := doc.DataAt("created_by_human_id"); err == nil {
+		if s, ok := v.(string); ok && s != "" {
+			senderHumanID = s
+		}
+	}
+
+	streamName := ""
+	if v, err := parent.DataAt("properties.name"); err == nil {
+		if s, ok := v.(string); ok {
+			streamName = s
+		}
+	}
+
+	senderEmailPrefix := ""
+	if senderHumanID != "" {
+		if sender, err := humanSvc.GetByID(ctx, senderHumanID); err == nil {
+			senderEmailPrefix = sender.EmailPrefix
+		} else {
+			slog.Warn("notify: failed to look up sender", "error", err, "humanID", senderHumanID)
+		}
+	}
+
+	if err := notifier.NotifyParticleCreated(ctx, pushnotify.NotifyInput{
+		NetworkID:         networkID,
+		SenderHumanID:     senderHumanID,
+		SenderEmailPrefix: senderEmailPrefix,
+		ParticleID:        doc.Ref.ID,
+		ParticleKind:      string(pType),
+		StreamID:          parent.Ref.ID,
+		StreamName:        streamName,
+		StreamVisibleTo:   parentStream.VisibleTo,
+		Body:              previewForParticle(pType, doc, transcript),
+	}); err != nil {
+		slog.Error("notify: dispatch failed", "error", err, "particleID", doc.Ref.ID, "networkID", networkID)
+	}
+}
+
+// Builds the notification body. Kept short — lockscreens truncate aggressively.
+// Media prefers transcript text and falls back to a generic "Sent a …" line.
+func previewForParticle(pType particle.ParticleType, doc *firestore.DocumentSnapshot, transcript string) string {
+	switch pType {
+	case particle.TypeText:
+		if v, err := doc.DataAt("properties.content"); err == nil {
+			if s, ok := v.(string); ok {
+				return truncatePreview(s, 140)
+			}
+		}
+		return "Sent a message"
+	case particle.TypeMedia:
+		if t := strings.TrimSpace(transcript); t != "" {
+			return truncatePreview(t, 140)
+		}
+		mime := ""
+		if v, err := doc.DataAt("properties.mime_type"); err == nil {
+			if s, ok := v.(string); ok {
+				mime = s
+			}
+		}
+		if strings.HasPrefix(mime, "video/") {
+			return "Sent a video"
+		}
+		return "Sent a voice message"
+	case particle.TypeFile:
+		return "Sent a file"
+	case particle.TypeQuest:
+		if v, err := doc.DataAt("properties.title"); err == nil {
+			if s, ok := v.(string); ok && s != "" {
+				return "Quest: " + truncatePreview(s, 120)
+			}
+		}
+		return "Added a quest"
+	case particle.TypePaper:
+		if v, err := doc.DataAt("properties.title"); err == nil {
+			if s, ok := v.(string); ok && s != "" {
+				return "Paper: " + truncatePreview(s, 120)
+			}
+		}
+		return "Added a paper"
+	default:
+		return "New activity"
+	}
+}
+
+func truncatePreview(s string, n int) string {
+	s = strings.TrimSpace(s)
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "…"
+}

go/cmd/pusherservice/main.go

@@ -25,29 +25,22 @@ func main() {
 	port := utils.MustGetEnv("PORT")
 	grpcPort := utils.MustGetEnv("GRPC_PORT")
 
-	// Initialize database (for network membership checks)
 	db.Init()
 	defer db.Cleanup()
 
-	// Redis for auth session validation (same DB as orion)
-	authRedis := internal.ConnectAndTestRedis(db.RedisDBAuth)
+	authRedis := internal.ConnectAndTestRedis(db.RedisDBAuth)     // shared with orion
+	pusherRedis := internal.ConnectAndTestRedis(db.RedisDBPusher) // presence + pub/sub
 
-	// Redis for pusher state (presence hashes, pub/sub)
-	pusherRedis := internal.ConnectAndTestRedis(db.RedisDBPusher)
+	sessionReader := auth.NewSessionReader(authRedis)
+	networkReader := network.NewReader(db.Pool())
 
-	// Services
-	sessionReader := auth.NewSessionReader(authRedis) // pusher only validates sessions
-	networkReader := network.NewReader(db.Pool())     // pusher only checks membership
-
-	// Pod identity (use hostname in k8s, which is the pod name)
+	// Hostname is the k8s pod name.
 	podID, err := os.Hostname()
 	if err != nil {
 		podID = fmt.Sprintf("pod-%d", os.Getpid())
 	}
 
-	// Pusher core
 	bridge := pusher.NewRedisBridge(pusherRedis, podID)
-	// Context for graceful shutdown
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
@@ -56,16 +49,11 @@ func main() {
 	bridge.SetHub(hub)
 	server := pusher.NewServer(ctx, hub, bridge, sessionReader)
 
-	// Start hub event loop
 	go hub.Run(ctx)
-
-	// Start Redis Pub/Sub listener
 	go bridge.Listen(ctx)
-
-	// Start pod heartbeat + stale pod cleanup
 	go bridge.Heartbeat(ctx)
 
-	// --- gRPC server (internal, for presence queries) ---
+	// --- gRPC server (internal presence queries) ---
 	grpcListener, err := net.Listen("tcp", fmt.Sprintf("0.0.0.0:%s", grpcPort))
 	if err != nil {
 		slog.Error("failed to listen for gRPC", "port", grpcPort, "error", err)
@@ -104,7 +92,7 @@ func main() {
 	<-sigCh
 
 	slog.Info("shutting down...")
-	cancel() // stops hub, bridge listener, heartbeat
+	cancel()
 
 	grpcServer.GracefulStop()
 	httpServer.Shutdown(context.Background())

go/cmd/transcodebackfill/main.go

@@ -1,12 +1,6 @@
-// transcodebackfill is a one-shot job that scans every doc under the
-// "children" Firestore collection group, identifies media particles missing a
-// transcoded variant, and re-runs the transcode + upload + Firestore-update
-// flow against the configured GCS bucket. Idempotent — re-running the Job
-// after a partial failure picks up where it left off via the existing
-// `transcoded_object_id != ""` short-circuit inside particle.Transcode.
-//
-// Intended to back-fill the production iOS playback backlog created before we
-// launched mobile / particle processor worker only transcodes new media.
+// transcodebackfill walks every doc under the "children" collection group and
+// re-runs transcode for media particles missing a transcoded variant.
+// Idempotent: particle.Transcode short-circuits on transcoded_object_id != "".
 package main
 
 import (
@@ -104,9 +98,7 @@ func run(ctx context.Context, fs *firestore.Client, depotSvc depot.Service) (sta
 
 		s.scanned++
 
-		// Cheap pre-filter: most docs under the "children" collection group
-		// are not media particles. DataAt avoids unmarshalling the full
-		// document for those.
+		// DataAt avoids unmarshalling the full doc; most children aren't media.
 		rawType, err := doc.DataAt("type")
 		if err != nil {
 			s.skippedNonMedia++