How chandansahoo-cs/mesh-turborepo works
1. Repository shape
- This is a Turborepo-style monorepo with two runtime apps: apps/mesh-app (the main Next.js product) and apps/mesh-wss (a separate websocket presence service).
- The architecture is split between a browser-facing application and several realtime/backend services, rather than a single monolith.
2. Primary UI shell: mesh-app
- apps/mesh-app is a Next.js App Router application.
- Top-level routes are organized around product areas: authentication, friends/DMs, servers, server channels, and server member profiles.
- Route layouts under src/app/servers/[serverId], src/app/friends/[friendId], etc. create distinct shells for each collaboration context.
3. Feature-oriented frontend structure
- The frontend is strongly modularized under src/features/*.
- Each feature usually contains:
- api/ hooks for server state operations and queries,
- components/ for feature-specific UI,
- store/ for local UI state.
- This is the main boundary in the client app: UI routes compose feature modules rather than embedding domain logic directly in pages.
4. Convex as the main backend and data model
- apps/mesh-app/convex is the core backend layer.
- It contains the schema plus domain modules for users, servers, channels, members, roles, messages, reactions, friends, uploads, and conversation/thread logic.
- Generated Convex artifacts in _generated/ indicate the app uses Convex’s typed client/server contract as the canonical backend API.
5. Data flow for persistent application state
- Most persistent interaction flows follow the same path:
- page/component UI in src/app or src/features
- typed hook in src/features/*/api
- Convex query or mutation
- reactive updates pushed back to the UI.
- This is the main realtime loop for server channels, DMs, member lists, roles, messages, and reactions.
6. Domain boundaries in the backend
- The backend is partitioned by business capability:
- servers, channels, serverMembers, roles for server administration and access control,
- messages, reactions, friendMessages, friendReactions, friendConversation for conversation content,
- friendRequests for social graph workflows,
- users and auth for identity,
- upload for file/image attachment support.
- This separation mirrors the frontend feature boundaries and makes the architecture diagram naturally domain-centric.
7. Real-time collaborative state via Liveblocks
- The app uses Liveblocks for ephemeral collaboration concerns like typing indicators and room-based presence.
- Dedicated Next.js auth routes exist for different room scopes: friend rooms, friend threads, server channels, server members, and server threads.
- This suggests Liveblocks is used as a secondary realtime system alongside Convex, handling transient room state rather than persisted chat data.
8. Voice communication via LiveKit
- src/app/api/livekit/route.ts is the integration point for voice room access.
- Voice-related client code lives under src/components/rooms/VoiceRoom* and src/features/voice.
- The README indicates voice is “global,” meaning the voice session is not strictly bound to a single text channel page, so the voice subsystem is logically separate from the text chat tree.
9. Custom websocket service for user presence
- apps/mesh-wss is a standalone websocket server used to mark online/offline presence.
- The README calls out multitab support and heartbeat cleanup, so this service is responsible for connection lifecycle and stale-session handling, not message persistence.
- This is an important boundary: presence is not entirely delegated to Convex or Liveblocks.
10. Next.js API routes as integration bridges
- src/app/api/* contains small server-side endpoints that bridge the browser app to external realtime services and status actions.
- These include Liveblocks auth endpoints, the LiveKit auth endpoint, and a mark-status endpoint likely tied to presence/state transitions.
- They are not the primary business logic layer; they exist to mint tokens or perform trusted server-side actions.
11. Route-level product areas
- The app is organized around three major user experiences:
- authentication/onboarding,
- direct friendships and DMs,
- server-based communities with channels, roles, and member management.
- Each area has its own UI subtree and its own backend contracts, which is useful to reflect as separate clusters in an architecture diagram.
12. Shared UI and interaction primitives
- src/components holds reusable building blocks such as rooms, message lists, editors, presence trackers, reaction UI, modals, and hero/landing elements.
- The components/ui folder is a large shadcn/Radix-style design system layer.
- These components are composition primitives; they do not own domain state, but they are the glue used by multiple feature routes.
13. State management pattern
- Local UI state is split from backend state.
- Feature stores under src/features/*/store handle modal visibility, selected IDs, and panel controls.
- Backend-derived state comes from Convex hooks, while ephemeral collaboration state comes from Liveblocks, and voice/presence are handled by separate integrations.
14. Mental model for the diagram
- Draw the main app as a Next.js presentation layer in front.
- Behind it, show Convex as the persistent realtime data plane for chat, servers, roles, friends, and uploads.
- Add Liveblocks for ephemeral room collaboration, LiveKit for voice, and mesh-wss for presence/heartbeat.
- The key architectural idea is that the product combines multiple realtime systems, each owning a different kind of state.
Main entry points: convex Convex backend · app Next.js app · api API routes · components Shared UI
Components 17
mesh-app
Primary Next.js product app.
- Next.js app · App Router UI shell for auth, friends, and server workspaces.
apps/mesh-app/src/app - Auth routes · Authentication and onboarding screens.
apps/mesh-app/src/app/auth - Friends · Direct friendships, DMs, and friend profiles.
apps/mesh-app/src/app/friends - Servers · Server communities, channels, members, and roles.
apps/mesh-app/src/app/servers - API routes · Server-side endpoints for auth tokens and trusted actions.
apps/mesh-app/src/app/api - Feature modules · Domain-oriented client modules that pair API hooks, UI, and local stores.
apps/mesh-app/src/features - Shared UI · Reusable UI primitives, room shells, editors, modals, and presence widgets.
apps/mesh-app/src/components
Backend
Persistent realtime data and external integrations.
- Convex backend · Main reactive backend for app state, domain logic, and generated client/server bindings.
apps/mesh-app/convex - Schema · Canonical data model for users, servers, channels, members, messages, reactions, and uploads.
apps/mesh-app/convex/schema.ts - Social domain · Identity, friends, requests, and friend conversations.
apps/mesh-app/convex/friendRequests.ts - Community domain · Servers, channels, memberships, roles, and server conversations.
apps/mesh-app/convex/servers.ts - Chat domain · Messages and reactions for server and friend conversations.
apps/mesh-app/convex/messages.ts - Uploads · File and image attachment support.
apps/mesh-app/convex/upload.ts - Generated API · Generated Convex client/server artifacts used by the app.
apps/mesh-app/convex/_generated/api.js
Realtime
Ephemeral collaboration and presence systems.
- Liveblocks · Room-based presence and transient collaboration state for text rooms.
apps/mesh-app/liveblocks.config.ts - LiveKit · Voice room access and global voice sessions.
apps/mesh-app/src/app/api/livekit/route.ts - mesh-wss · Standalone websocket service for online/offline presence and heartbeat cleanup.
apps/mesh-wss/src/index.ts
Connections 21
- Next.js app → Auth routes: renders · Top-level auth experience.
- Next.js app → Friends: renders · Friend and DM experience.
- Next.js app → Servers: renders · Server community experience.
- Next.js app → API routes: calls · Browser app relies on trusted server routes for token minting and status actions.
- Next.js app → Feature modules: composes · Route screens are built from feature modules.
- Next.js app → Shared UI: uses · Shared presentation and interaction primitives.
- Next.js app → Generated API: queries/mutates · Typed backend contract consumed by client hooks.
- Feature modules → Convex backend: hooks into · Feature API hooks map UI actions to Convex operations.
- Convex backend → Schema: defines · Schema anchors the persistent data model.
- Convex backend → Social domain: contains · Identity and social graph logic.
- Convex backend → Community domain: contains · Server administration and membership logic.
- Convex backend → Chat domain: contains · Persistent messaging and reaction logic.
- Convex backend → Uploads: contains · Attachment upload flow.
- Convex backend → Generated API: generates · Typed client/server API artifacts.
- API routes → Liveblocks: auths · Issues Liveblocks auth tokens for scoped rooms.
- API routes → LiveKit: auths · Issues LiveKit access for voice rooms.
- API routes → mesh-wss: marks status · Trusted endpoint for presence/status transitions.
- Shared UI → Liveblocks: shows presence · Room UI includes ephemeral collaboration state.
- Shared UI → LiveKit: hosts voice · Voice room components wrap LiveKit sessions.
- mesh-wss → Convex backend: separate from · Presence is handled outside Convex persistence.
- Liveblocks → Convex backend: alongside · Transient room collaboration complements persistent chat data.