@opengroundplan/core 0.1.1

package/catalog/sources/realtime-messaging.yaml

@@ -0,0 +1,787 @@
+# realtime-messaging.yaml
+#
+# Groundplan template source catalog — category: realtime-messaging
+# Research date: 2026-07-18
+#
+# ADVERSARIAL RE-VERIFICATION — 2026-07-18 (second pass, independent)
+#
+#   Every one of the 18 entries was re-checked against primary sources. The
+#   GitHub REST API was rate-limited (60/hr, unauthenticated, exhausted) for the
+#   whole of this pass, so verification used the stronger primary sources
+#   directly rather than waiting on it:
+#     license  — the actual LICENSE text on raw.githubusercontent.com. This is
+#                stronger than `license.spdx_id`, which returns NOASSERTION for
+#                four of these repos and is a heuristic match in the rest.
+#     stars    — exact `title` attribute of the repo-page star counter.
+#     archived — repo page checked for the "Public archive" banner (0/18 hit).
+#     lastCommit — `/commits/{branch}.atom` latest entry.
+#
+#   RESULT OF THE LICENSE GATE: all 18 confirmed, 0 mismatches, 0 drops.
+#   16 vendorable / 2 reference-only. No repo had a hidden EE or dual-license
+#   file (root listings checked for LICENSE*/COPYING/NOTICE variants; nested
+#   probes on hatchet ee/, trigger.dev packages/, socket.io packages/, colyseus
+#   packages/ found nothing more restrictive than the root).
+#   All 18 URLs return 200. All 18 pushed within ~2 months, so every
+#   `maintained: true` holds. Star counts all within 0.01% of recorded.
+#
+#   Defects found and fixed in this pass (none were license-class errors):
+#     - Hangfire spdx was LGPL-3.0-only; LICENSE.md says "or (at your option)
+#       any later version" => corrected to LGPL-3.0-or-later.
+#     - coder/websocket examples are at internal/examples/, not examples/.
+#     - sse-starlette 02_message_broadcasting.py does not exist; it is
+#       02_broadcasting.py.
+#     - trigger.dev top-level references/ is gone (now ai/references/, prose).
+#     - nats.go and centrifugo ship no NOTICE file; the Apache-2.0 attribution
+#       advice was overstated and has been corrected per repo.
+#     - soketi drop-note staleness was wrong (2023-08-20, not 2025-03-03).
+#     - windmill is dual Apache-2.0/AGPLv3 per file, not uniformly AGPL-3.0.
+#     - layer-id collisions: realtime-sse vs realtime-sse-*, and
+#       realtime-rooms-presence vs realtime-presence; Hangfire mislabelled
+#       queue-postgres-native despite being SQL-Server-first.
+#
+#   Spot-checked for fabrication: all 14 cited socket.io example dirs exist and
+#   the "37 apps" count is exact; all 12 cited temporal samples exist; watermill
+#   _examples//components/, nats jetstream//micro//kv.go, hatchet examples//sdks/,
+#   kafka config/, and all 4 cited river example test files exist.
+#
+# ORIGINAL VERIFICATION NOTES (first pass)
+#   Every `stars`, `lastCommit` and `spdx` value below was read from a GitHub
+#   primary source on 2026-07-18. No figure comes from memory, a blog post, or a
+#   README badge. (Memory was measurably wrong during this research: recalled
+#   star counts for apache/kafka and coder/websocket were off by ~2,400 and
+#   ~1,000 respectively, and were discarded in favour of fetched values.)
+#
+#   Two verification paths were used, both primary:
+#     `spdxSource: github-api`  — https://api.github.com/repos/{owner}/{repo},
+#        fields stargazers_count / license.spdx_id / pushed_at / archived.
+#     `spdxSource: LICENSE-file` — used when the API returned NOASSERTION, and
+#        for four repos verified after the unauthenticated API rate limit (60/hr)
+#        was exhausted. For those, stars came from the exact `title` attribute of
+#        the repo page star counter on github.com, lastCommit from the
+#        `/commits/{branch}.atom` feed, and the SPDX id from reading the actual
+#        LICENSE text on raw.githubusercontent.com. Affected entries:
+#        coder/websocket, sysid/sse-starlette, websockets/ws, apache/kafka.
+#        Their `lastCommit` is therefore latest-commit time, not `pushed_at`;
+#        the two differ by seconds-to-minutes and do not affect staleness.
+#
+#   NOASSERTION is never treated as permissive by default. It appeared on four
+#   repos here and resolved to three different licenses — BSD-3-Clause (celery),
+#   MIT (temporal samples), LGPL-3.0 (Hangfire) and SSPL-1.0 (inngest, dropped).
+#
+#   licenseClass gate:
+#     vendorable     — MIT, Apache-2.0, BSD-2/3, ISC, Unlicense, CC0, 0BSD.
+#                      Copy + adapt permitted. Apache-2.0 and BSD-3 require the
+#                      copyright/NOTICE text to travel with any copied file.
+#     reference-only — MPL-2.0, LGPL, EPL. Read for ideas; do not copy files.
+#     excluded       — GPL, AGPL, SSPL, BUSL, source-available, or unlicensed.
+#
+#   `maintained: false` is set when last push is >18 months old, regardless of
+#   stars. All entries below were pushed within the last 3 months.
+
+category: realtime-messaging
+
+sources:
+
+  # ---------------------------------------------------------------- simple ---
+
+  - name: coder/websocket
+    url: https://github.com/coder/websocket
+    stars: 5349
+    spdx: ISC
+    spdxSource: LICENSE-file   # LICENSE.txt is verbatim ISC ("Permission to use, copy, modify, and distribute ... with or without fee")
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-06-15T03:25:28Z"
+    stack: go
+    complexity: simple
+    whatToBorrow: >-
+      The smallest credible WebSocket baseline in Go. Vendor the
+      `internal/examples/echo` server (echoServer.ServeHTTP + websocket.Accept +
+      rate limiting via golang.org/x/time/rate) and `internal/examples/chat`
+      (subscriber fan-out with a buffered per-client channel and slow-client
+      eviction). Note the path: they live under `internal/` with their own
+      go.mod, so they are copy-and-adapt sources, not importable packages. The
+      `wsjson.Read`/`wsjson.Write` helpers plus first-class context.Context on
+      every call are the pattern to copy for cancellation and read deadlines.
+      Zero dependencies, so it strips down cleanly into a starter.
+    whatToAvoid: >-
+      Import path moved from nhooyr.io/websocket to github.com/coder/websocket —
+      any tutorial or snippet older than 2024 uses the dead path. The chat
+      example's in-memory subscriber map is single-process only; do not ship it
+      as-is behind more than one replica without a Redis/NATS fan-out layer.
+    proposedLayerIds:
+      - realtime-websocket-go
+      - realtime-websocket-echo
+      - realtime-chat-fanout
+
+  - name: sysid/sse-starlette
+    url: https://github.com/sysid/sse-starlette
+    stars: 841
+    spdx: BSD-3-Clause
+    spdxSource: LICENSE-file   # BSD text incl. the third "Neither the name ... endorse or promote" clause
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-12T20:34:25Z"
+    stack: python-fastapi
+    complexity: simple
+    whatToBorrow: >-
+      The reference way to do Server-Sent Events on FastAPI/Starlette.
+      `EventSourceResponse` handles the three things hand-rolled SSE always gets
+      wrong: automatic keepalive pings (default 15s, `ping_message_factory` to
+      customise), client-disconnect detection via `await
+      request.is_disconnected()`, and cooperative graceful shutdown with a grace
+      period so generators can emit a farewell event. Adapt the numbered
+      examples: `01_basic_sse.py`, `02_broadcasting.py` (multi-client fan-out),
+      `03_database_streaming.py` (thread-safe DB streaming), and
+      `07_cooperative_shutdown.py` (the graceful-shutdown path described above).
+      `ServerSentEvent`/`JSONServerSentEvent` give typed data/event/id/retry
+      fields instead of manual string formatting.
+    whatToAvoid: >-
+      SSE is unidirectional — do not template it where the app actually needs
+      bidirectional messaging. Buffering proxies (nginx `proxy_buffering on`,
+      some CDNs) silently break SSE, so the template must ship the
+      `X-Accel-Buffering: no` header and a documented proxy config. Single
+      maintainer project; keep the dependency surface thin so it is replaceable.
+    proposedLayerIds:
+      - realtime-sse-fastapi
+      - realtime-sse-broadcast
+      - realtime-python-async
+
+  - name: websockets/ws
+    url: https://github.com/websockets/ws
+    stars: 22786
+    spdx: MIT
+    spdxSource: LICENSE-file   # verbatim MIT ("Permission is hereby granted, free of charge ...")
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-14T16:37:58Z"
+    stack: nodejs
+    complexity: simple
+    whatToBorrow: >-
+      The unopinionated Node WebSocket primitive that almost every higher-level
+      library sits on. Borrow the documented recipes rather than the library
+      internals: the `examples/` server-side broadcast loop, the HTTP-upgrade +
+      authentication handshake pattern (`server.on('upgrade')` with the auth
+      check before `wss.handleUpgrade`), and — most importantly — the
+      ping/pong liveness heartbeat from the README ("How to detect and close
+      broken connections"), which is the single most commonly missing piece in
+      hand-written WS starters. `perMessageDeflate` config and `maxPayload` are
+      the tunables to surface in the template config layer.
+    whatToAvoid: >-
+      No reconnection, no rooms, no ack/retry, no horizontal scale — all of that
+      is the app's problem. Do not enable `perMessageDeflate` by default; it is
+      documented as a significant memory/throughput cost. Teams that need rooms
+      and fallbacks should be steered to Socket.IO or Centrifugo instead of
+      growing a bespoke framework on top of ws.
+    proposedLayerIds:
+      - realtime-websocket-node
+      - realtime-websocket-heartbeat
+      - realtime-ws-auth-upgrade
+
+  # -------------------------------------------------------------- standard ---
+
+  - name: socketio/socket.io
+    url: https://github.com/socketio/socket.io
+    stars: 63158
+    spdx: MIT
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-16T08:35:49Z"
+    stack: nodejs-typescript
+    complexity: standard
+    whatToBorrow: >-
+      The `examples/` directory is effectively a free template library — 37 apps
+      that map almost 1:1 onto Groundplan layers. Highest value:
+      `nextjs-app-router` and `nextjs-pages-router` (the custom-server wiring
+      teams always get wrong), `nestjs-example`, `private-messaging` (rooms +
+      session persistence + per-user delivery), `connection-state-recovery-example`
+      (server-side buffering across brief disconnects), `express-session-example`
+      and `passport-jwt-example` (sharing HTTP auth with the socket handshake),
+      `cluster-engine-redis` / `postgres-adapter-example` (horizontal fan-out),
+      and the `cluster-nginx` / `cluster-haproxy` / `cluster-traefik` configs for
+      sticky-session load balancing. Also `webtransport` and `custom-parsers`.
+    whatToAvoid: >-
+      Socket.IO is a protocol, not raw WebSocket — a plain `WebSocket` client
+      cannot talk to it, which surprises teams integrating non-JS clients.
+      Sticky sessions are mandatory when HTTP long-polling fallback is enabled;
+      shipping a multi-replica template without the adapter plus sticky LB
+      config produces intermittent, hard-to-debug failures. The long-polling
+      fallback carries real overhead — consider `transports: ['websocket']` as
+      the template default. Client and server versions are coupled across major
+      versions.
+    proposedLayerIds:
+      - realtime-socketio-server
+      - realtime-socketio-nextjs
+      - realtime-socketio-redis-adapter
+      - realtime-rooms
+      - realtime-presence
+      - realtime-ws-auth-upgrade
+
+  - name: colyseus/colyseus
+    url: https://github.com/colyseus/colyseus
+    stars: 7097
+    spdx: MIT
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18T08:24:19Z"
+    stack: nodejs-typescript
+    complexity: standard
+    whatToBorrow: >-
+      The best open-source model for authoritative, stateful realtime sessions.
+      Borrow the three-part architecture: a `Room` subclass owning server-side
+      lifecycle (`onCreate`/`onJoin`/`onMessage`/`onLeave`/`onDispose`), a
+      `Schema` state class whose annotated fields are automatically delta-
+      compressed and binary-encoded to clients, and the built-in matchmaker
+      (`joinOrCreate`, filtering, queuing, reconnection tokens). `npm create
+      colyseus-app@latest` emits the canonical project skeleton to diff against.
+      The state-sync-instead-of-manual-message-plumbing idea generalises well
+      beyond games — collaborative editors, live dashboards, auction rooms.
+    whatToAvoid: >-
+      State lives in the room process, so a room is a single point of failure and
+      scale-out is per-room, not per-request; persistence is entirely your job.
+      The `@type()` Schema decorators require `experimentalDecorators` and are
+      easy to mis-annotate — a missing decorator silently stops syncing that
+      field. Heavily game-shaped vocabulary, which reads oddly in non-game
+      products. Migrations across Colyseus major versions have historically been
+      non-trivial.
+    proposedLayerIds:
+      - realtime-multiplayer-colyseus
+      - realtime-room-state-sync
+      - realtime-matchmaking
+      - realtime-presence
+
+  - name: taskforcesh/bullmq
+    url: https://github.com/taskforcesh/bullmq
+    stars: 9152
+    spdx: MIT
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18T16:24:08Z"
+    stack: nodejs-typescript
+    complexity: standard
+    whatToBorrow: >-
+      The default job queue for Node and the right `queue-*` baseline. Borrow the
+      Queue/Worker/QueueEvents triad as separate process entry points, the
+      `FlowProducer` parent/child dependency graph (fan-out then join — the
+      cleanest OSS take on job DAGs), repeatable/cron jobs, per-queue rate
+      limiting, deduplication, and sandboxed processors (worker file path instead
+      of an inline fn) so a crashing job cannot take the main loop down. The
+      Lua-script atomicity approach is worth reading even if you never copy it.
+      Ports exist for Python, Rust, Elixir and PHP, so the layer concept carries
+      across stacks.
+    whatToAvoid: >-
+      Redis-only, and it needs `maxmemory-policy: noeviction` — an eviction
+      policy on a shared Redis silently destroys jobs. Job payloads must stay
+      small (they are serialised into Redis); pass an id, not a blob. The most
+      attractive features — observables, groups, group rate limiting — are in
+      the commercial BullMQ-Pro tier, so a template must not be designed around
+      them. Taskforce.sh is the paid dashboard; pair the OSS template with a
+      self-hosted board instead of assuming it.
+    proposedLayerIds:
+      - queue-bullmq-redis
+      - queue-worker-process
+      - queue-flows-dag
+      - queue-cron-repeatable
+      - queue-dashboard
+
+  - name: ThreeDotsLabs/watermill
+    url: https://github.com/ThreeDotsLabs/watermill
+    stars: 9801
+    spdx: MIT
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-05-14T08:52:09Z"
+    stack: go
+    complexity: standard
+    whatToBorrow: >-
+      The broker-agnostic abstraction that lets one Groundplan template target many
+      backends. The `message.Router` with middleware (retry, poison queue,
+      correlation id, recovery) is the piece to copy — it turns each broker into
+      a swappable `Publisher`/`Subscriber` pair behind one handler signature.
+      13+ implementations exist (Kafka, NATS JetStream, Redis Streams, AMQP,
+      SQL/Postgres, Google Pub/Sub, AWS SNS/SQS), so `broker-*` layers can share
+      handler code. `_examples/` is unusually well curated: basic (first app,
+      realtime feed, metrics, CQRS), per-backend getting-started dirs, and
+      real-world ones covering exactly-once delivery, webhooks, database sync
+      and event logging. The `components/` dir has ready CQRS and outbox pieces.
+    whatToAvoid: >-
+      An abstraction over brokers necessarily leaks — Kafka partition/offset
+      semantics and AMQP routing keys do not survive the common interface, so
+      "swap the backend" is only true for simple pub/sub. Adds a dependency layer
+      over already-good native clients; for a single-broker project, using
+      nats.go or franz-go directly is often the better template. Lower commit
+      cadence than the other entries here (last push 2026-05-14) — mature rather
+      than abandoned, but confirm before pinning.
+    proposedLayerIds:
+      - pubsub-watermill-go
+      - broker-kafka
+      - broker-nats-jetstream
+      - broker-redis-streams
+      - broker-rabbitmq-amqp
+      - pattern-cqrs
+      - pattern-transactional-outbox
+
+  - name: hibiken/asynq
+    url: https://github.com/hibiken/asynq
+    stars: 13528
+    spdx: MIT
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-06-22T23:22:43Z"
+    stack: go
+    complexity: standard
+    whatToBorrow: >-
+      The Go analogue of BullMQ/Sidekiq and a clean `queue-*` template for Go.
+      Borrow the `asynq.Client.Enqueue` + `asynq.ServeMux` handler-routing split
+      (it deliberately mirrors net/http, so the mental model is free), weighted
+      and strict priority queues, per-task timeout/deadline, `asynq.Unique` for
+      dedup, and the crash-recovery guarantee (in-flight tasks are requeued when
+      a worker dies). Asynqmon ships a web UI and there is a CLI plus Prometheus
+      integration — a complete ops story to template.
+    whatToAvoid: >-
+      Still pre-1.0 (`v0.x`); the README explicitly warns the public API can
+      change without a major bump, so pin exact versions in generated projects.
+      Redis-only with the same noeviction requirement as BullMQ. Development
+      cadence is moderate and largely single-maintainer — for a Postgres-backed
+      shop, River is the more actively developed option (but check its MPL-2.0
+      class before copying).
+    proposedLayerIds:
+      - queue-asynq-go
+      - queue-worker-process
+      - queue-priority-queues
+      - queue-dashboard
+
+  - name: nats-io/nats.go
+    url: https://github.com/nats-io/nats.go
+    stars: 6694
+    spdx: Apache-2.0
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-13T03:09:00Z"
+    stack: go
+    complexity: standard
+    whatToBorrow: >-
+      The lightest credible message broker to template — a single ~15MB server
+      binary with no ZooKeeper/Kraft ceremony, which makes it the right default
+      `broker-*` layer for teams that do not need Kafka. Borrow from the
+      `jetstream/` subpackage: stream and consumer creation as code (so topology
+      is version-controlled, not clicked), durable pull consumers with explicit
+      ack/nak/term, and the KV (`kv.go`) and object store APIs which cover
+      config-watch and blob cases without adding another datastore. The `micro/`
+      subpackage gives request/reply services with built-in discovery and stats —
+      a genuinely different, and simpler, take on service RPC. `examples/` plus
+      the cross-client "NATS by example" collection are the adaptation targets.
+    whatToAvoid: >-
+      Core NATS is at-most-once fire-and-forget with no persistence — durability
+      only exists once JetStream is explicitly enabled, and conflating the two is
+      the classic NATS production incident. `micro/` is still labelled beta.
+      Apache-2.0 attribution: this repo ships NO NOTICE file (verified 404), so
+      the obligation is to keep the per-file copyright headers and include the
+      Apache-2.0 text — do not go looking for a NOTICE to propagate.
+      Smaller managed-hosting ecosystem than Kafka, so self-hosting is the
+      realistic assumption for generated projects.
+    proposedLayerIds:
+      - broker-nats-jetstream
+      - broker-nats-core
+      - broker-kv-store
+      - service-rpc-request-reply
+      - pattern-event-driven
+
+  # ---------------------------------------------------------- professional ---
+
+  - name: centrifugal/centrifugo
+    url: https://github.com/centrifugal/centrifugo
+    stars: 10527
+    spdx: Apache-2.0
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-15T04:29:40Z"
+    stack: go-standalone-server
+    complexity: professional
+    whatToBorrow: >-
+      A self-hosted Pusher/Ably replacement that runs as a sidecar, which means
+      the realtime layer stops being coupled to your app language. This is the
+      strongest `realtime-*` option for polyglot backends. Borrow the two auth
+      models: short-lived JWT connection tokens (backend mints, Centrifugo
+      verifies — no shared session store), and the proxy model where Centrifugo
+      calls your backend on connect/subscribe/publish so authorisation stays in
+      your app. Transport negotiation covers WebSocket, HTTP-streaming, SSE,
+      GRPC and experimental WebTransport behind one client API. Ship the
+      `docker-compose.yml` plus a config file as the template's realtime layer,
+      and use the server-side channel/namespace config for per-feature rules.
+    whatToAvoid: >-
+      It is a separate service to run, monitor and upgrade — real operational
+      weight that a small app does not need over plain ws or Socket.IO.
+      Presence and history require Redis, so the "one binary" story is only true
+      for the simplest deployment. The channel-namespace configuration is
+      powerful but has a genuine learning curve, and misconfigured namespace
+      permissions are a security footgun. Apache-2.0 attribution: this repo ships
+      NO NOTICE file (verified 404) — retain the Apache-2.0 text and per-file
+      copyright headers instead. (apache/kafka, by contrast, does have a NOTICE
+      that must travel with anything copied from it.)
+    proposedLayerIds:
+      - realtime-centrifugo
+      - realtime-jwt-connection-token
+      - realtime-sse-centrifugo
+      - realtime-presence
+      - realtime-sidecar-service
+
+  - name: supabase/realtime
+    url: https://github.com/supabase/realtime
+    stars: 7605
+    spdx: Apache-2.0
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17T22:17:47Z"
+    stack: elixir-phoenix
+    complexity: professional
+    whatToBorrow: >-
+      The clearest production reference for the three primitives every realtime
+      product re-implements: Broadcast (ephemeral low-latency client-to-client),
+      Presence (CRDT-backed shared online state that self-heals across nodes),
+      and Postgres Changes (logical replication decoded and fanned out to clients
+      with row-level authorisation applied). Even for a non-Elixir template, the
+      channel authorisation model and the Postgres-CDC-to-WebSocket pipeline are
+      the design to copy. Operationally it is unusually well documented for an
+      OSS server: `ENVS.md` for configuration, `ERROR_CODES.md`, and
+      `OBSERVABILITY_METRICS.md` — vendor that documentation discipline. Ships
+      `compose.yml`, `compose.dbs.yml` and `compose.tests.yml`.
+    whatToAvoid: >-
+      Elixir/Phoenix/OTP is a real operational skill dependency; most teams
+      should consume this via hosted Supabase rather than self-host it, and a
+      Groundplan template should say so plainly. Postgres Changes does not scale
+      indefinitely — it is documented as the feature to move off (toward
+      Broadcast-from-database triggers) under load, so do not template it as the
+      default event path for high write volume. Tightly shaped around Supabase's
+      own auth (`auth.uid()`, RLS) and awkward to decouple from it.
+    proposedLayerIds:
+      - realtime-supabase
+      - realtime-presence
+      - realtime-postgres-cdc
+      - realtime-broadcast-channels
+      - db-postgres-logical-replication
+
+  - name: celery/celery
+    url: https://github.com/celery/celery
+    stars: 28699
+    spdx: BSD-3-Clause
+    spdxSource: LICENSE-file   # API returned NOASSERTION; LICENSE reads "BSD License (3 Clause)"
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-16T06:44:39Z"
+    stack: python
+    complexity: professional
+    whatToBorrow: >-
+      The incumbent Python task queue and the realistic `queue-celery-python`
+      layer. Borrow the conventional project layout (a `celery.py` app module,
+      `tasks.py` per Django/Flask app, autodiscovery), and the production
+      settings that starter projects always omit: `task_acks_late=True` with
+      `task_reject_on_worker_lost` for at-least-once semantics,
+      `worker_prefetch_multiplier=1` for long tasks, explicit
+      `task_time_limit`/`soft_time_limit`, `task_routes` for per-queue routing,
+      and Celery Beat for periodic work. Canvas primitives (`chain`, `group`,
+      `chord`) are the DAG story. Pairs with RabbitMQ or Redis as broker.
+    whatToAvoid: >-
+      Heavy, old, and configuration-dense — a large surface of settings with
+      unsafe-by-default behaviour (late acks off, generous prefetch) that bites
+      in production. The pickle serializer must stay disabled (`task_serializer='json'`)
+      or task payloads become an RCE vector. Historically weak Windows support.
+      For a greenfield Python service, consider whether Dramatiq, arq or a
+      Postgres-backed queue is a better template default, and reserve Celery for
+      teams already invested in it.
+    proposedLayerIds:
+      - queue-celery-python
+      - queue-celery-beat-scheduler
+      - broker-rabbitmq-amqp
+      - broker-redis-streams
+      - queue-worker-process
+      - queue-dashboard
+
+  - name: temporalio/samples-typescript
+    url: https://github.com/temporalio/samples-typescript
+    stars: 462
+    spdx: MIT
+    spdxSource: LICENSE-file   # API returned NOASSERTION; LICENSE reads "MIT License"
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17T20:02:25Z"
+    stack: nodejs-typescript
+    complexity: professional
+    whatToBorrow: >-
+      Low stars but the highest template density in this category: 60+ runnable
+      sample projects, MIT, maintained by Temporal itself. The canonical layout —
+      `src/workflows.ts`, `src/activities.ts`, `src/worker.ts`, `src/client.ts` —
+      is exactly the skeleton a `workflow-temporal` layer should emit. Adapt
+      `hello-world` as the base, then layer specific samples: `signals-queries`
+      (external input and state read-out), `activities-cancellation-heartbeating`
+      (long tasks that report progress and cancel cleanly), `child-workflows`,
+      `continue-as-new`, `schedules`, `patching-api` (versioning long-running
+      workflows — the hardest real problem), `interceptors-opentelemetry`,
+      `custom-logger`, and `hello-world-mtls` for Temporal Cloud auth. Full-stack
+      references exist too: `nextjs-ecommerce-oneclick`, `food-delivery`.
+    whatToAvoid: >-
+      Requires a Temporal cluster (Postgres/Cassandra + history, matching,
+      frontend and worker services) — genuinely heavy infrastructure, so a
+      generated project must ship a docker-compose dev cluster or point at
+      Temporal Cloud. Workflow code must be deterministic: no `Date.now()`, no
+      `Math.random()`, no direct I/O, which is a real constraint developers hit
+      immediately and must be documented in the template. The samples are
+      individually small and not wired for production concerns like config or
+      secrets — take the shape, add your own config layer. Note the samples repo
+      is MIT while the `temporalio/temporal` server is separately licensed;
+      verify per repo before copying.
+    proposedLayerIds:
+      - workflow-temporal
+      - workflow-durable-execution
+      - workflow-signals-queries
+      - workflow-versioning
+      - observability-opentelemetry
+
+  - name: triggerdotdev/trigger.dev
+    url: https://github.com/triggerdotdev/trigger.dev
+    stars: 15682
+    spdx: Apache-2.0
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18T19:16:19Z"
+    stack: nodejs-typescript
+    complexity: professional
+    whatToBorrow: >-
+      Durable, long-running background tasks defined in plain TypeScript, with
+      retries, queues, concurrency control and observability — and, unusually for
+      this space, genuinely Apache-2.0 rather than SSPL/BUSL. Borrow the task
+      authoring ergonomics (a `task()` definition with typed payload plus
+      `retry`, `queue` and `machine` options colocated with the function) and the
+      `trigger.config.ts` project-config convention. The `hosting/` and `docker/`
+      directories plus the official Helm chart are a complete self-host
+      reference. The old top-level `references/` directory of runnable example
+      projects is gone — what remains is `ai/references/` (repo.md, tests.md,
+      migrations.md), which is architecture/testing prose, not sample apps, so
+      source the task examples from the docs site instead. Turbo + pnpm monorepo
+      layout under `apps/` (webapp, supervisor) and `packages/` is itself a
+      reusable pattern.
+    whatToAvoid: >-
+      The self-hosted stack is not light — Postgres, Redis, object storage and a
+      container runtime for task isolation; a "simple" template this is not, and
+      the OSS/cloud feature parity gap should be checked before promising
+      self-host. Fast-moving with breaking changes across major versions (v2 to
+      v3 was a rewrite), so pin versions in generated projects. The vendor
+      operates the hosted product, so weigh lock-in of task-definition syntax
+      even though the license itself is permissive.
+    proposedLayerIds:
+      - workflow-trigger-dev
+      - workflow-durable-execution
+      - queue-concurrency-control
+      - deploy-docker-compose
+      - deploy-helm-chart
+
+  - name: hatchet-dev/hatchet
+    url: https://github.com/hatchet-dev/hatchet
+    stars: 7523
+    spdx: MIT
+    spdxSource: github-api
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18T07:07:24Z"
+    stack: go-postgres
+    complexity: professional
+    whatToBorrow: >-
+      The sweet spot between "a job queue" and "Temporal": durable task
+      orchestration with retries, real-time monitoring, alerting and logging,
+      using Postgres as the single durability layer for both runtime and
+      observability — no Redis, no Kafka, no separate history store. That
+      one-datastore decision is the most reusable idea here for
+      `workflow-postgres-native` templates. Borrow the DAG/workflow declaration
+      from `examples/`, the `sql/` schema and migration approach, and the
+      multi-language SDK boundary in `sdks/` (Python, TypeScript, Go, Ruby) which
+      shows how to keep one engine addressable from several stacks. MIT and
+      actively developed.
+    whatToAvoid: >-
+      Younger and less battle-tested than Celery/Temporal; the API surface is
+      still moving, so pin versions. Postgres-as-queue has a real ceiling —
+      excellent to a few thousand jobs/sec, then it becomes a database scaling
+      problem rather than a queue problem. The repo carries a full frontend/ web
+      UI and Go engine, so it is a service you run, not a library you import;
+      generated projects should depend on the SDK and treat the engine as
+      infrastructure. Vendor also sells Hatchet Cloud — check OSS feature parity.
+    proposedLayerIds:
+      - workflow-hatchet
+      - workflow-durable-execution
+      - queue-postgres-native
+      - db-postgres-migrations
+      - observability-task-monitoring
+
+  # ------------------------------------------------------------ enterprise ---
+
+  - name: apache/kafka
+    url: https://github.com/apache/kafka
+    stars: 33267
+    spdx: Apache-2.0
+    spdxSource: LICENSE-file   # trunk/LICENSE is verbatim "Apache License Version 2.0, January 2004"
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18T17:48:58Z"
+    stack: java-scala
+    complexity: enterprise
+    whatToBorrow: >-
+      The default event backbone in large and regulated organisations, and the
+      one `broker-*` layer that will be mandated rather than chosen. Borrow the
+      operational contract rather than the source: KRaft-mode cluster config
+      (ZooKeeper is removed as of 4.0 — templates must not emit ZK any more),
+      topic design as declarative config (partitions, replication factor,
+      `min.insync.replicas`, retention and compaction), consumer-group semantics
+      with explicit offset commit, and the idempotent/transactional producer
+      settings (`enable.idempotence`, `acks=all`) that give exactly-once within
+      Kafka. `config/` holds the reference server properties to parameterise.
+      Schema Registry + Avro/Protobuf contracts are the enterprise pairing.
+    whatToAvoid: >-
+      Very heavy for anything below genuine scale — a multi-broker JVM cluster
+      with its own tuning, rebalancing and monitoring discipline; NATS or Redis
+      Streams is the right answer for most generated projects. The repo itself is
+      a Java/Scala broker codebase, not starter material: template against a
+      client library and docker-compose, do not vendor broker source. Avoid the
+      Confluent Platform images in templates — several Confluent components are
+      Community-License, not Apache-2.0, and that distinction is easy to miss.
+      Consumer rebalance storms and partition-count-as-permanent-decision are the
+      two footguns worth documenting.
+    proposedLayerIds:
+      - broker-kafka
+      - broker-kafka-kraft
+      - pattern-event-driven
+      - pattern-schema-registry
+      - pattern-transactional-outbox
+      - deploy-docker-compose
+
+  # --------------------------------------------------- reference-only ---------
+  # Readable for design ideas. Do NOT copy source files into generated projects.
+
+  - name: riverqueue/river
+    url: https://github.com/riverqueue/river
+    stars: 5449
+    spdx: MPL-2.0
+    spdxSource: github-api
+    licenseClass: reference-only
+    maintained: true
+    lastCommit: "2026-07-17T20:45:12Z"
+    stack: go-postgres
+    complexity: standard
+    whatToBorrow: >-
+      IDEAS ONLY — MPL-2.0 is file-level copyleft, so no River source may be
+      vendored. The idea worth reimplementing is transactional enqueueing: insert
+      the job in the same Postgres transaction as the business write, so the job
+      and the data commit or roll back together and the dual-write/outbox problem
+      disappears. Also worth studying: batch insert via Postgres COPY, unique
+      jobs with deduplication by args/period/queue/state, snooze-from-within-
+      handler, and transactional job completion. The example test files
+      (`example_insert_and_work_test.go`, `example_batch_insert_test.go`,
+      `example_cron_job_test.go`, `example_unique_job_test.go`) are the clearest
+      statement of the API shape. Depending on River as an unmodified dependency
+      is fine under MPL-2.0 — copying its files into a template is not.
+    whatToAvoid: >-
+      The license is the gate: MPL-2.0 obliges you to publish modifications to
+      any River file you alter, which is exactly what a scaffolding tool would
+      cause downstream users to do unknowingly. Keep it a go.mod dependency, never
+      vendored source. Technically, Postgres-as-queue has the same throughput
+      ceiling as Hatchet, and the web UI (River UI) is a separate deployment.
+    proposedLayerIds:
+      - queue-river-postgres
+      - queue-transactional-enqueue
+      - queue-postgres-native
+      - pattern-transactional-outbox
+
+  - name: HangfireIO/Hangfire
+    url: https://github.com/HangfireIO/Hangfire
+    stars: 10098
+    spdx: LGPL-3.0-or-later
+    spdxSource: LICENSE-file   # LICENSE.md is multi-license; OSS arm reads "version 3 of the License, or (at your option) any later version" => -or-later, not -only
+    licenseClass: reference-only
+    maintained: true
+    lastCommit: "2026-07-16T10:13:20Z"
+    stack: dotnet
+    complexity: professional
+    whatToBorrow: >-
+      IDEAS ONLY — the OSS arm of the multi-license is LGPL v3, so no source
+      copying. Hangfire remains the reference background-job design for .NET and
+      the patterns are worth reimplementing over a permissive base: persistent
+      storage in the app's existing SQL Server/Postgres database (no extra
+      infrastructure — the strongest reason .NET shops pick it), the
+      fire-and-forget / delayed / recurring / continuation job taxonomy, the
+      automatic retry with exponential backoff, and the built-in Hangfire
+      Dashboard mounted as ASP.NET middleware with its own authorisation filter.
+      The "jobs survive an app-pool recycle because they are rows in a table"
+      guarantee is the core idea.
+    whatToAvoid: >-
+      The licence is a genuine trap: the GitHub API reports NOASSERTION and many
+      blog posts describe Hangfire as simply "open source", but LICENSE.md is a
+      multi-license under which the free terms are LGPL v3 — copying files into a
+      generated project is out of scope for Groundplan, and the commercial Hangfire
+      Pro/Ace packages (batches, Redis storage, performance counters) are
+      separately paid. Technically, SQL-Server-backed polling adds database load
+      and default polling intervals give visibly latent job pickup; the dashboard
+      is unauthenticated by default outside localhost, which is a real
+      misconfiguration risk.
+    proposedLayerIds:
+      - queue-hangfire-dotnet
+      - queue-sql-storage-backed   # SQL Server first; Postgres is community storage, so not queue-postgres-native
+      - queue-dashboard
+      - queue-cron-repeatable
+
+# -----------------------------------------------------------------------------
+# DROPPED CANDIDATES — checked against the GitHub API on 2026-07-18 and rejected
+# -----------------------------------------------------------------------------
+#
+#   inngest/inngest — 5,618 stars, pushed 2026-07-18, NOT archived, but the API
+#     returns NOASSERTION and LICENSE.md is the Server Side Public License v1.0
+#     (with an Apache-2.0 future grant). SSPL is EXCLUDED. Note the client SDK
+#     (inngest/inngest-js) is licensed separately and may qualify — it must be
+#     verified on its own before use; the server repo may not be vendored.
+#
+#   soketi/soketi — 5,625 stars, AGPL-3.0 (LICENSE is verbatim GNU AGPL v3) →
+#     EXCLUDED. Also hard stale, worse than first recorded: the last commit on
+#     the default branch (master) is 2023-08-20, ~35 months before the research
+#     date — not the ~16 months previously noted. Its Pusher-protocol niche is
+#     better served by Centrifugo (Apache-2.0) or Laravel Reverb (MIT).
+#
+#   redis/redis — EXCLUDED for template source. Redis relicensed away from BSD;
+#     current releases are tri-licensed RSALv2 / SSPLv1 / AGPLv3, none of which
+#     are vendorable here. Using Redis as a runtime dependency via a permissive
+#     client library is fine and is assumed by the BullMQ and asynq layers —
+#     copying Redis source is not. Valkey (BSD-3) is the permissive fork if a
+#     template needs to ship server source.
+#
+#   rabbitmq/rabbitmq-server — MPL-2.0, so reference-only at best, and like
+#     Kafka it is broker source rather than starter material. Templates should
+#     depend on it via an AMQP client (and it already appears as the
+#     `broker-rabbitmq-amqp` layer under Watermill and Celery) rather than
+#     carrying an entry of its own.
+#
+#   windmill-labs/windmill and n8n-io/n8n (Sustainable Use License) were
+#     considered for the workflow-engine slot and EXCLUDED on license.
+#     Windmill is not uniformly AGPL-3.0 as first recorded — its root LICENSE
+#     states the tree is "variously licensed" under Apache-2.0 (LICENSE-APACHE)
+#     or AGPLv3, per file. Since the split must be resolved per file and the
+#     server core is the AGPL part, treat the repo as EXCLUDED for vendoring.
+#     Trigger.dev (Apache-2.0) and Hatchet (MIT) cover that slot cleanly.
+#
+#   ueberdosis/hocuspocus — MIT and actively maintained (v4.4.0, July 2026);
+#     a strong Yjs/CRDT collaboration backend. Held back only because it belongs
+#     more naturally in a collaborative-editing category than in
+#     realtime-messaging. Recommended for a future `collab-crdt-yjs` layer.
+#
+#   laravel/reverb — MIT, maintained by the Laravel core team (v1.10.2, May
+#     2026), but ~1.6k stars and useful almost exclusively inside a Laravel app.
+#     Worth revisiting if a PHP stack track is added.
+#
+#   django/channels — BSD-3-Clause and an official Django project; a reasonable
+#     future `realtime-websocket-django` layer. Omitted here only to keep the
+#     list at depth rather than breadth, since sse-starlette already covers the
+#     Python realtime slot.