How restezzz/owncord works
Purpose and Entry Points
OwnCord is a self-hosted real-time messenger supporting direct/group chat, uploads and voice notes, WebRTC calls, screen sharing, push notifications, and an optional Electron shell. The Node server is the authoritative API, persistence, signaling, and event hub: server/src/index.js, server/src/socket.js, server/src/ioHub.js. The browser client starts at client/src/main.tsx and composes the application in client/src/App.tsx. Electron launches the same web client/server deployment rather than maintaining local message state: desktop/main.js, desktop/preload.js.
Server HTTP, Authentication, and Security Boundary
Express exposes REST resources for identity, users, messages, groups, invites, mutes, push subscriptions, and health. Route modules form the HTTP boundary: server/src/routes/auth.js, server/src/routes/messages.js, server/src/routes/groups.js. Authentication and authorization are centralized around JWT/bcrypt and security policy in server/src/auth.js and server/src/security.js; admin, privacy, account deletion, and registration-invite rules are separate domain policies: server/src/admin.js, server/src/privacy.js, server/src/invites.js.
Persistence, Files, and Lifecycle Jobs
SQLite, accessed through better-sqlite3, is the durable source for accounts, conversations, messages, groups, and associated state: server/src/db.js. Upload handling is isolated at server/src/uploads.js, providing the boundary between HTTP/socket message operations and filesystem-backed attachments. Retention periodically removes expired messages and attachment files, while account deletion preserves conversation history under a deleted-user identity: server/src/retention.js, server/src/accountDeletion.js.
Realtime Messaging and Presence
Socket.IO delivers live conversation/group mutations, presence, and WebRTC signaling, while REST supplies durable reads and mutation endpoints. The server’s socket layer routes authenticated events through the shared IO hub: server/src/socket.js, server/src/ioHub.js; online/offline state is managed by server/src/presence.js. On the client, client/src/socket.ts maintains the realtime connection, client/src/api.ts handles HTTP calls, and client/src/components/ChatPanel.tsx / client/src/components/MessageList.tsx render and operate the active conversation.
Calls and WebRTC Signaling
Media remains peer-to-peer WebRTC; the server coordinates call state and relays signaling rather than transporting media. Direct-call lifecycle—including reconnect windows—is held in server/src/callRegistry.js; group session membership is tracked in server/src/groupCallRegistry.js. Client call orchestration owns media capture, peer connections, and signaling consumption: client/src/hooks/useCall.ts, client/src/hooks/useGroupCall.ts, client/src/components/CallView.tsx. Group calls use mesh topology, creating an explicit practical participant limit.
Client State and Product Shell
React state is organized by cross-cutting providers: authentication/configuration, groups, mutes, settings, and notifications in client/src/context/AuthContext.tsx, client/src/context/GroupsContext.tsx, and client/src/context/SettingsContext.tsx. Main screens divide unauthenticated and authenticated flows: client/src/pages/Login.tsx, client/src/pages/Register.tsx, client/src/pages/Home.tsx. Feature UI is component-driven, including group management and messaging attachments: client/src/components/GroupModal.tsx, client/src/components/AttachmentMessage.tsx, client/src/components/VoiceRecorder.tsx.
Delivery, Push, and Runtime Infrastructure
Production serves the built Vite client from the Node process; development runs Vite separately. The PWA surface includes a manifest and service worker: client/public/manifest.webmanifest, client/public/sw.js. Web Push spans server subscription/delivery logic and client registration utilities: server/src/push.js, client/src/utils/push.ts. Deployment targets a Node/systemd service behind nginx, with optional Dockerized TURN for restrictive NATs: deploy/owncord.service, deploy/nginx.conf.example, deploy/turn/docker-compose.yml. Electron adds native global shortcuts, auto-update, screen selection, and audio integration at the desktop boundary: desktop/shortcuts.js, desktop/autoUpdater.js, desktop/screenPicker/picker.js.
Main entry points: messages.js REST routes · App.tsx App shell · useCall.ts Call orchestration · ioHub.js IO hub & presence
Components 23
Node server
Authoritative API, event hub, and durable state.
- Server entry
server/src/index.js - REST routes · Identity, messages, groups, invites, mutes, push, and health.
server/src/routes/messages.js - Auth & security
server/src/auth.js - Account policies · Admin, privacy, invite, and deletion rules.
server/src/admin.js - SQLite state · Durable accounts, conversations, messages, and groups.
server/src/db.js - Attachment storage
server/src/uploads.js - Retention jobs · Expires messages and attachment files.
server/src/retention.js - Socket gateway · Authenticated realtime events and signaling.
server/src/socket.js - IO hub & presence
server/src/ioHub.js
Web client
React and PWA application.
- React entry
client/src/main.tsx - App providers · Authentication, groups, settings, mutes, and notifications.
client/src/context/AuthContext.tsx - App shell
client/src/App.tsx - Login & home screens · Unauthenticated and authenticated product flows.
client/src/pages/Home.tsx - Chat interface · Renders active messages and sends mutations.
client/src/components/ChatPanel.tsx - HTTP client
client/src/api.ts - Realtime client
client/src/socket.ts
Calling
Server signaling coordination and peer media.
- Call registries · Direct lifecycle and group session membership.
server/src/callRegistry.js - Call orchestration · Captures media and manages peer connections; group calls use mesh.
client/src/hooks/useCall.ts
Delivery
Push and production runtime boundaries.
- Web Push · Server subscriptions and client registration.
server/src/push.js - PWA worker
client/public/sw.js - Production edge · Serves built client through Node behind nginx.
deploy/owncord.service - TURN service · Optional relay for restrictive NATs.
deploy/turn/docker-compose.yml
Electron shell
Optional native host for the web deployment.
- Electron main · Hosts the same web client/server deployment.
desktop/main.js
Connections 26
- Server entry → REST routes: mounts
- Server entry → Socket gateway: starts
- REST routes → Auth & security: authorizes with
- REST routes → Account policies: enforces
- REST routes → SQLite state: reads and writes
- REST routes → Attachment storage: stores attachments
- Socket gateway → IO hub & presence: routes through
- IO hub & presence → SQLite state: persists mutations
- IO hub & presence → Call registries: coordinates calls
- Retention jobs → SQLite state: expires records
- Retention jobs → Attachment storage: removes files
- React entry → App shell: renders
- App shell → App providers: provides state
- App shell → Login & home screens: routes to
- Login & home screens → Chat interface: hosts
- Chat interface → HTTP client: uses
- Chat interface → Realtime client: receives live updates
- HTTP client → REST routes: REST
- Realtime client → Socket gateway: Socket.IO
- Call orchestration → Realtime client: consumes signaling
- Call orchestration → Call registries: exchanges signaling
- Call orchestration → TURN service: uses when needed
- PWA worker → Web Push: registers subscription
- Web Push → REST routes: subscription API
- Production edge → Server entry: runs
- Electron main → App shell: hosts