Caching, Queues & Real-time¶

Three problems that always travel together: short-lived shared state (cache), background work (queues), and live bidirectional connections (real-time). The portfolio's defaults are Redis + BullMQ + Socket.IO — with a handful of deliberate exceptions.

Redis¶

What it is. In-memory key-value store with optional persistence. Used for caching, session storage, pub/sub, distributed locks, rate-limit counters, and as the broker for BullMQ.

Why we use it. Fast (microsecond latency), tiny ops footprint (one container), single tool that handles 5+ jobs.

Image: redis:7-alpine everywhere.

Used in: ~15 apps including Automotive-Repair-Diagnosis-AI, Boomer_AI, Ecom-Sales (job queue is pg-boss instead, but Redis is still present for cache), FamilyChat, GoGreen-AI-Concierge, GoGreen-DOC-AI, GoGreen-SmartForms, GoGreen-Workflow-Hub, GoGreenMarketing, MangyDogCoffee, MyPollingApp, OpenSentinel, PolyMarketAI, Recruiting_AI, Salon-Digital-Assistant, SCO-Digital-Assistant, TimeSheetAI, Tutor_AI, Voting_NewAndImproved.

Apps that skip Redis: SellMe* family (single-binary SQLite path), AscendOne (desktop), ChoreAndMoreTracker (desktop).

Comparison alternatives (not used): - KeyDB / Dragonfly — Redis-protocol-compatible, multithreaded forks. Higher throughput. Not needed at portfolio scale. - Memcached — older, simpler. Loses out to Redis on data structures. - Upstash Redis / Vercel KV / Cloudflare KV — managed Redis-like services. Not used; self-hosted Redis on the IONOS VPS is the default.

BullMQ¶

What it is. Robust Node.js job queue backed by Redis. Successor to Bull. Features: delayed jobs, repeatable cron, retries with backoff, rate limiting, job priorities, scheduled jobs, and bull-board for a web UI.

Used in: - MangyDogCoffee — queue for knowledge processing. - OpenSentinel — central queue for agent jobs, MCP calls, scraping. - Recruiting_AI-Docker — 9 distinct job queues (bull-board UI exposed). - SCO-Digital-Assistant — knowledge / RAG indexing jobs. - Salon-Digital-Assistant — same as SCO. - GoGreen-AI-Concierge — knowledge processing workers. - GoGreen-Workflow-Hub — the Workflow Hub itself runs on BullMQ to execute multi-step user workflows. - FamilyChat — message processing, transcription, push delivery.

Pattern. A separate worker process consumes from the queue (so the web tier stays responsive). Common to ship the worker as a sidecar container in docker-compose.yml.

pg-boss¶

What it is. Postgres-native job queue. Uses Postgres LISTEN/NOTIFY and a pgboss schema instead of Redis. Persistence, retries, throttling, cron — same shape as BullMQ but no Redis dependency.

Used in: - Ecom-Sales — chose pg-boss explicitly to drop a Redis container. - GogreenSellerAI — same pattern. - Boomer_AI-Docker — pg-boss for background jobs.

Tradeoffs. Postgres becomes both the data store and the queue — simpler infra, but heavier load on Postgres. Throughput ceiling lower than BullMQ for very high job rates; well above what these apps need.

Celery (Python)¶

What it is. The Python world's BullMQ. Distributed task queue with Redis or RabbitMQ broker, beat scheduler, flower UI.

Used in: - GoGreen-SmartForms — async ingestion + form processing. - PolyMarketAI — scheduled scraping, model retraining, news ingestion.

arq¶

What it is. Async-first Python job queue. Uses Redis. Lighter than Celery, native asyncio.

Used in: GoGreen-DOC-AI.

Why arq over Celery here. The DOC-AI service is async-throughout (FastAPI + asyncpg + LangChain async); arq fits that style.

Socket.IO¶

What it is. Real-time framework over WebSocket with HTTP long-polling fallback. Rooms, namespaces, automatic reconnection, ack callbacks. Cluster-aware via Redis adapter.

