A distributed chat system built to teach GenServers, OTP, and distributed Elixir.

The file lib/beam_chat/server.ex contains a skeleton with all the function signatures, types, and detailed TODO comments — but no implementation.

Your task: implement the GenServer callbacks and helper functions so that the tests pass and the chat system works end-to-end.

When you're done, you can check your work against the solution branch:

git diff main..solution -- lib/beam_chat/server.ex

  Terminal 1 (Server Node)         Terminal 2 (Client Node)         Terminal 3 (Client Node)
  ┌─────────────────────┐         ┌─────────────────────┐         ┌─────────────────────┐
  │                     │         │  BeamChat.TUI       │         │  BeamChat.TUI       │
  │  BeamChat.Server    │◄────────│  BeamChat.Client    │         │  BeamChat.Client    │
  │  (GenServer)        │────────►│  (GenServer)        │         │  (GenServer)        │
  │                     │         │                     │         │                     │
  │  - tracks clients   │◄────────┤                     │         │                     │
  │  - broadcasts msgs  │────────►│                     │         │                     │
  │  - keeps history    │         └─────────────────────┘         └─────────────────────┘
  │                     │                                                    ▲ │
  │                     │◄───────────────────────────────────────────────────┘ │
  │                     │─────────────────────────────────────────────────────►│
  └─────────────────────┘

Before writing anything, read these files to understand how the system works:

1. lib/beam_chat/server.ex — Read the Client API functions (already done). They tell you exactly what messages each callback will receive.
2. lib/beam_chat/client.ex — See how the client joins, sends messages, and handles incoming {:new_message, msg} tuples.
3. test/beam_chat_test.exs — The tests define the expected behavior.

Start with the private functions at the bottom of server.ex:

1. build_message/2 — Build a %{user: ..., text: ..., timestamp: ...} map
2. find_client/2 — Search a MapSet for a tuple matching a PID
3. already_joined?/2 — Check if a PID is in the clients MapSet
4. broadcast/2 — Send a message to every client PID

Work through these in order:

1. init/1 — Set up the initial state
2. handle_call(:get_history, ...) — Return the history (easiest callback)
3. handle_call({:join, username}, ...) — Join logic with monitoring
4. handle_cast({:send_message, ...}, ...) — Message relay
5. handle_cast({:leave, ...}, ...) — Graceful disconnect
6. handle_info({:DOWN, ...}, ...) — Crash detection

mix test

All 6 tests should pass.

# Terminal 1 — Server
./start_server.sh

# Terminal 2 — Alice
./start_client.sh Alice

# Terminal 3 — Bob
./start_client.sh Bob

ref = Process.monitor(pid)    # Start watching a process
Process.demonitor(ref, [:flush])  # Stop watching
# If pid dies -> you receive {:DOWN, ref, :process, pid, reason}

Once you finish the server, try these extensions:

1. Add /users command — Query the server for the list of connected usernames
2. Add private messages — Implement /msg Bob Hey there! to send only to Bob
3. Add a message limit — Only keep the last 100 messages in history
4. Handle server crash — What happens to clients when the server dies? Add reconnect logic