System architecture

High-level view of the Ceili desktop client, chatserver, and voice relay.

System architecture

The current Ceili implementation is a Wails desktop client connected to a Go chatserver. The chatserver owns room membership, message fanout, and voice signaling. Voice media is relayed through a server-side Pion SFU; clients do not form a peer-to-peer mesh.

Core layers

Desktop client

  • Wails provides the desktop shell and Go entrypoints.
  • React owns WebSocket state, room state, voice state, and diagnostics.
  • The client persists the last server, display name, and room locally.
  • Reconnect logic uses exponential backoff after transport failures.

Chatserver transport

  • HTTP exposes health/readiness checks and /voice/bootstrap.
  • WebSocket /ws requires a display name and room query parameter.
  • The chat hub registers clients, switches rooms, broadcasts messages, and maintains voice membership.

Voice relay

  • Each participant has one peer connection to the server’s Pion voice service.
  • The server forwards tracks between participants in the same voice channel.
  • ICE server settings and the server peer ID are supplied by /voice/bootstrap.
  • STUN/TURN and UDP port settings are deployment concerns; see Voice configuration.

Storage boundary

  • Message persistence is behind the MessageRepository interface.
  • The current MVP can run without a persistent repository and uses in-memory behavior where configured.
  • Authentication, user management, moderation, and extension services are not part of the current chatserver flow.

Request flow

  1. The client opens /ws?name=<display_name>&room=<room_id>.
  2. The chatserver assigns a member ID, registers the connection, and sends room state and message replay.
  3. Chat messages are validated, optionally stored, and broadcast to the current room.
  4. Room switches update membership and replay state; an active voice session is left before the move.
  5. Voice clients fetch ICE settings, join a voice channel, and send WebRTC signaling to voice-sfu.
  6. Pion forwards voice tracks within the server-scoped voice session.

Runtime topology

Wails desktop client
  React UI + protocol/voice services
        |
        | HTTP health/bootstrap and WebSocket
        v
    chatserver transport
        |
        v
      chat hub -------- MessageRepository
        |
        | voice signaling and room/channel scope
        v
    Pion voice service / SFU
        |
        v
  participant peer connections
  (server-relayed media only)

The separate userserver directory is currently a scaffold and is not integrated into this documented chat flow. Extensions remain planned rather than an implemented runtime API.