Toju/toju-app/src/app/domains/direct-call/README.md

Direct Call Domain

Direct calls coordinate private voice sessions started from people cards, direct-message headers, or active-call rail icons. The domain owns call session state and call-control events; media capture, camera, screen sharing, playback, and voice activity stay in the existing voice and screen-share domains.

Flow

1. DirectCallService.startCall() creates or reuses the direct-message conversation for a peer, while startConversationCall() starts from an existing one-to-one or group conversation. Both paths reuse a live call for the same peer or group before creating a new session.
2. The caller joins a call-scoped voice session and sends a direct-call ring event through PeerDeliveryService. Joining a direct call first leaves any other joined call or server voice channel.
3. The recipient stores the incoming session, loops assets/audio/call.wav, and shows a desktop notification when permission allows. The ring stops when the recipient joins, leaves, or the call ends.
4. Opening /call/:callId shows the private call surface with portraits, voice indicators, media controls, screen/camera tiles, add-user control, and a narrow DM chat panel.
5. If a third participant is invited, the call creates a fresh empty group conversation and switches the call chat panel to it. Existing one-to-one messages stay in the original PM and are not copied into the group chat.
6. Starting a call from a group chat uses the group conversation id as the call id and rings every other participant.
7. Joining, leaving, ending, participant additions, and call chat conversion updates are mirrored as direct-call events over the same P2P/signaling fallback path used by direct messages.
8. The server rail shows call icons only while at least one participant is joined. If a user is viewing a private call after the session ends, the route returns to the call's chat view.

Two-person calls use the one-to-one direct-message conversation id as their call id. Converted group calls keep the original call id for media routing but point conversationId at the new group chat so active streams stay connected while the chat history boundary changes.