xonecas.io
8058
Ir

irvc / files

irvc / irvc.md

9.4 KB
1# IRVC — Design
2
3A WebRTC-powered text and voice chat. Private, self-hosted, personal server.
4
5## Goal
6
7Small, private chat + voice for 4–6 people on one VPS. No data gathering, full ownership.
8
9## Scope (MVP)
10
11**In:**
12- Server-side accounts, invite-only.
13- Text channels and 1-on-1 DMs with persisted history (IRC-like), GFM markdown, multiline compose, mentions, message editing and deletion.
14- Text and voice channels created and deleted from the sidebar; the seeded channels are permanent.
15- Image and video attachments, stored on disk.
16- Voice channels, ephemeral (not recorded), with mute, deafen, per-peer volume, mic processing, a level-based noise gate, and a join/leave tone.
17- Screen sharing into a voice channel, with tab/system audio, simulcast, and a 720p/1080p quality choice.
18- 1-on-1 voice and video calls inside a DM, with a ring tone the callee can switch off.
19- Presence: online/offline, plus who is in each voice channel without joining.
20- Client themes, font size, per-user voice settings.
21- One server per deployment, seeded with one text and one voice channel.
22
23**Out (now):**
24- Large scale, multi-node, clustering.
25- Recording, and video outside DM calls.
26- Group calls; only 1-on-1 calls exist.
27- Message search.
28- Email, OAuth, passkeys.
29- Backups.
30- Password reset via email (admin resets manually).
31
32## Architecture
33
34One VPS, three processes:
35
36- **LiveKit** — self-hosted, voice and screen share. Own ports: signal `7880`, TCP `7881`, media `50000-60000/udp`. Media ports exposed raw, not proxied.
37- **Gin server (Go)** — API, auth, invite/session handling, LiveKit token minting, text chat and presence over WebSocket, media upload/serve, SQLite.
38- **Caddy** — TLS + reverse proxy for frontend and API. Terminates TLS; proxies `wss` to LiveKit signal.
39
40Split:
41- Text → our WebSocket + SQLite. LiveKit not involved.
42- Voice → LiveKit. Ephemeral. The Go server mints tokens but never dials LiveKit.
43- Presence → our WebSocket (connected = online; voice occupancy broadcast to all).
44- Media → disk under the media dir, served by Go.
45
46## Auth & Identity
47
48- Invite links: single-use, 14-day expiry. Anyone with a link creates a user and joins.
49- Revoke = delete the row.
50- Passwords hashed with argon2id.
51- Login → session cookie (`HttpOnly`, `Secure`, `SameSite=Lax`), 30-day TTL, server-side session row. Cookie value is HMAC-signed.
52- Server mints a short-lived LiveKit token when a voice channel or DM call is joined.
53- Rate limit login and invite-claim endpoints (per IP).
54- No email. Admin resets passwords by hand.
55
56## Data (SQLite)
57
58WAL mode, `busy_timeout`. One file, the only state; uploaded media lives in the media dir.
59
60```
61users    (id, username, pass_hash, created_at)
62invites  (token, created_by, expires_at, used_by, used_at)
63sessions (id, user_id, expires_at)
64channels (id, type, name, position, permanent, created_at)   -- type: text | voice | dm
65messages (id, channel_id, user_id, body, created_at, edited_at)
66reactions (message_id, user_id, reaction)
67read_state (user_id, channel_id, last_read_message_id, updated_at)
68```
69
70- Messages are returned joined with their author's username.
71- Seed: one text channel `#general` and one voice channel `general`, both marked permanent.
72- DMs: `type = 'dm'` channels with canonical name `u:<min_id>:<max_id>`, resolved to the peer's username for each participant.
73- Uploaded media: random names, raster images and mp4/webm video only (no SVG/HTML), served with `nosniff` and Range support, so video streams and seeks.
74
75## Behavior
76
77- **Channels:** seeded (`#general` text, `general` voice, both permanent) plus on-demand 1-on-1 DMs opened by clicking a user. Text and voice channels can be created and deleted from the sidebar; permanent channels cannot be deleted, and a voice channel cannot be deleted while someone is in it. Ordered by `position`.
78- **Text:** GFM markdown; single newlines are hard breaks. Messages persist; live append over WS. Rendered as timestamp, author, content.
79- **Mentions:** `@username` highlights the message for that user; typing `@` opens an autocomplete.
80- **Unread:** `read_state` stores each user's last-read message per channel; `/channels` returns the count of newer messages by others. Opening a channel marks it read, so the count survives reload and is shared across devices.
81- **Commands:** `/me <action>` renders an emote as `* user action`; `/collapse` hides media in the current channel; `/gif [query]` opens a picker with the top Giphy results (trending when no query) to insert one. The gif picker is disabled without `IRVC_GIPHY_API_KEY`.
82- **Media:** pasted or attached, uploaded, rendered inline. Images open in a click-to-zoom dialog; video renders as a player capped to the image size, showing its first frame as a thumbnail. Collapsible per message or channel-wide. Gifs from Giphy can also be inserted with the gif picker.
83- **Voice:** joining a voice channel connects to its LiveKit room (`voice-<id>`). Not persisted, not recorded. Occupants are visible to everyone without joining.
84- **Calls in DMs:** a DM holds a 1-on-1 voice or video call. It reuses the voice-token path — a DM call mints a token for the DM's own room — so a call is the same LiveKit machinery as a voice channel, attached to the DM instead. Starting one rings the peer with a slow repeating `beep()` (toggleable in settings) and signals them over the WS. Only one capture at a time, so starting a DM call leaves any voice channel first. The call pane is a horizontal split: peers' cameras fill the top, the DM's text shrinks to the bottom quarter.
85- **Screen share:** any participant may publish a screen share (with tab or system audio) into the room. It is not persisted and not recorded. Shares are visible only to participants, not to the rest of the server. Share audio plays through the normal audio path, so deafen and per-peer volume apply.
86- **Voice controls:** mute, deafen, camera on/off, per-peer volume, mic/speaker device, quality preset, echo cancellation, noise suppression, auto gain, voice isolation, level-based noise gate, join/leave tone, ring tone, start/stop screen share. Deafen still only silences incoming audio locally; its state is shared, nothing else.
87- **Presence:** a user is online while their WS connection is up; otherwise offline. Voice occupancy rides along with presence, and so does each occupant's mute/deafen state, so everyone sees who cannot hear or be heard without joining the call. A user with several connections counts as muted or deafened only when all of them are. No invisible mode.
88- **Settings:** colors, font size, and voice preferences are client-side (device-local). Voice occupancy is server-side only.
89
90## Frontend
91
92- React, modern. oxlint + oxfmt. Tailwind, LiveKit client. Mobile-first: the layout is built for narrow screens and widens from there.
93- **Style system.** One set of semantic tokens (`src/index.css`) names every role the UI
94  uses: background, sidebar, panels, text, muted, faint, borders, accent, accent text,
95  danger. Palettes set those variables; user overrides replace them; components only ever
96  reference the roles. The shared vocabulary on top (`src/ui`) is buttons, inputs, fields,
97  toggles, menus and lists — feature code composes those instead of inventing new Tailwind
98  recipes, so the UI stays consistent by construction.
99- **Theming.** `80s-nicotine` (sepia, default) and `tuxedo` (grayscale) are presets of those
100  colors, not fixed themes: any color can be overridden per light/dark mode from the
101  settings pane and is stored with the rest of the preferences. Mode, preset and overrides
102  are applied before first paint.
103- **No hover-only interactions.** Anything interactive is visible and reachable by tap and
104  keyboard: per-message actions open from an always-present `⋯`, channel actions from a
105  `⋯` menu, and the selected message's actions appear in a contextual bar above the
106  composer. Hover only ever adds a colour change.
107- Layout:
108  - Left sidebar: text channels, voice channels (with occupants), DMs, then users
109    (online/offline). Fixed on desktop, a drawer with a scrim on mobile.
110  - Focus pane: chat for the selected text channel or DM, a DM call, the settings pane, or a screen share.
111  - Header: sidebar toggle (mobile), current channel, channel actions.
112  - Voice bar: whenever you are in a call — docked in the sidebar on desktop, at the bottom
113    of the screen on mobile — with mute, deafen, camera, screen share, leave, participants
114    and per-peer volume (from the participant's own menu).
115- Settings pane: mode, palette, per-role colours, text size, sounds (join/leave, ringing), voice-activation
116  meter/threshold, devices, quality (audio and screen share), mic processing.
117
118## Config
119
120Secrets from shell env, `IRVC_*`:
121
122```
123IRVC_LISTEN_ADDR
124IRVC_DB_PATH
125IRVC_SESSION_SECRET     required to run
126IRVC_LIVEKIT_URL        browser-facing
127IRVC_LIVEKIT_API_KEY
128IRVC_LIVEKIT_SECRET
129IRVC_MEDIA_DIR          uploaded media storage
130IRVC_MAX_UPLOAD         max upload bytes
131IRVC_GIPHY_API_KEY      Giphy API key; the gif picker is disabled without it
132```
133
134LiveKit key/secret must match the LiveKit server config and ours. Voice is disabled when the LiveKit vars are unset.
135
136Flags exist for the address, DB, media dir, upload size and LiveKit URL; secrets stay environment-only. `irvc invite` creates an invite and prints a `/join?token=...` link; `irvc --gen-secret` prints a random session secret. A Makefile wraps build/test/fmt for Go and npm.
137
138## Deployment
139
140Bare Linux, no Docker. README lists system-level deps. Services start on boot and restart on crash (systemd). See `DEPLOY.md` for the runbook.