# chandansahoo-cs/mesh-turborepo architecture

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

- Interactive diagram: https://gitdiagram.com/chandansahoo-cs/mesh-turborepo
- Repository: https://github.com/chandansahoo-cs/mesh-turborepo

## Overview

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: [`apps/mesh-app/convex`](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/convex) (Convex backend), [`apps/mesh-app/src/app`](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app) (Next.js app), [`apps/mesh-app/src/app/api`](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app/api) (API routes), [`apps/mesh-app/src/components`](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/components) (Shared UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monorepo["Monorepo"]
end

subgraph group_mesh_app["mesh-app"]
  node_mesh_app_next["Next.js app<br/>presentation shell"]
  node_mesh_app_routes_auth["Auth routes<br/>route area"]
  node_mesh_app_routes_friends["Friends<br/>route area"]
  node_mesh_app_routes_servers["Servers<br/>route area"]
  node_mesh_app_routes_api["API routes<br/>integration bridge"]
  node_features_core["Feature modules<br/>frontend modules"]
  node_shared_ui["Shared UI<br/>component library"]
end

subgraph group_backend["Backend"]
  node_convex_backend[("Convex backend<br/>persistent data plane")]
  node_convex_schema["Schema<br/>data model<br/>[schema.ts]"]
  node_convex_social["Social domain<br/>convex domain<br/>[friendRequests.ts]"]
  node_convex_community["Community domain<br/>convex domain<br/>[servers.ts]"]
  node_convex_chat["Chat domain<br/>convex domain<br/>[messages.ts]"]
  node_convex_upload["Uploads<br/>convex domain<br/>[upload.ts]"]
  node_convex_generated["Generated API<br/>typed contract<br/>[api.js]"]
end

subgraph group_realtime["Realtime"]
  node_liveblocks["Liveblocks<br/>ephemeral collaboration"]
  node_livekit["LiveKit<br/>voice integration<br/>[route.ts]"]
  node_mesh_wss["mesh-wss<br/>presence websocket<br/>[index.ts]"]
end

node_mesh_app_next -->|"renders"| node_mesh_app_routes_auth
node_mesh_app_next -->|"renders"| node_mesh_app_routes_friends
node_mesh_app_next -->|"renders"| node_mesh_app_routes_servers
node_mesh_app_next -->|"calls"| node_mesh_app_routes_api
node_mesh_app_next -->|"composes"| node_features_core
node_mesh_app_next -->|"uses"| node_shared_ui
node_mesh_app_next -->|"queries/mutates"| node_convex_generated
node_features_core -->|"hooks into"| node_convex_backend
node_convex_backend -->|"defines"| node_convex_schema
node_convex_backend -->|"contains"| node_convex_social
node_convex_backend -->|"contains"| node_convex_community
node_convex_backend -->|"contains"| node_convex_chat
node_convex_backend -->|"contains"| node_convex_upload
node_convex_backend -->|"generates"| node_convex_generated
node_mesh_app_routes_api -->|"auths"| node_liveblocks
node_mesh_app_routes_api -->|"auths"| node_livekit
node_mesh_app_routes_api -->|"marks status"| node_mesh_wss
node_shared_ui -->|"shows presence"| node_liveblocks
node_shared_ui -->|"hosts voice"| node_livekit
node_mesh_wss -.->|"separate from"| node_convex_backend
node_liveblocks -.->|"alongside"| node_convex_backend

click node_mesh_app_next "https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app"
click node_mesh_app_routes_auth "https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app/auth"
click node_mesh_app_routes_friends "https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app/friends"
click node_mesh_app_routes_servers "https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app/servers"
click node_mesh_app_routes_api "https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app/api"
click node_features_core "https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/features"
click node_shared_ui "https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/components"
click node_convex_backend "https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/convex"
click node_convex_schema "https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/schema.ts"
click node_convex_social "https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/friendRequests.ts"
click node_convex_community "https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/servers.ts"
click node_convex_chat "https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/messages.ts"
click node_convex_upload "https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/upload.ts"
click node_liveblocks "https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/liveblocks.config.ts"
click node_livekit "https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/src/app/api/livekit/route.ts"
click node_mesh_wss "https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-wss/src/index.ts"
click node_convex_generated "https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/_generated/api.js"

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_mesh_app_next,node_mesh_app_routes_auth,node_mesh_app_routes_friends,node_mesh_app_routes_servers,node_mesh_app_routes_api,node_features_core,node_shared_ui toneAmber
class node_convex_backend,node_convex_schema,node_convex_social,node_convex_community,node_convex_chat,node_convex_upload,node_convex_generated toneMint
class node_liveblocks,node_livekit,node_mesh_wss toneRose
```

## Components

### mesh-app

Primary Next.js product app.

- [Next.js app](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app): presentation shell · App Router UI shell for auth, friends, and server workspaces. · `apps/mesh-app/src/app`
- [Auth routes](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app/auth): route area · Authentication and onboarding screens. · `apps/mesh-app/src/app/auth`
- [Friends](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app/friends): route area · Direct friendships, DMs, and friend profiles. · `apps/mesh-app/src/app/friends`
- [Servers](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app/servers): route area · Server communities, channels, members, and roles. · `apps/mesh-app/src/app/servers`
- [API routes](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/app/api): integration bridge · Server-side endpoints for auth tokens and trusted actions. · `apps/mesh-app/src/app/api`
- [Feature modules](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/features): frontend modules · Domain-oriented client modules that pair API hooks, UI, and local stores. · `apps/mesh-app/src/features`
- [Shared UI](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/src/components): component library · Reusable UI primitives, room shells, editors, modals, and presence widgets. · `apps/mesh-app/src/components`

### Backend

Persistent realtime data and external integrations.

- [Convex backend](https://github.com/chandansahoo-cs/mesh-turborepo/tree/main/apps/mesh-app/convex): persistent data plane · Main reactive backend for app state, domain logic, and generated client/server bindings. · `apps/mesh-app/convex`
- [Schema](https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/schema.ts): data model · Canonical data model for users, servers, channels, members, messages, reactions, and uploads. · `apps/mesh-app/convex/schema.ts`
- [Social domain](https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/friendRequests.ts): convex domain · Identity, friends, requests, and friend conversations. · `apps/mesh-app/convex/friendRequests.ts`
- [Community domain](https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/servers.ts): convex domain · Servers, channels, memberships, roles, and server conversations. · `apps/mesh-app/convex/servers.ts`
- [Chat domain](https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/messages.ts): convex domain · Messages and reactions for server and friend conversations. · `apps/mesh-app/convex/messages.ts`
- [Uploads](https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/upload.ts): convex domain · File and image attachment support. · `apps/mesh-app/convex/upload.ts`
- [Generated API](https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/convex/_generated/api.js): typed contract · Generated Convex client/server artifacts used by the app. · `apps/mesh-app/convex/_generated/api.js`

### Realtime

Ephemeral collaboration and presence systems.

- [Liveblocks](https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/liveblocks.config.ts): ephemeral collaboration · Room-based presence and transient collaboration state for text rooms. · `apps/mesh-app/liveblocks.config.ts`
- [LiveKit](https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-app/src/app/api/livekit/route.ts): voice integration · Voice room access and global voice sessions. · `apps/mesh-app/src/app/api/livekit/route.ts`
- [mesh-wss](https://github.com/chandansahoo-cs/mesh-turborepo/blob/main/apps/mesh-wss/src/index.ts): presence websocket · Standalone websocket service for online/offline presence and heartbeat cleanup. · `apps/mesh-wss/src/index.ts`

## Connections

- 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.
