Elixir Pub/Sub - Expanded Project Guides

Generated from: LEARN_ELIXIR_PUBSUB_DEEP_DIVE.md

This folder contains twelve standalone deep-dive projects that progress from raw BEAM mailboxes to a secure, durable, observable multi-node event platform.

Overview

These projects teach Pub/Sub as a set of explicit boundaries rather than one universal event bus. The early projects expose process mailboxes, local membership, topic routing, and event contracts. The middle projects add Phoenix.PubSub, LiveView, Presence, overload control, and demand-aware pipelines. The final projects separate transient notification from durable handoff, test distributed partitions and rolling changes, integrate a broker, and certify tenant isolation.

Every guide includes theory, an observable outcome, architecture, implementation phases, testing strategy, failure signatures, extensions, resources, and completion criteria. The implementation sections deliberately provide pseudocode and structured guidance rather than full runnable solutions.

Project Index

# Project Difficulty Time Key Focus
1 Mailbox Broadcast Laboratory Level 1 6–8h Raw sends, ordering, selective receive, monitors
2 Registry Topic Bus Level 2 8–12h Duplicate Registry, local membership, dispatch
3 Contract-Aware Domain Event Hub Level 2 10–14h Topics, envelopes, versions, tenant routing
4 Phoenix.PubSub Notification Hub Level 2 10–14h Phoenix.PubSub APIs, echo, pool migration
5 LiveView Operations Board Level 3 14–20h UI freshness, reconnect, authoritative reload
6 Distributed Presence Workspace Level 3 16–22h Tracker CRDT, multi-device presence, convergence
7 Mailbox Pressure Laboratory Level 3 16–24h Overload, event age, coalescing, recovery SLO
8 Demand-Aware Fanout Bridge Level 3 18–26h GenStage demand, Broadway, batching, ack boundaries
9 Durable Notification Outbox Level 4 22–32h Ecto transaction, Oban, idempotent retry
10 Three-Node PubSub Laboratory Level 4 20–30h Distribution, :pg, partitions, pool migration
11 Tenant-Safe Broker Edge Bridge Level 4 24–36h RabbitMQ, Broadway ack, DLQ, authorization
12 Multi-Tenant Real-Time Event Platform Level 5 45–60h Production synthesis and chaos certification

Dependency Graph

P01 Mailboxes
 ├──▶ P02 Registry ──▶ P03 Event Contracts ──▶ P04 Phoenix.PubSub
 │                                                   │
 │                                                   ├──▶ P05 LiveView
 │                                                   ├──▶ P06 Presence
 │                                                   └──▶ P10 Multi-Node
 │
 └────────────────────────▶ P07 Mailbox Pressure ──▶ P08 Demand Bridge
                                      │                    │
                                      └────▶ P09 Outbox ◀──┘
                                                   │
                          P06 + P07 + P09 + P10 ──▶ P11 Broker Edge
                                                   │
                     P01–P11 concepts/evidence ───▶ P12 Capstone

Learning Paths

Recommended OTP path

  1. P01 Mailbox Broadcast
  2. P02 Registry Topic Bus
  3. P03 Domain Event Hub
  4. P04 Phoenix.PubSub Hub
  5. P07 Mailbox Pressure
  6. P09 Durable Outbox
  7. P10 Three-Node Lab
  8. P12 Capstone

Phoenix product path

  • P01 -> P04 -> P05 -> P06 -> P07 -> P12

Integration path

  • P01 -> P03 -> P07 -> P08 -> P09 -> P11 -> P12

Distributed/SRE path

  • P01 -> P02 -> P04 -> P07 -> P10 -> P11 -> P12

Prerequisites

  • Elixir syntax, pattern matching, modules, structs, and tagged tuples.
  • Basic BEAM process and OTP supervision vocabulary.
  • Mix, IEx, and ExUnit usage.
  • Phoenix/LiveView fundamentals before Projects 5–6.
  • PostgreSQL/Ecto fundamentals before Project 9.
  • Named-node and network basics before Project 10.
  • Broker/exchange/queue vocabulary before Project 11.

Use Elixir 1.20.x with Erlang/OTP 29 or a currently supported compatible pair. The parent guide records the July 2026 research baseline and primary sources.

How to Use the Expanded Guides

  1. Read the parent theory chapter links listed in each project’s Quick Reference.
  2. Answer the Core Question and design questions before implementing.
  3. Draw the architecture and failure matrix by hand.
  4. Implement one phase at a time and stop at every checkpoint.
  5. Produce the exact observable output or UI behavior described by the guide.
  6. Run the fault, overload, duplicate, reconnect, and authorization fixtures.
  7. Complete the self-assessment without notes.
  8. Record deviations, measurements, and lessons in the project README.

Shared Safety and Correctness Rules

  • A completed send or broadcast is never labeled subscriber processing success.
  • Per-sender ordering is never described as global ordering.
  • Phoenix.PubSub and Presence are never used as durable business history.
  • Commands have a responsible owner; facts may have many observers.
  • Every slow-consumer path has a bounded policy and visible counter.
  • At-least-once delivery always has stable identity and an idempotency strategy.
  • Topic names are derived only after authorization; subscriber filtering is not access control.
  • Partition tests explicitly name missed transient events and the durable reload/replay path.
  • Telemetry callbacks remain bounded and metric labels avoid raw high-cardinality IDs.
  • Examples are guidance and pseudocode, not production-ready copy/paste implementations.

Completion Standard

Do not mark a project complete because the happy path appears to work. Completion requires its Definition of Done, critical tests, one injected failure, reproducible output, and a written statement of ordering, loss, duplicate, capacity, authorization, and recovery semantics.

Return to the complete Elixir Pub/Sub mastery guide for the theory primer, project comparison, recommendations, and production path.