Used in: - FamilyChat — chat, typing indicators, presence. - GoGreen-AI-Concierge — chat + real-time knowledge-processing status. - GoGreen-Workflow-Hub — live workflow execution updates. - MangyDogCoffee (via WebSockets) — voice / chat.

Why Socket.IO over raw ws. Multi-room broadcast, fallbacks, reconnect logic, server-side adapter for horizontal scaling. Worth the extra protocol overhead for chat.

Native WebSockets (`ws` library)¶

What it is. Raw RFC 6455 WebSockets. Lower overhead, no automatic rooms or reconnection.

Used in: - Boomer_AI — voice realtime channel. - NaggingWifeAI — same. - Salon-Digital-Assistant, SCO-Digital-Assistant — same pattern. - MangyDogCoffee — voice realtime alongside Socket.IO chat. - Recruiting_AI, Sales_AI_App, SellMe* family, Tutor_AI — voice / streaming. - GoGreenPaperlessInitiative — long-lived push channel.

When raw ws is the right pick. Voice / OpenAI Realtime API integration — those are RFC-6455 connections, not Socket.IO. Anything where you control both ends and don't need rooms.

Server-Sent Events (SSE)¶

What it is. One-way HTTP streaming from server to client. Browser-native (EventSource), reconnects automatically, plays nicely with HTTP/2.

Used (implicitly) in: Vercel AI SDK in GoGreen-Workflow-Hub, plus most LLM-token-streaming endpoints across the portfolio. Lightweight alternative to WebSockets when you only need server → client.

tRPC¶

What it is. End-to-end type-safe RPC for TypeScript. The client gets the types of every server procedure for free. Subscriptions over WebSocket are supported (used as a real-time mechanism).

Used in: Ecom-Sales, GogreenSellerAI.

Tradeoff vs. REST. Rapid iteration when client and server are in the same repo; harder to expose to non-TS consumers. The portfolio uses REST elsewhere.

Real-time on the client¶

Library	Where
`socket.io-client`	FamilyChat, Concierge, Workflow-Hub web UIs
Native `WebSocket`	Voice apps, OpenAI Realtime
`EventSource` (SSE)	LLM streaming UIs
`@trpc/client` + `@trpc/react-query`	Ecom-Sales, GogreenSellerAI

What NOT to reach for¶

Tool	Why not
Kafka	No app has the throughput to justify it. BullMQ + Redis covers everything below ~10K jobs/sec.
RabbitMQ	Same — BullMQ / pg-boss fill its niche with less ops.
NATS	No use case in the portfolio.
AWS SQS / Pub/Sub	The portfolio is self-hosted on IONOS — no managed-cloud queues.
Inngest / Trigger.dev / Temporal	Workflow engines. GoGreen-Workflow-Hub plays this role internally; no need for an external one.

Push notifications (server-initiated, distinct from in-app realtime)¶

Web Push (VAPID) — FamilyChat, plus Boomer_AI, NaggingWifeAI, Salon, SCO via web channels.
Firebase Admin — Boomer_AI, Ecom-Sales, GogreenSellerAI for mobile FCM push.
OS-native (Electron) — sent through Firebase Admin from the server.

See Integrations-Comms.md for the integration side.

Cache patterns seen in the codebase¶

Per-request memoization — in-process Map / LRU; embedding lookups in Boomer_AI use an LRU.
Redis-cached Postgres reads — TanStack Query handles client-side, Redis handles server-side.
Embedding cache — Tutor_AI keeps the last 500 embeddings in an in-process LRU; saves OpenAI calls.
Rate-limit counters — Redis INCR + EXPIRE is the standard pattern (used in TimeSheetAI, OpenSentinel).

Decision guide¶

Need a cache?                                          Redis.
Need background jobs in a TypeScript app?              BullMQ (default) or pg-boss (drop Redis).
Need background jobs in a Python app?                  arq (async) or Celery (mature).
Need a chat / multi-room real-time channel?           Socket.IO.
Need a voice / OpenAI Realtime channel?               Raw ws.
Just streaming LLM tokens to the browser?             SSE.
Need type-safe RPC, single TS team?                   tRPC.
"Should we add Kafka / RabbitMQ?"                     Probably no — start with BullMQ.