PINGUP 📱

Connect, Share, and Engage in Real-Time

Powered by cutting-edge technologies:

LIVE - DEMO 🌐

Visit the 👉 LINK 🔗

Profile Page	Home Page

---

Table of Contents

• Overview
• Key Features
• Tech Stack
• Architecture
• Getting Started
  • Prerequisites
  • Installation
  • Environment Variables
• Core Functionality
• API Endpoints
• Deployment
• Performance
• Contributing
• License
• Support

---

Overview

PINGUP is a full-featured social media platform that provides:

• 👥 Social Networking: Connect with friends and discover new people
• 💬 Real-time Messaging: Instant chat with typing indicators
• 📱 Stories Feature: Share ephemeral content that disappears in 24 hours
• 📸 Media Sharing: Upload and share images with optimized delivery
• 🔍 Discoverability: Find and connect with users based on interests
• ⚡ Background Processing: Efficient handling of async tasks with Inngest

Built with the MERN stack and designed for modern social interactions.

---

Key Features

🔐 Authentication & Security

• Clerk Integration: Secure authentication with social login options
• JWT Tokens: Stateless authentication for API requests
• Protected Routes: Role-based access control
• Session Management: Secure user sessions

💬 Real-time Communication

• Instant Messaging: One-on-one and group chats
• Typing Indicators: Real-time feedback when users are typing
• Message Status: Read receipts and delivery confirmations
• Online Presence: User online/offline status

📱 Social Features

• Post System: Share text and image content with followers
• Stories: 24-hour ephemeral content with viewer tracking
• Follow/Unfollow: Build your social network
• Friend Requests: Manage connections with approval system
• News Feed: Personalized content based on connections
• Notifications: Real-time alerts for social interactions

🖼️ Media Management

• ImageKit Integration: Optimized image storage and delivery
• File Uploads: Support for multiple image formats
• Image Optimization: Automatic resizing and compression
• CDN Delivery: Fast global content delivery

⚙️ Background Processing

• Inngest Integration: Efficient background job processing
• Scheduled Tasks: Automated cleanup and maintenance
• Email Notifications: Welcome emails and alerts
• Async Operations: Non-blocking background processing

---

Tech Stack

Frontend (Client)

• React 18+ - Modern React with hooks and context
• Axios - HTTP client for API communication
• Redux Toolkit - State management (store.js)
• React Router - Client-side navigation
• Custom Hooks - Feature-specific logic encapsulation

Backend (Server)

• Node.js - JavaScript runtime environment
• Express.js - Web application framework
• MongoDB - NoSQL database for flexible data storage
• Mongoose - MongoDB object modeling
• Socket.io - Real-time bidirectional communication
• Inngest - Background job processing
• ImageKit - Image optimization and CDN
• Nodemailer - Email notification system
• JWT - Authentication tokens

DevOps & Deployment

• Vercel - Frontend deployment platform
• Render/Railway - Backend deployment
• MongoDB Atlas - Cloud database service
• ImageKit CDN - Media content delivery

---

Architecture

PingUp/
├── client/                 # React Frontend
│   ├── src/
│   │   ├── api/           # API configuration
│   │   │   └── axios.js   # Axios instance
│   │   ├── app/           # Redux store
│   │   │   └── store.js   # State management
│   │   ├── assets/        # Static assets
│   │   ├── components/    # Reusable UI components
│   │   │   ├── Loading.jsx
│   │   │   ├── MenuItems.jsx
│   │   │   ├── Notification.jsx
│   │   │   ├── PostCard.jsx
│   │   │   ├── ProfileModal.jsx
│   │   │   ├── RecentMessages.jsx
│   │   │   ├── Sidebar.jsx
│   │   │   ├── StoriesBar.jsx
│   │   │   ├── StoryModal.jsx
│   │   │   ├── StoryViewer.jsx
│   │   │   ├── UserCard.jsx
│   │   │   └── UserProfileInfo.jsx
│   │   ├── features/      # Feature-based organization
│   │   │   ├── connections/
│   │   │   ├── messages/
│   │   │   └── user/
│   │   ├── pages/         # Route components
│   │   │   ├── ChatBox.jsx
│   │   │   ├── Connections.jsx
│   │   │   ├── CreatePost.jsx
│   │   │   ├── Discover.jsx
│   │   │   ├── Feed.jsx
│   │   │   ├── Layout.jsx
│   │   │   ├── Login.jsx
│   │   │   ├── Messages.jsx
│   │   │   └── Profile.jsx
│   │   └── ...           # Config files
│
├── server/                # Express Backend
│   ├── configs/          # Configuration files
│   │   ├── db.js         # Database configuration
│   │   ├── imageKit.js   # ImageKit configuration
│   │   ├── multer.js     # File upload configuration
│   │   └── nodeMailer.js # Email configuration
│   ├── controllers/      # Business logic
│   │   ├── messageController.js
│   │   ├── postController.js
│   │   ├── storyController.js
│   │   └── userController.js
│   ├── inngest/          # Background jobs
│   │   └── index.js
│   ├── middlewares/      # Custom middlewares
│   │   └── auth.js
│   ├── models/           # Database models
│   │   ├── Connection.js
│   │   ├── Message.js
│   │   ├── Post.js
│   │   ├── Story.js
│   │   └── User.js
│   ├── routes/           # API routes
│   │   ├── messageRoutes.js
│   │   ├── postRoutes.js
│   │   ├── storyRoutes.js
│   │   └── userRoutes.js
│   └── server.js         # Server entry point

