# jewelpaul/chat-application architecture

> Architecture diagram of the GitHub repository jewelpaul/chat-application, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jewelpaul/chat-application
- Repository: https://github.com/jewelpaul/chat-application

## Overview

1. This repository is split into two primary runtimes: a Node.js server in `server/` and a React/TypeScript client in `client/`. The server is the real-time coordination layer; the client is the interactive chat/call UI.

2. The server is an Express + Socket.io application. `server/server.js` is the main entrypoint, with `auth.js`, `database.js`, and `utils.js` supporting invite-code registration, ephemeral state management, and request/event validation. There is no persistent database; all user/session/message state lives in memory and disappears on restart or disconnect.

3. HTTP on the server is minimal and mostly infrastructure-oriented. The app serves the client build at `/` and exposes `/health` for uptime and client-count monitoring. This is the endpoint used by Docker/Render health checks.

4. Real-time communication is the core backend path. Socket.io handles registration, connection requests/acceptance, text messages, media transfer, typing indicators, and call signaling. The server acts as a relay and state coordinator between matched peers rather than a long-lived data store.

5. The client is a Vite-built React app using TypeScript and Tailwind CSS. `main.tsx` and `App.tsx` bootstrap the app, while the UI is organized into reusable chat, call, modal, and layout components under `client/src/components/`.

6. The client UI is composed around a few main surfaces: chat layout (`MainChatLayout`, `Sidebar`, `ChatArea`, `ChatInterface`), call surfaces (`CallInterface`, `ActiveCallScreen`, incoming-call modals), and onboarding/auth flows (`WelcomeScreen`, `KeyWelcomeScreen`, `OnboardingSlideshow`, request modals). This suggests a state-driven single-page app rather than separate pages.

7. Chat data flow goes through a dedicated hook and socket layer. `useChat.ts` consumes Socket.io events and feeds the conversation UI, while `socket.ts` centralizes the client connection. Messages are rendered by specialized components such as `MessageBubble`, `ImageMessage`, `VideoMessage`, `AudioMessage`, and `FileMessage`.

8. Media sharing is handled as a first-class chat path, not a separate subsystem. The client includes `MediaPicker` and `VoiceRecorder`, and the server accepts `media-upload` events with filename/MIME metadata. Inline previews and download behavior are handled in the message components, while validation remains on the server side.

9. Voice/video calls use WebRTC for peer media transport, with Socket.io only as signaling. `useWebRTC.ts` and `services/webrtc.ts` manage peer setup, offer/answer exchange, ICE signaling, and call lifecycle events; the server relays `call-*` and `webrtc-signal` messages but does not carry media streams.

10. Privacy and security are architectural constraints, not just features. Optional client-side encryption is implemented through `crypto.ts` and `encryption.ts`, with helper utilities like `deviceKey.ts` for per-device identity. The README’s “ephemeral” model means no durable chat history, no file persistence, and automatic cleanup on disconnect.

11. Cross-cutting client concerns are centralized in providers and guards. `ThemeProvider`, `NotificationProvider`, and `ErrorBoundary` wrap the app so theme state, toasts/alerts, and render failures do not leak into the core chat logic. Shared UI primitives live under `components/ui/`.

12. Packaging and deployment are straightforward: the root repo contains the production Node server, and the client is built separately via Vite. Docker and `render.yaml` are the main deployment artifacts, with environment variables controlling port, origin/CORS, logging, and optional encryption behavior.

