# vanshsingh7/linksphere architecture

> Architecture diagram of the GitHub repository vanshsingh7/linksphere, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vanshsingh7/linksphere
- Repository: https://github.com/vanshsingh7/linksphere

## Overview

#### 1. Purpose and Runtime Topology
LinkSphere is a Discord-like communication system: authenticated users manage community servers, channels, messages, friends, direct messages, uploads, and WebRTC calls. It is a split React/Vite client and Node/Express backend, with Socket.io sharing the backend HTTP runtime.
- `client/src/main.jsx`
- `server/server.js`
- `server/app.js`

#### 2. Client Entry, Routing, and Application Shell
The browser entry mounts React; the router separates public landing/auth/OAuth pages from the protected application and settings experiences. The main app page is the UI integration point for server/channel/chat workflows, while modal components handle server creation, editing, and joining.
- `client/src/main.jsx`
- `client/src/App.jsx`
- `client/src/pages/AppPage.jsx`

`ProtectedRoute` gates authenticated client routes, while `AuthContext` owns client-side session/user state. The client calls the API through its configured backend base URL.
- `client/src/components/ProtectedRoute.jsx`
- `client/src/context/AuthContext.jsx`
- `client/src/apiConfig.js`

#### 3. Backend API Composition and Request Boundary
`server/app.js` configures the Express application and mounts domain route groups: authentication, users, servers, DMs, friends, and uploads. Route modules delegate to controllers; authentication, validation, and centralized errors form the request boundary before business logic or persistence.
- `server/app.js`
- `server/routes/serverRoutes.js`
- `server/middleware/authMiddleware.js`

Core business domains are separated into controllers for user/auth profile operations, server/channel/message/member/invite operations, friendship, and direct messages.
- `server/controllers/serverController.js`
- `server/controllers/dmController.js`
- `server/controllers/friendController.js`

#### 4. Identity and Access Control
Local signup/login use JWT-based authentication with password hashing; authenticated requests pass through JWT verification. Google OAuth is configured through Passport and returns users to the client OAuth flow. Authorization is material for server ownership/membership and protected user, messaging, and upload actions.
- `server/routes/authRoutes.js`
- `server/config/passport.js`
- `server/models/User.js`

#### 5. Persistent Collaboration Data
MongoDB is the system of record, reached through Mongoose connection setup. User documents represent identity, relationship/presence fields, and OAuth linkage. Server documents contain membership, ownership, invite, and embedded channel structure; channel messages and direct messages are independently persisted. Attachments model uploaded media metadata.
- `server/database/db.js`
- `server/models/Server.js`
- `server/models/Message.js`

- `server/models/DirectMessage.js`
- `server/models/Attachment.js`

Primary flow: client fetches server/DM history through REST; mutation controllers validate authorization, write MongoDB records, and real-time delivery supplements persisted history.

#### 6. Real-Time Messaging, Presence, and Calling
Socket.io is initialized with the HTTP server and provides channel-room messaging, online presence, and WebRTC signaling. Socket identity/presence connects users to active sessions; persisted messages remain retrievable via REST. The client voice hook and call modal manage browser media and peer-connection lifecycle, with Socket.io relaying offers, answers, ICE candidates, and call state.
- `server/server.js`
- `client/src/hooks/useVoiceChannel.jsx`
- `client/src/components/CallModal.jsx`

WebRTC media is peer-to-peer; the backend is a signaling/presence coordinator rather than a media relay.

#### 7. External Services and Deployment Boundaries
MongoDB is required infrastructure. Cloudinary is the external object/media storage boundary, accessed by upload routes/helpers; resulting URLs are attached to profiles or messages. Google OAuth is optional external identity infrastructure. The React client is Vite-built and has Vercel deployment configuration, while Node runs the API and Socket.io service.
- `server/routes/uploadRoutes.js`
- `server/utils/cloudinaryHelper.js`
- `client/vercel.json`

