WorldConnect — Real-Time Social Platform

WorldConnect is a feature-rich, premium social networking and chat application. It is designed to match users globally using their languages and interests. It features real-time notifications, typing statuses, online presences, settings customization, and a comprehensive chat client.

---

Architecture Overview

graph TD
    Client[Next.js Client] <-->|HTTP/REST & Socket.IO| Server[Express Server]
    Server <-->|Prisma ORM| Database[(PostgreSQL Database)]

Loading

Frontend Architecture

• Framework: Next.js (using App Router).
• Styling: Vanilla CSS for maximum flexibility and performance.
• State Management: Zustand stores manage lightweight state caches (e.g., authentication, toasts).
• Socket Client: Socket.IO Client handles real-time connection pooling and reconnect logic.
• Data Hook Orchestration: Custom hooks (e.g., useConversation, useProfile, useSearch) manage domain-specific state encapsulation.

Backend Architecture

• Framework: Express.js with TypeScript (tsx for dev run, tsc for production).
• ORM: Prisma client interacting with Supabase PostgreSQL.
• Real-Time Gateway: Socket.IO Server managing socket presence updates, rooms, and namespace broadcasts.

---

Folder Structure

WorldConnect/
├── client/                      # Next.js Frontend
│   ├── src/
│   │   ├── app/                 # Page route trees (Explore, Messages, Settings, Profile, Auth)
│   │   ├── components/          # React components (common UI elements, layout wrappers)
│   │   ├── hooks/               # State hooks (useConversation, useProfile, useSettings, useAuth)
│   │   ├── lib/api/             # Axios REST client API request modules
│   │   ├── providers/           # Context providers (SocketProvider, ThemeProvider)
│   │   ├── services/            # Client singletons (socket.service, storage.service)
│   │   ├── store/               # Zustand caches (auth, toasts)
│   │   └── types/               # TypeScript domain model types
│   ├── eslint.config.mjs        # Client-side ESLint v10 configuration
│   └── package.json
├── server/                      # Express Backend
│   ├── src/
│   │   ├── config/              # Server configuration loaders (env, database, socket)
│   │   ├── database/            # Prisma instance bootstrap
│   │   ├── middleware/          # Express route middlewares (auth, upload, validation)
│   │   ├── modules/             # Server domain modules (auth, messages, profiles, notifications)
│   │   ├── socket/              # Socket event registry handlers (presence, typing, conversation)
│   │   └── server.ts            # Server entry point
│   └── package.json
└── package.json                 # Monorepo workspaces coordinator

---

Environment Variables

Client Setup (client/.env.local & client/.env)

Create the environment files in the client/ subdirectory:

NEXT_PUBLIC_API_URL=http://localhost:5000/api
NEXT_PUBLIC_WS_URL=http://localhost:5000

Server Setup (server/.env)

Create the environment file in the server/ subdirectory:

PORT=5000
DATABASE_URL=postgresql://<username>:<password>@<host>:<port>/<db_name>
DIRECT_URL=postgresql://<username>:<password>@<host>:<port>/<db_name>
JWT_SECRET=<your-jwt-secure-signing-secret>
SUPABASE_URL=https://<your-project>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>
SUPABASE_ANON_KEY=<anon-key>
CLIENT_URL=http://localhost:3000

---

Available Scripts

Run scripts from the monorepo root folder using npm workspace targets:

• Start Development: Starts client (port 3000) and server (port 5000) concurrently:

  npm run dev

• Lint Codebase: Lints client app:

  npm run lint

• Build Application: Build both client and server:

  npm run build

• Prisma Studio: Launches local database viewer:

  npx prisma studio --schema=server/prisma/schema.prisma

---

Real-Time Socket.IO Protocol API

The real-time gateway synchronizes notifications, chat bubbles, and indicators.

Events Listened by Server

• conversation:join: Subscribes the client to thread message updates.
  • Payload: { conversationId: string }
• conversation:leave: Unsubscribes from thread message updates.
  • Payload: { conversationId: string }
• typing:start: Signals that the client is composing a message in a thread.
  • Payload: { conversationId: string }
• typing:stop: Signals that composer typing has ceased.
  • Payload: { conversationId: string }

Events Emitted by Server

• presence:updated: Broadcasts a user's connection status change.
  • Payload: { profileId: string, status: 'ONLINE' | 'OFFLINE', lastSeen: string | null }
• message:new: Notifies active thread subscribers of a new chat message.
  • Payload: { conversationId: string, message: Message }
• message:read: Notifies sender that the recipient has read the messages.
  • Payload: { conversationId: string, readBy: string, readAt: string }
• typing: Forwards typing indicator triggers to the thread recipient.
  • Payload: { conversationId: string, profileId: string, username: string, displayName: string }
• typing:ended: Tells recipient that the sender stopped composing.
  • Payload: { conversationId: string, profileId: string, username: string, displayName: string }
• notification:new: Pushes live notification entries to specific users.
  • Payload: Notification object