Chat your way.
Learn how.

How to use this guide

What you'll be able to explain

• What Kivo is, who it's for, and what it deliberately isn't (not Slack).
• How a message travels (optimistic UI → JWT → Zod → Mongo → Socket → receipts → push → offline outbox).
• Why Mongo is truth and sockets only announce; why no Redis/microservices/TS — yet.
• Auth that actually revokes, presence that doesn't spam, threads that stay quiet, Plus that the client can't fake.

What is Kivo?

Principles

Fast & realtime · Simple despite rich · Personal & customizable · Clean responsive UI (bottom tabs on phones, icon rail on desktop) · Privacy + authorization foundational — never trust the client · One identity across DMs/Groups/Spaces · No premature microservices.

Pages (what users actually open)

Repository map + 4-file rule

📱 Everyday user manual

1 · Create account & log in (2 minutes)

2 · Layout: desktop vs phone

3 · Friends, Find & Nearby

4 · Chat like a pro

5 · Groups & Spaces

6 · Make it yours + stay notified + Plus

🗺️ Five journeys, end to end

The journey of a message

Code refs: backend/src/modules/messages/messages.service.js (createMessage) · backend/src/modules/notifications/notifications.service.js (createForMessage) · backend/src/socket/io.js (emitToConversation) · frontend/lib/outbox.js + components/outbox/outbox-flusher.jsx · frontend/lib/cache.js.

Tech stack + why each choice

Monorepo, no microservicesJS onlyRedis planned, NOT used

Architecture, API & file tour

Networking rule (interview favorite)

