This project is a full-featured social network application similar to Facebook or Instagram.
👉 Users can:
- Create accounts (Public or Private)
- Share posts (with images and privacy settings)
- Follow other users (Accept/Decline requests)
- Chat in real-time (Private and Groups)
- Join communities and groups
- Receive real-time notifications
The system is built with a modern, scalable architecture divided into 3 main parts:
👉 What the user sees and interacts with. Built with React and Tailwind CSS.
👉 The brain of the application (logic + REST API + WebSockets).
👉 Relational database that stores all data safely and efficiently.
- User clicks "Create Post"
- Frontend sends an HTTP request to the backend
- Backend processes the request and validates data
- Data is saved in the PostgreSQL database
- Backend sends a success response
- Frontend updates the UI
- NestJS (Node.js framework)
- WebSockets (Real-time features via NestJS Gateway)
- REST API (with secure routes and middleware)
- Next.js (React framework - App Router)
- Tailwind CSS (for styling)
- Fetch API / Axios (for data fetching)
- React Context / Zustand (for state management)
- PostgreSQL (Relational Database)
The backend is modular. Each feature is isolated into its own module for scalability and maintainability.
src/
├── modules/
│ ├── auth/ # Login & registration (Sessions/Cookies, bcrypt)
│ ├── users/ # Profiles, public/private accounts
│ ├── posts/ # Feed, posts, comments, likes
│ ├── follows/ # Follow graphs, requests
│ ├── groups/ # Communities, group posts, events
│ ├── chat/ # Real-time WebSocket messaging
│ ├── notifications/ # Real-time alerts
│ ├── feed/ # Smart feed ranking algorithm
│ └── search/ # Full-text PostgreSQL search
├── common/ # Guards, interceptors, filters
├── database/ # Entities and migrations
└── main.ts
- Auth Module: Handles sessions, cookies, and password hashing (bcrypt). Endpoints include
/auth/register,/auth/login, and/auth/logout. - Posts Module: Core platform feature allowing image uploads, privacy toggles, and managing likes/comments.
- Chat Module: Uses WebSockets for real-time private/group messages, typing indicators, and online status.
- Groups Module: Allows creating communities, joining via invites, making group posts, and scheduling events.
The database schema is highly relational, connecting users, their content, and interactions.
- users:
id,email,password_hash,first_last_name,avatar_url,is_private,is_online,last_seen - sessions: Tracks active login tokens and expirations.
- follows:
follower_id,following_id - follow_requests: Manages pending follow requests for private profiles.
- blocked_users: Social privacy controls.
- posts:
id,user_id,content,image_url,privacy,likes_count,comments_count - comments: Allows threaded replies via
parent_id. - likes: Connects users to liked posts.
- saved_posts: Bookmarked content.
- groups:
id,creator_id,title,description - group_members: Manages roles (admin/member) and statuses.
- group_posts & events: Community content and scheduled events (with
event_responses).
- conversations & messages: Tracks sender, receiver, and read receipts (
sent/delivered/seen). - notifications: Triggers alerts (
type,reference_id,is_read). - activities: Advanced tracking for analytics.
The frontend uses Next.js App Router to organize pages clearly.
app/
├── (auth)/ # Login and Register pages
├── feed/ # Smart feed with popular posts and create post UI
├── profile/ # User profile, posts, followers/following lists
├── messages/ # Real-time chat interface
├── groups/ # Browse communities and view events
├── notifications/ # Live action alerts
- 🧠 Smart Feed: Ranks posts by engagement
(likes × 2) + comments + recencyrather than just chronological order. - 🔎 Search Engine: Uses PostgreSQL full-text search to find people, posts, and groups quickly.
- 💬 Real-Time System: Instantly delivers messages, typing indicators, read receipts, and handles "Online Status" via WebSockets.
- 🔐 Advanced Privacy: Granular controls for post visibility, blocking users, and setting entire accounts to "private".
- 📋 Moderation & Analytics: Built-in reporting system for toxic content and activity tracking to understand user behavior.
Docker ensures the application runs consistently across any environment using isolated containers:
- Backend Container: Hosts the NestJS server.
- Database Container: Hosts the PostgreSQL server.
- Frontend Container: Hosts the Next.js React app.
- Authentication & Users
- Posts & Follows
- Chat & Notifications
- Groups & Events
- Advanced Features (Feed, Search, Analytics)
This architecture is scalable, maintainable, and strictly follows industry standards. By completing this, you implement core full-stack features: scalable database schema design, real-time connection management, security, and smart algorithms.
🔥 This is a production-ready architecture.
The easiest way to run the entire application is using Docker. The provided docker-compose.yml sets up the Database, Redis, MinIO, Backend, and Frontend automatically.
- Docker & Docker Compose installed on your machine.
- Git to clone the repository.
-
Clone the repository
git clone https://github.com/soufianehamdach28/social-network.git cd social-network -
Start the application with Docker Compose
docker-compose up -d
-
Access the Application
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- MinIO Console: http://localhost:9001 (Credentials:
minioadmin/minioadmin) - PostgreSQL:
localhost:5432
Note: The backend container automatically installs dependencies, generates the Prisma client, and applies database migrations upon startup.
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.