Main entry points: [`server/app.js`](https://github.com/vanshsingh7/linksphere/blob/main/server/app.js) (Express API composition), [`server/server.js`](https://github.com/vanshsingh7/linksphere/blob/main/server/server.js) (HTTP + Socket.io runtime), [`server/database/db.js`](https://github.com/vanshsingh7/linksphere/blob/main/server/database/db.js) (MongoDB), [`client/src/App.jsx`](https://github.com/vanshsingh7/linksphere/blob/main/client/src/App.jsx) (Router & app shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_browser["Browser UI<br/>runtime"]
  node_client_entry["React entry<br/>entrypoint<br/>[main.jsx]"]
  node_router_shell["Router &amp; app shell<br/>ui composition<br/>[App.jsx]"]
  node_app_page["Community workspace<br/>page<br/>[AppPage.jsx]"]
  node_auth_context["Session state<br/>auth context<br/>[AuthContext.jsx]"]
  node_protected_route["Protected route<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_voice_call["Voice &amp; call UI<br/>WebRTC client"]
end

subgraph group_backend["Node Backend"]
  node_http_socket{{"HTTP + Socket.io runtime<br/>Node entrypoint<br/>[server.js]"}}
  node_express_app["Express API composition<br/>[app.js]"]
  node_auth_boundary["Authentication boundary<br/>JWT &amp; OAuth<br/>[authRoutes.js]"]
  node_auth_middleware["JWT authorization<br/>middleware<br/>[authMiddleware.js]"]
  node_server_routes["Server route group<br/>REST routes<br/>[serverRoutes.js]"]
  node_collaboration["Server collaboration<br/>controller"]
  node_dm_friends["DM &amp; friendship<br/>controllers<br/>[dmController.js]"]
  node_uploads["Upload service<br/>media boundary<br/>[uploadRoutes.js]"]
  node_realtime["Presence &amp; signaling<br/>Socket.io service<br/>[server.js]"]
end

subgraph group_data["Data &amp; External Services"]
  node_mongodb[("MongoDB<br/>system of record<br/>[db.js]")]
  node_cloudinary[("Cloudinary<br/>media storage")]
  node_google["Google OAuth<br/>identity provider<br/>[passport.js]"]
end

node_browser -->|"loads"| node_client_entry
node_client_entry -->|"mounts"| node_router_shell
node_router_shell -->|"guards app routes"| node_protected_route
node_protected_route -->|"reads session"| node_auth_context
node_router_shell -->|"renders workspace"| node_app_page
node_app_page -->|"REST history &amp; mutations"| node_http_socket
node_auth_context -->|"authenticated API calls"| node_http_socket
node_voice_call -->|"signaling and presence"| node_realtime
node_http_socket -->|"serves requests"| node_express_app
node_http_socket -->|"initializes"| node_realtime
node_express_app -->|"mounts auth routes"| node_auth_boundary
node_express_app -->|"applies to protected routes"| node_auth_middleware
node_express_app -->|"mounts"| node_server_routes
node_server_routes -->|"delegates"| node_collaboration
node_express_app -->|"delegates DM and friend routes"| node_dm_friends
node_express_app -->|"mounts upload routes"| node_uploads
node_auth_boundary -->|"OAuth identity"| node_google
node_collaboration -->|"persists collaboration data"| node_mongodb
node_dm_friends -->|"persists DMs and friendships"| node_mongodb
node_uploads -->|"stores media"| node_cloudinary
node_uploads -->|"records attachment URLs"| node_mongodb
node_realtime -.->|"supplements persisted history"| node_mongodb

click node_client_entry "https://github.com/vanshsingh7/linksphere/blob/main/client/src/main.jsx"
click node_router_shell "https://github.com/vanshsingh7/linksphere/blob/main/client/src/App.jsx"
click node_app_page "https://github.com/vanshsingh7/linksphere/blob/main/client/src/pages/AppPage.jsx"
click node_auth_context "https://github.com/vanshsingh7/linksphere/blob/main/client/src/context/AuthContext.jsx"
click node_protected_route "https://github.com/vanshsingh7/linksphere/blob/main/client/src/components/ProtectedRoute.jsx"
click node_voice_call "https://github.com/vanshsingh7/linksphere/blob/main/client/src/hooks/useVoiceChannel.jsx"
click node_http_socket "https://github.com/vanshsingh7/linksphere/blob/main/server/server.js"
click node_express_app "https://github.com/vanshsingh7/linksphere/blob/main/server/app.js"
click node_auth_boundary "https://github.com/vanshsingh7/linksphere/blob/main/server/routes/authRoutes.js"
click node_auth_middleware "https://github.com/vanshsingh7/linksphere/blob/main/server/middleware/authMiddleware.js"
click node_server_routes "https://github.com/vanshsingh7/linksphere/blob/main/server/routes/serverRoutes.js"
click node_collaboration "https://github.com/vanshsingh7/linksphere/blob/main/server/controllers/serverController.js"
click node_dm_friends "https://github.com/vanshsingh7/linksphere/blob/main/server/controllers/dmController.js"
click node_uploads "https://github.com/vanshsingh7/linksphere/blob/main/server/routes/uploadRoutes.js"
click node_realtime "https://github.com/vanshsingh7/linksphere/blob/main/server/server.js"
click node_mongodb "https://github.com/vanshsingh7/linksphere/blob/main/server/database/db.js"
click node_cloudinary "https://github.com/vanshsingh7/linksphere/blob/main/server/utils/cloudinaryHelper.js"
click node_google "https://github.com/vanshsingh7/linksphere/blob/main/server/config/passport.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_browser,node_client_entry,node_router_shell,node_app_page,node_auth_context,node_protected_route,node_voice_call toneBlue
class node_http_socket,node_express_app,node_auth_boundary,node_auth_middleware,node_server_routes,node_collaboration,node_dm_friends,node_uploads,node_realtime toneAmber
class node_mongodb,node_cloudinary,node_google toneMint
```

## Components

### React Client

- **Browser UI**: runtime · Authenticated collaboration client.
- [React entry](https://github.com/vanshsingh7/linksphere/blob/main/client/src/main.jsx): entrypoint · `client/src/main.jsx`
- [Router & app shell](https://github.com/vanshsingh7/linksphere/blob/main/client/src/App.jsx): ui composition · Separates public, protected, and settings experiences. · `client/src/App.jsx`
- [Community workspace](https://github.com/vanshsingh7/linksphere/blob/main/client/src/pages/AppPage.jsx): page · Integrates server, channel, and chat workflows. · `client/src/pages/AppPage.jsx`
- [Session state](https://github.com/vanshsingh7/linksphere/blob/main/client/src/context/AuthContext.jsx): auth context · `client/src/context/AuthContext.jsx`
- [Protected route](https://github.com/vanshsingh7/linksphere/blob/main/client/src/components/ProtectedRoute.jsx): route guard · `client/src/components/ProtectedRoute.jsx`
- [Voice & call UI](https://github.com/vanshsingh7/linksphere/blob/main/client/src/hooks/useVoiceChannel.jsx): WebRTC client · Manages media and peer connection lifecycle. · `client/src/hooks/useVoiceChannel.jsx`

### Node Backend

- [HTTP + Socket.io runtime](https://github.com/vanshsingh7/linksphere/blob/main/server/server.js): Node entrypoint · Hosts REST APIs and real-time connections. · `server/server.js`
- [Express API composition](https://github.com/vanshsingh7/linksphere/blob/main/server/app.js): application · Mounts domain route groups and request middleware. · `server/app.js`
- [Authentication boundary](https://github.com/vanshsingh7/linksphere/blob/main/server/routes/authRoutes.js): JWT & OAuth · Verifies JWTs and supports Google OAuth. · `server/routes/authRoutes.js`
- [JWT authorization](https://github.com/vanshsingh7/linksphere/blob/main/server/middleware/authMiddleware.js): middleware · `server/middleware/authMiddleware.js`
- [Server route group](https://github.com/vanshsingh7/linksphere/blob/main/server/routes/serverRoutes.js): REST routes · `server/routes/serverRoutes.js`
- [Server collaboration](https://github.com/vanshsingh7/linksphere/blob/main/server/controllers/serverController.js): controller · Handles servers, channels, messages, members, and invites. · `server/controllers/serverController.js`
- [DM & friendship](https://github.com/vanshsingh7/linksphere/blob/main/server/controllers/dmController.js): controllers · Handles direct messages and friend relationships. · `server/controllers/dmController.js`
- [Upload service](https://github.com/vanshsingh7/linksphere/blob/main/server/routes/uploadRoutes.js): media boundary · Stores media and attaches resulting URLs. · `server/routes/uploadRoutes.js`
- [Presence & signaling](https://github.com/vanshsingh7/linksphere/blob/main/server/server.js): Socket.io service · Coordinates rooms, presence, and WebRTC signaling. · `server/server.js`

### Data & External Services

- [MongoDB](https://github.com/vanshsingh7/linksphere/blob/main/server/database/db.js): system of record · Persists users, servers, messages, DMs, and attachments. · `server/database/db.js`
- [Cloudinary](https://github.com/vanshsingh7/linksphere/blob/main/server/utils/cloudinaryHelper.js): media storage · `server/utils/cloudinaryHelper.js`
- [Google OAuth](https://github.com/vanshsingh7/linksphere/blob/main/server/config/passport.js): identity provider · `server/config/passport.js`

## Connections

- Browser UI → React entry: loads
- React entry → Router & app shell: mounts
- Router & app shell → Protected route: guards app routes
- Protected route → Session state: reads session
- Router & app shell → Community workspace: renders workspace
- Community workspace → HTTP + Socket.io runtime: REST history & mutations
- Session state → HTTP + Socket.io runtime: authenticated API calls
- Voice & call UI → Presence & signaling: signaling and presence
- HTTP + Socket.io runtime → Express API composition: serves requests
- HTTP + Socket.io runtime → Presence & signaling: initializes
- Express API composition → Authentication boundary: mounts auth routes
- Express API composition → JWT authorization: applies to protected routes
- Express API composition → Server route group: mounts
- Server route group → Server collaboration: delegates
- Express API composition → DM & friendship: delegates DM and friend routes
- Express API composition → Upload service: mounts upload routes
- Authentication boundary → Google OAuth: OAuth identity
- Server collaboration → MongoDB: persists collaboration data
- DM & friendship → MongoDB: persists DMs and friendships
- Upload service → Cloudinary: stores media
- Upload service → MongoDB: records attachment URLs
- Presence & signaling → MongoDB: supplements persisted history