REST uses relative /api/… → Next.js rewrites (next.config.mjs) to BACKEND_URL (default http://localhost:4000), staying same-origin so sameSite=strict httpOnly cookies flow without CORS. Socket.IO dials NEXT_PUBLIC_API_URL directly — rewrites can't proxy WebSocket upgrades. Config: frontend/lib/api.js (fetch + auto-refresh) · components/socket-provider.jsx.

Request lifecycle (example: send message)

CopyPOST /api/v1/conversations/:id/messages
Authorization: Bearer <15m JWT>
{"content":"hey!","replyToMessageId":null}

routes.js → auth() → rateLimiter(send 40/min) → controller
  → service: Zod validate → membership/ban/block check
  → getRequesterPlan() limits → Message.create()
  → Conversation.lastMessageAt touch
  → notifications.createForMessage() [bulk insertMany + async push]
  → io.emitToConversation(id,"message:new",msg) → 201

Module mounts

Errors: {success:false, error:{code,message}} — prod never leaks stacks/secrets/paths (middleware/errorHandler.js). Frontend tour: app/ routes · components/dashboard/* shell/panels · lib/theme.js truth · lib/cache.js outbox.js drafts.js.

Data models — MongoDB is truth

Never embed messagesPins/saves = fieldsThreads reuse Message

Socket.IO: rooms, presence, receipts

Copy// client minimal (frontend)
import { io } from "socket.io-client";
const s = io(process.env.NEXT_PUBLIC_API_URL, { auth: { token } });
s.on("message:new", m => m.threadId ? openThread(m) : appendChat(m));
s.emit("conversation:focus", { conversationId }); // suppresses its DM notifs
s.emit("message:delivered", { messageId });

Identity, trust, and guards

Rate limits — in-memory fixed window (middleware/rateLimiter.js)

Per-user else IP · X-RateLimit-* + Retry-After · 5-min unref sweep · per-process (shared store only if multi-instance).
register 5/h/IP · login 10/15m · 2FA code 10/5m/IP · setup 5/5m · verify-code 5/60s · refresh 30/60s · forgot 5/5m · reset 10/5m · resend 1/m · send 40/m · edit 20/m · reactions 60/m · friend-req 20/h · user-search 30/m · nearby 30/m · location 10/m · space/channel 10/h · uploads 10/m · search 30/m · link-preview 30/m · call-token 20/m · status 10/day + feed 30/m + view 60/m · plus-claim 5/day · admin-login 5/15m · oauth-link 10/60s.

Security checklist (say this in interviews)

How each feature actually works

👥 Friends · Find · Nearby

Request by username/email/name + optional welcome 280 (stored + 80-char notif snippet → Quote bubble). Blocked both-ways → BLOCKED_USER. Directed-unique; reverse auto-accepts. Remove = shared edge deleted both sides + friend:removed live; history stays. Find: debounced 30/min, blocked/banned filtered, square cards (profile-preview-card.jsx) + modal with/without message. Nearby full-screen (nearby-screen.jsx like Appearance; rail + Menu → Nearby; FriendsModal tab): default ON, Settings → Privacy OFF clears; one-shot getCurrentPosition 12s → POST /me/location 10/min (reject accuracy>200/OFF) → Point + 2dsphere; GET /nearby?radius=1/2/5/10km 30/min $geoNear fuzz <1km→50m ≥1km→0.1km, filters banned/blocked-both/friends+pending+declined/stale>15m/hidden, nearest. Consent kivo:nearbyConsent; Permissions-Policy geolocation=(self).

💬 Messaging core

DM create-or-return ($all). List by lastMessageAt desc + unread (not-mine ∧ not-readBy) + online. Cursor newest-first + hasMore, scroll-up infinite, around jump, after catch-up. Optimistic sent→delivered→read + retry (chat-panel.jsx memoized MessageRows, O(1) byId). Menu: react strip, copy, save, profile, block, reply, thread, forward, pin, select (multi copy/forward/delete), Share mobile. ❤️ double-tap (500ms throttle). Edit own (Plus unlimited else 15m, history 10, ↑-on-empty), soft-delete (blanked, pin cleared). System chips never bump unread. Remove from list (DM either side, group admin, channels 403) = permanent both-sides + conversation:removed + confirm modal.

Reply replyToMessageId inline (deleted = placeholder). Forward bare {forwardedFromId} both-memberships-checked → forwardedFromName pill, no caption/mention-resolve, forwardCount. Pin any member POST /:id/pin timestamp, newest-first max10 banner, pin-updated. Threads threadId=root (roots null) excluded from timeline/cursors/search/pinned/unread/cache; quiet (no badge/bell, mentions still notify); content-required, no quote/forward inside, live root non-system non-reply only; list (root+count/last/participants → chips) + panel oldest-first 500; same message:* routed by threadId (thread-panel.jsx). Saved POST /:id/save → savedBy, flag at read, GET /saved newest-first 200 (Plus 1K), personal cross-device, deleted drops, jump. Mentions @-autocomplete participants-only → @username highlight (mention-autocomplete.jsx), override muted (if Mentions on).

📊 Polls · 🟢 Status · 📎 Files & voice · 📞 Calls

Polls (polls/poll-card.jsx): type poll + poll{question140, opts 2–8×60, voters, multi, anon, expiry, closed, total}. Free 5/24h/single; Plus 8/7d/multi+anon. vote/retract/end-early; poll:updated/ended; 60s sweep; searchable.

Status 24h friends-only (status/*): text280 + 6 backgrounds OR photo (jpg/png/webp/gif ≤30MB, 1/status) + caption280. Vertical tab My-top + grouped friends, green #25D366/grey rings, viewer 5s photo advance + caption + dots, 10/day, Appwrite attachments bucket, hourly file-then-doc sweep, status:new/deleted/viewed + isViewed. Mobile 5th tab.

Attachments (chat/attachments.jsx): browser → backend allow-list + 30MB → Appwrite bucket (images, docs pdf/doc(x)/xls(x)/ppt(x)/txt, audio webm/ogg/mp3/m4a/aac/wav — bucket extensions must include audio). 10/msg (Plus 20; 100MB). Progress + caption + lightbox (arrows/download) + doc cards + Media/Files/Links drawer (chat-media-drawer.jsx) with counts + jump + empty states. Voice: hold mic MediaRecorder→bare MIME (no transcode), slide-up cancel, timer, needs net; 32-bar deterministic pseudo-waveform (fileId seed, CSS divs, no fetch), tabular-nums timer, shared <audio> singleton, slider seek (click, ←/→±5s, Home/End, Space), responsive, audioDuration preserved on forward.

Calls — LiveKit SFU (calls/*): deterministic rooms kivo_<conv>, 6h tokens POST /calls/token (membership/ban/block, 20/min), GET /config gates buttons, GET /status Join pill. Socket ring only (30s → missed chip + bell + 📞CALL: history started/cancelled/declined/missed/ended + duration + Call back). Panel: mute/camera/devices/leave, voice→video upgrade, mirrored selfie, group grid+headcount, reconnect banner, iOS unlock; lazy client SSR-safe, manual themed tracks.

🔔 Notifications · 📱 Offline · 🔎 Search · 🔗 Previews · 📝 Polish

Bell (notifications/*): DMs/groups/Spaces/announcements/mentions/requests+accepts/waves; cursor pages + mark-all; click deep-links. Prefs per category (Space OFF default; mentions break through; wave ungated 20s). Focus/blur suppression. Sounds Web Audio per category + master + preview (lib/sound.js, kivo:sounds). Perf: insertMany + batch prefs + async VAPID; 404/410 prune. Push: opt-in (bell first-ask), per-user subs, SW click → chat (public/sw.js, lib/push.js, pwa-register.jsx).

PWA/offline: manifest + sw installable; precache shell + hashed /_next/static cache-first; navigations network-first → cached shell → styled offline (public/offline.html); API/Socket never intercepted. IndexedDB (lib/cache.js) lists + last-50/chat SWR + restore last open + Space expand. Outbox (lib/outbox.js) durable per-account text queue, survives reload, flushes on reconnect; attachments need net; dual-signal banner.

Search Ctrl+K (dashboard/search-overlay.jsx): messages+people+spaces + jump highlight (Plus 20/cat vs 5). Blocked/banned filtered. Previews (chat/link-preview.jsx, lib/links.js): first URL → card (image/title/2-line/domain); server 8s/1.5MB regex parse + relative resolve, 1h/500 cache, SSRF-guarded (http(s), no localhost/private/link-local on host + DNS + redirect); empty stays plain; client 200-cache, broken→text-only. Polish (derived, zero schema): day dividers Today/Yesterday/weekday/date; big emoji 1–3 grapheme-aware (lib/emoji.js, Intl.Segmenter) 44/36/30px chromeless; jump pill (120px pin, 200px threshold, own sends pin); drafts per-conv (lib/drafts.js 250ms/50-chat/4000-clamp); paste-image→queue; swipe ~45px lock + haptics.

👤 Profiles · 👋 Wave · 🎨 Emoji · 👑 Plus

Profiles (dashboard/profile-edit-modal.jsx, profile/*): name50/handle/bio280/status60 + chip8 (32 + 6 vibes) + photo4MB + 10 frames (Default, My-accent, solids, gradients) + banner (curated GIFs; Plus custom 8MB PATCH /me/banner, old retired) + effects none/glow/gradient-name/aura (kivo-pfx-*, server-clamped, downgrade→none) + flag + graph + social chips (social-links.jsx) + pronouns + auto-clear + privacy toggles. Public /u/:username (app/u/[username]): no-login, Plus flourishes, owner-theme skin (lib/profile-skin.js), Share + QR + copy + native Share, Join nudge, Message/Add/Accept/Block/Unfriend. Verified admin-granted + showBadge toggle; Google/GitHub chips.

Wave: notification not message. POST /notifications/:id/wave → wave + senderUsername, 20s cooldown, self/blocked rejected, in-app else VAPID, deep-links to sender, countdown button. Emoji 3-tier (emoji-factory-panel.jsx, lib/custom-emoji.js): Global admin 200 / Space Plus-admin 100 / Personal Plus 50 everywhere; →webp (gif kept) 2MB sharp; emoji bucket (fallback attachments); :name: + custom:id reactions; IDB SWR; emoji:new/deleted.

Plus UPI self-serve (plus/plus-screen.jsx, modules/plus/*, lib/plus.js PLAN_LIMITS): pay published UPI ID ₹49 → paste 12-digit UTR (POST /plus/claim 5/day) → admin queue ≤24h → 30d grant (PLUS_DURATION_MS). /plus pricing+steps+status. Expired reads free (getEffectivePlan, never trust client); hourly sweepPlus lapses + scrubs effects. Admin POST /admin/users/:id/plan + audit.

🏠 Spaces detail

Create → auto #general (each channel = own Conversation). Text (all) vs announcement (admin+; anyone may thread-reply). Admin+ channels (last protected). Roles member↔moderator (admin+), admin owner-only, no direct owner, last-owner protected, self-leave auto-promotes. Public → Discover (search/category, one-click); private hidden + single rotating 7d code (Privacy & invites; New invalidates, Off closes; never in payloads; /app?join=CODE + Discover box). Space look (accent+tint+wallpaper+bubbles, live preview, per-field "Member's own", Reset→personal) scopes members' channel view. Owner-only delete kills channels+messages. Files: spaces/*.

Theme system — live demo

Engine (lib/theme.js): derivePalette() washes only surface tokens (base/surface/elevated/border/scrollbars/bubbleReceived) preserving lightness — contrast never breaks. tintStrength 0.2 dark / 0.14 light; isChromatic rejects near-gray; accent sets badge/soft/onAccent via luminance. resolveChatLook() (lib/chat-style.js): conversation → Space → personal per field, null = "Member's own". Wallpapers pure CSS color-mix() (none/dots/grid/diagonal/bubbles/wash); bubbles kivo-bubbles-* (rounded/pill/squared/outline-mine). Partial merges; conversation:updated repaints live; rings follow accent; /u wears owner skin (profile-skin.js).

What keeps it fast (and what to measure)

Why this, not that

Run yourself, configure & deploy

Copy# backend (terminal 1)
cd backend && bun install
cp .env.example .env   # fill MongoDB/JWT/Appwrite/VAPID/Gmail/LiveKit/ADMIN_*
bun run dev            # http://localhost:4000  (prod: bun run start)

# frontend (terminal 2)
cd frontend && bun install
echo "NEXT_PUBLIC_API_URL=http://localhost:4000" > .env.local
bun run dev            # http://localhost:3000  (prod: build + start)
bun run lint           # Biome check
# push: npx web-push generate-vapid-keys  → VAPID_* in backend .env
# calls stay hidden until LIVEKIT_* set; storage errors until APPWRITE_* set

Environment variables

Deploy checklist

Questions & answers

🙋 Everyday FAQ (no jargon)

Terms, plainly

Roadmap & limits

Shipped (Phase 1 + 1.5): DMs, groups, Spaces/channels, notifications + prefs + push, PWA + offline + outbox, 10 themes + studio + Space palettes + chat look, attachments + voice waveform, profiles + badges + blocking + wave + QR, friends + welcome + Nearby, polls, Status text+photo, threads + saved + forward + pin, Ctrl+K search, link previews, LiveKit calls, 2FA, OAuth, custom emoji, Plus UPI, admin panel, media gallery, delete, Seen-by, drafts/swipe/jump/dividers/big-emoji.
Next (Phase 2–4): stronger search, video attachments, voice rooms, screen share, recording, bots/webhooks, dev platform, mini-apps, theme marketplace.
Not / limits: no E2E encryption (server sees plaintext) · offline history = last-50/chat · no video attachments yet · single-instance presence (needs shared adapter to scale) · disappearing messages removed 2026-09-08. If you demo this, say the limits out loud — interviewers trust it more.