---

Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm (v8 or higher)
• MongoDB Atlas account or local MongoDB
• ImageKit account
• Clerk account
• Inngest account

Installation

1. Clone the repository:

git clone https://github.com/elyse502/PingUp.git
cd PingUp

2. Install client dependencies:

cd client && npm install

3. Install server dependencies:

cd ../server && npm install

Environment Variables

Client (.env)

VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
VITE_API_BASE_URL=http://localhost:5000
VITE_IMAGEKIT_URL_ENDPOINT=your-imagekit-endpoint
VITE_IMAGEKIT_PUBLIC_KEY=your-imagekit-public-key

Server (.env)

MONGODB_URI=your-mongodb-connection-string
CLERK_SECRET_KEY=sk_test_...
IMAGEKIT_PRIVATE_KEY=your-imagekit-private-key
INNGEST_EVENT_KEY=your-inngest-event-key
INNGEST_SIGNING_KEY=your-inngest-signing-key
EMAIL_SERVICE=your-email-service
EMAIL_USER=your-email-username
EMAIL_PASS=your-email-password
JWT_SECRET=your-jwt-secret
PORT=5000

4. Start the development servers:

# Terminal 1 - Start backend
cd server && npm run dev

# Terminal 2 - Start frontend
cd client && npm run dev

---

Core Functionality

🗂️ User Management

• User registration and authentication via Clerk
• Profile customization with avatars and bios
• Friend request system with approval workflow
• User search and discovery features

💬 Messaging System

• Real-time chat with Socket.io
• Conversation history persistence
• Typing indicators and read receipts
• Message notifications

📱 Content Sharing

• Create posts with text and images
• Like, comment, and share functionality
• News feed algorithm based on connections
• Hashtag and mention support

🎬 Stories Feature

• Upload images/videos as stories
• 24-hour expiration with auto-cleanup
• Viewer tracking and analytics
• Story reactions and replies

⚡ Background Jobs

• Email notifications for new messages
• Story expiration cleanup
• Periodic data backups
• Analytics and reporting generation

---

API Endpoints

Authentication Routes (/api/auth)

Method	Endpoint	Description
POST	/verify	Verify Clerk session
GET	/profile	Get user profile
PUT	/profile	Update user profile

User Routes (/api/users)

Method	Endpoint	Description
GET	/search	Search for users
POST	/follow	Follow a user
DELETE	/unfollow	Unfollow a user
GET	/connections	Get user connections

Post Routes (/api/posts)

Method	Endpoint	Description
GET	/feed	Get news feed
POST	/create	Create a new post
PUT	/like	Like a post
POST	/comment	Add comment to post

Message Routes (/api/messages)

Method	Endpoint	Description
GET	/conversations	Get user conversations
GET	/conversation/:id	Get specific conversation
POST	/send	Send a message

Story Routes (/api/stories)

Method	Endpoint	Description
POST	/upload	Upload a story
GET	/user/:id	Get user stories
GET	/feed	Get stories from connections

---

Deployment

Frontend (Vercel)

Backend (Render/Railway)

Deploy with environment variables configured for:

• MongoDB Atlas connection
• Clerk authentication
• ImageKit integration
• Inngest background processing

Database (MongoDB Atlas)

# Recommended: MongoDB Atlas Cloud
https://www.mongodb.com/atlas

Real-time Services

• Socket.io for real-time features
• Inngest for background jobs
• ImageKit for media optimization

---

Performance

• ⚡ Lighthouse Score: 90+
• 📦 Optimized Bundle Size with code splitting
• 🚀 Fast image loading with ImageKit CDN
• 📱 Mobile-first responsive design
• 🔒 Secure authentication with Clerk
• ⏱️ Efficient background processing with Inngest

---

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

License

Distributed under the MIT License. See LICENSE for more information.

---

Support

For support, email elyseniyibizi502@gmail.com or create an issue in the GitHub repository.

---

📞 Contact

For any questions or support, please contact:

• NIYIBIZI Elysée👨🏿‍💻 | Github | Linkedin | Twitter.
• Email: elyseniyibizi502@gmail.com

---

PINGUP - Where connections happen in real time! 🚀

Built with ❤️ using the MERN stack and modern web technologies.

Made with ❤️ by Elysée NIYIBIZI

⬆ Back to Top