Main entry points: [`server/server.js`](https://github.com/jewelpaul/chat-application/blob/main/server/server.js) (Server main), [`client/src/App.tsx`](https://github.com/jewelpaul/chat-application/blob/main/client/src/App.tsx) (App state), [`client/src/components/MainChatLayout.tsx`](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/MainChatLayout.tsx) (Chat layout), [`client/src/components/ChatArea.tsx`](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/ChatArea.tsx) (Chat area)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server"]
  node_server_entry["Server main<br/>Express/Socket.io app<br/>[server.js]"]
  node_server_auth["Auth<br/>[auth.js]"]
  node_server_state[("In-memory state<br/>ephemeral store<br/>[database.js]")]
  node_server_utils["Validation utils<br/>request/event guards<br/>[utils.js]"]
end

subgraph group_client["Client"]
  node_client_main["App shell<br/>React bootstrap<br/>[main.tsx]"]
  node_client_app["App state<br/>SPA router/state<br/>[App.tsx]"]
  node_client_socket["Socket client<br/>Socket.io client<br/>[socket.ts]"]
  node_client_chat_hook["Chat hook<br/>chat event hook<br/>[useChat.ts]"]
  node_client_webrtc_hook["WebRTC hook<br/>call lifecycle hook<br/>[useWebRTC.ts]"]
  node_client_webrtc_service["WebRTC service<br/>peer signaling<br/>[webrtc.ts]"]
  node_client_layout["Chat layout<br/>chat surface<br/>[MainChatLayout.tsx]"]
  node_client_sidebar["Sidebar<br/>contacts/navigation<br/>[Sidebar.tsx]"]
  node_client_chat_area["Chat area<br/>conversation surface<br/>[ChatArea.tsx]"]
  node_client_messages["Message media<br/>message renderers<br/>[Message.tsx]"]
  node_client_call["Call surface<br/>call UI<br/>[CallInterface.tsx]"]
  node_client_onboarding["Onboarding<br/>auth/welcome UI<br/>[WelcomeScreen.tsx]"]
  node_client_providers["Providers<br/>cross-cutting context<br/>[ThemeProvider.tsx]"]
  node_client_ui["UI primitives<br/>shared components<br/>[Button.tsx]"]
end

subgraph group_deploy["Deploy"]
  node_deploy["Deployment<br/>build/runtime config"]
end

node_client_main -->|"mounts"| node_client_app
node_client_app -->|"wraps"| node_client_providers
node_client_app -->|"shows"| node_client_onboarding
node_client_app -->|"shows"| node_client_layout
node_client_layout -->|"contains"| node_client_sidebar
node_client_layout -->|"contains"| node_client_chat_area
node_client_layout -->|"contains"| node_client_call
node_client_chat_area -->|"renders"| node_client_messages
node_client_chat_area -->|"uses"| node_client_ui
node_client_socket -->|"feeds"| node_client_chat_hook
node_client_socket -->|"feeds"| node_client_webrtc_hook
node_client_chat_hook -->|"updates"| node_client_chat_area
node_client_webrtc_hook -->|"uses"| node_client_webrtc_service
node_server_entry -->|"uses"| node_server_auth
node_server_entry -->|"stores"| node_server_state
node_server_entry -->|"uses"| node_server_utils
node_server_entry -->|"relays"| node_client_socket
node_server_entry -->|"signals"| node_client_call
node_server_entry -->|"relays"| node_client_chat_hook
node_server_entry -->|"served by"| node_deploy
node_client_main -->|"built for"| node_deploy

click node_server_entry "https://github.com/jewelpaul/chat-application/blob/main/server/server.js"
click node_server_auth "https://github.com/jewelpaul/chat-application/blob/main/server/auth.js"
click node_server_state "https://github.com/jewelpaul/chat-application/blob/main/server/database.js"
click node_server_utils "https://github.com/jewelpaul/chat-application/blob/main/server/utils.js"
click node_client_main "https://github.com/jewelpaul/chat-application/blob/main/client/src/main.tsx"
click node_client_app "https://github.com/jewelpaul/chat-application/blob/main/client/src/App.tsx"
click node_client_socket "https://github.com/jewelpaul/chat-application/blob/main/client/src/socket.ts"
click node_client_chat_hook "https://github.com/jewelpaul/chat-application/blob/main/client/src/hooks/useChat.ts"
click node_client_webrtc_hook "https://github.com/jewelpaul/chat-application/blob/main/client/src/hooks/useWebRTC.ts"
click node_client_webrtc_service "https://github.com/jewelpaul/chat-application/blob/main/client/src/services/webrtc.ts"
click node_client_layout "https://github.com/jewelpaul/chat-application/blob/main/client/src/components/MainChatLayout.tsx"
click node_client_sidebar "https://github.com/jewelpaul/chat-application/blob/main/client/src/components/Sidebar.tsx"
click node_client_chat_area "https://github.com/jewelpaul/chat-application/blob/main/client/src/components/ChatArea.tsx"
click node_client_messages "https://github.com/jewelpaul/chat-application/blob/main/client/src/components/Message.tsx"
click node_client_call "https://github.com/jewelpaul/chat-application/blob/main/client/src/components/CallInterface.tsx"
click node_client_onboarding "https://github.com/jewelpaul/chat-application/blob/main/client/src/components/WelcomeScreen.tsx"
click node_client_providers "https://github.com/jewelpaul/chat-application/blob/main/client/src/components/ThemeProvider.tsx"
click node_client_ui "https://github.com/jewelpaul/chat-application/blob/main/client/src/components/ui/Button.tsx"
click node_deploy "https://github.com/jewelpaul/chat-application/tree/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_entry,node_server_auth,node_server_state,node_server_utils toneBlue
class node_client_main,node_client_app,node_client_socket,node_client_chat_hook,node_client_webrtc_hook,node_client_webrtc_service,node_client_layout,node_client_sidebar,node_client_chat_area,node_client_messages,node_client_call,node_client_onboarding,node_client_providers,node_client_ui toneAmber
class node_deploy toneMint
```

## Components

### Server

Express + Socket.io coordination layer

- [Server main](https://github.com/jewelpaul/chat-application/blob/main/server/server.js): Express/Socket.io app · Bootstraps HTTP server, routes, and real-time handlers · `server/server.js`
- [Auth](https://github.com/jewelpaul/chat-application/blob/main/server/auth.js): invite-code auth · Handles registration and access checks · `server/auth.js`
- [In-memory state](https://github.com/jewelpaul/chat-application/blob/main/server/database.js): ephemeral store · Tracks users, sessions, and active conversations in memory · `server/database.js`
- [Validation utils](https://github.com/jewelpaul/chat-application/blob/main/server/utils.js): request/event guards · Shared validation and helper logic for server events · `server/utils.js`

### Client

React + TypeScript SPA

- [App shell](https://github.com/jewelpaul/chat-application/blob/main/client/src/main.tsx): React bootstrap · Vite entry and top-level app composition · `client/src/main.tsx`
- [App state](https://github.com/jewelpaul/chat-application/blob/main/client/src/App.tsx): SPA router/state · Top-level application flow and conditional surfaces · `client/src/App.tsx`
- [Socket client](https://github.com/jewelpaul/chat-application/blob/main/client/src/socket.ts): Socket.io client · Central client connection and event wiring · `client/src/socket.ts`
- [Chat hook](https://github.com/jewelpaul/chat-application/blob/main/client/src/hooks/useChat.ts): chat event hook · Consumes socket events and feeds chat UI state · `client/src/hooks/useChat.ts`
- [WebRTC hook](https://github.com/jewelpaul/chat-application/blob/main/client/src/hooks/useWebRTC.ts): call lifecycle hook · Manages peer setup and call signaling state · `client/src/hooks/useWebRTC.ts`
- [WebRTC service](https://github.com/jewelpaul/chat-application/blob/main/client/src/services/webrtc.ts): peer signaling · Peer connection helpers and media-call orchestration · `client/src/services/webrtc.ts`
- [Chat layout](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/MainChatLayout.tsx): chat surface · Main conversation shell with sidebar and message area · `client/src/components/MainChatLayout.tsx`
- [Sidebar](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/Sidebar.tsx): contacts/navigation · Contact list and chat navigation · `client/src/components/Sidebar.tsx`
- [Chat area](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/ChatArea.tsx): conversation surface · Displays messages and message composer context · `client/src/components/ChatArea.tsx`
- [Message media](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/Message.tsx): message renderers · Renders text and rich media message variants · `client/src/components/Message.tsx`
- [Call surface](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/CallInterface.tsx): call UI · Active call, incoming call, and call controls · `client/src/components/CallInterface.tsx`
- [Onboarding](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/WelcomeScreen.tsx): auth/welcome UI · Welcome, key entry, and request flows · `client/src/components/WelcomeScreen.tsx`
- [Providers](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/ThemeProvider.tsx): cross-cutting context · Theme, notifications, and render-failure boundaries · `client/src/components/ThemeProvider.tsx`
- [UI primitives](https://github.com/jewelpaul/chat-application/blob/main/client/src/components/ui/Button.tsx): shared components · Reusable base controls and modal primitives · `client/src/components/ui/Button.tsx`

### Deploy

Build and runtime packaging

- [Deployment](https://github.com/jewelpaul/chat-application/tree/main/Dockerfile): build/runtime config · Container and platform configuration for production builds · `Dockerfile`

## Connections

- App shell → App state: mounts · Bootstraps the application shell
- App state → Providers: wraps · Applies shared context and boundaries
- App state → Onboarding: shows · Routes first-run and key-entry flows
- App state → Chat layout: shows · Main authenticated conversation experience
- Chat layout → Sidebar: contains · Navigation and contacts panel
- Chat layout → Chat area: contains · Primary message composition and viewing area
- Chat layout → Call surface: contains · Call-related surfaces
- Chat area → Message media: renders · Message variants and media previews
- Chat area → UI primitives: uses · Shared controls and modal primitives
- Socket client → Chat hook: feeds · Socket events drive chat state
- Socket client → WebRTC hook: feeds · Socket events drive signaling state
- Chat hook → Chat area: updates · Supplies conversation data to the UI
- WebRTC hook → WebRTC service: uses · Delegates peer-connection operations
- Server main → Auth: uses · Validates registration and access
- Server main → In-memory state: stores · Keeps users and sessions in memory
- Server main → Validation utils: uses · Validates HTTP and socket events
- Server main → Socket client: relays · Socket.io events bridge peers
- Server main → Call surface: signals · Call signaling events are mediated by the server
- Server main → Chat hook: relays · Chat, typing, and media events reach the client
- Server main → Deployment: served by · Runs behind container/platform deployment
- App shell → Deployment: built for · Vite production bundle is deployed separately
