vanshsingh7/linksphere

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