Loading repository data…
Loading repository data…
AbdolHamidDev / repository
Modern social media platform built with React, Node.js, and Python. Features real-time chat, stories, AI automation, and beautiful UI. Open source and free to use!
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
Production-grade social media platform built with microservices architecture. Real-time communication, AI automation, and modern UX.
Live Demo • Documentation • Report Bug • Request Feature
HooksDream is a full-stack social media platform demonstrating production-grade software engineering practices. Built with a microservices architecture separating concerns across Node.js (core API), React (frontend), and Python (AI/automation) services.
Key Characteristics:
┌─────────────────────────────────────────────────────────────┐
│ Client Layer │
│ React 18 + TypeScript + Vite + Tailwind CSS + PWA │
└───────────────────────┬─────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ REST │ │ WebSocket│ │ Push │
│ API │ │ Socket │ │Notify │
└────┬────┘ └────┬────┘ └─────────┘
│ │
┌────▼──────────────▼────┐
│ API Gateway Layer │
│ (Rate Limit + Auth) │
└───────────┬────────────┘
│
┌───────┴───────┐
│ │
┌────▼────┐ ┌────▼──────────┐
│ Node.js │ │ Python │
│ Backend │◄──►│ Backend │
│ Express │ │ FastAPI │
│ + MongoDB│ │ (AI/Bot) │
└─────────┘ └───────────────┘
│
┌────▼────────┐
│ Cloudinary │
│ (Media CDN) │
└─────────────┘
Design Principles:
| Technology | Purpose | Version |
|---|---|---|
| React | UI Framework | 18.x |
| TypeScript | Type Safety | 5.8 |
| Vite | Build Tool | Latest |
| Tailwind CSS | Styling | Latest |
| shadcn/ui | Component Library | Latest |
| TanStack Query | Data Fetching & Cache | Latest |
| Zustand | State Management | Latest |
| Socket.IO Client | Real-time Communication | Latest |
| React Hook Form + Zod | Form Management & Validation | Latest |
| i18next | Internationalization | Latest |
| Framer Motion | Animations | Latest |
| Vite PWA Plugin | Progressive Web App | Latest |
| Technology | Purpose | Version |
|---|---|---|
| Express.js | Web Framework | 4.x |
| MongoDB + Mongoose | Database & ODM | Latest |
| Socket.IO | Real-time Communication | Latest |
| JWT (jsonwebtoken) | Authentication | Latest |
| Cloudinary + Multer + Sharp | Media Upload & Processing | Latest |
| Node-cron | Scheduled Tasks | Latest |
| Web Push | Push Notifications | Latest |
| Express Rate Limit | API Protection | Latest |
| Cheerio | Web Scraping | Latest |
| Technology | Purpose | Version |
|---|---|---|
| FastAPI | API Framework | Latest |
| AsyncIO | Async Task Scheduling | Latest |
| Unsplash API | Image Sourcing | - |
| Bot Service | Social Media Automation | - |
| Technology | Purpose |
|---|---|
| Docker | Containerization |
| MongoDB Atlas | Managed Database |
| Render | Backend Hosting |
| Vercel | Frontend Hosting |
| Cloudinary | Media CDN & Processing |
HooksDream/
├── backend/ # Node.js API Service
│ ├── server.js # Entry point, server initialization
│ ├── routes/ # REST API routes
│ │ ├── auth.js # Authentication (register, login, OTP)
│ │ ├── users.js # User management
│ │ ├── posts.js # Post CRUD operations
│ │ ├── comments.js # Comment system
│ │ ├── follow.js # Follow/unfollow logic
│ │ ├── chat.js # Messaging endpoints
│ │ ├── notifications.js # Notification system
│ │ ├── search.js # Search functionality
│ │ ├── storyRoutes.js # Stories (ephemeral content)
│ │ ├── friendDiscovery.js # Friend recommendations
│ │ └── botRoutes.js # Bot integration
│ ├── controllers/ # Business logic layer
│ ├── models/ # Mongoose schemas
│ ├── middleware/ # Auth, validation, rate limiting
│ ├── services/ # Background services
│ ├── socket/ # Socket.IO handlers
│ └── utils/ # Helper functions
│
├── frontend/ # React Application
│ ├── src/
│ │ ├── pages/ # Route-level components
│ │ │ ├── FeedPage.tsx
│ │ │ ├── CreatePostPage.tsx
│ │ │ ├── PostDetailPage.tsx
│ │ │ ├── ProfilePage.tsx
│ │ │ ├── EditProfilePage.tsx
│ │ │ ├── StoriesPage.tsx
│ │ │ ├── MessagesPage.tsx
│ │ │ ├── NotificationsPage.tsx
│ │ │ ├── SearchPage.tsx
│ │ │ ├── FriendPageRQ.tsx
│ │ │ ├── MobileFriendPage.tsx
│ │ │ └── TermsOfUse.tsx
│ │ ├── components/ # Reusable UI components
│ │ │ ├── auth/ # Login, Register, OTP
│ │ │ ├── chat/ # Chat interface
│ │ │ ├── comment/ # Comments
│ │ │ ├── createpost/ # Post creation
│ │ │ ├── feed/ # Feed components
│ │ │ ├── layout/ # Layout shell
│ │ │ ├── modals/ # Modal dialogs
│ │ │ ├── navigation/ # Navigation bar
│ │ │ ├── notifications/ # Notification components
│ │ │ ├── posts/ # Post components
│ │ │ ├── profile/ # Profile components
│ │ │ ├── search/ # Search components
│ │ │ ├── story/ # Story components
│ │ │ └── ui/ # shadcn/ui primitives
│ │ ├── contexts/ # React Context providers
│ │ ├── hooks/ # Custom React hooks
│ │ ├── services/ # API service layer
│ │ ├── store/ # Zustand stores
│ │ ├── locales/ # i18n translations
│ │ └── utils/ # Utility functions
│ ├── package.json
│ ├── vite.config.ts
│ ├── tailwind.config.js
│ └── tsconfig.json
│
├── pyBackend/ # Python AI/Automation Service
│ ├── main.py # FastAPI application entry
│ ├── config.py # Configuration management
│ ├── requirements.txt # Python dependencies
│ ├── Dockerfile # Container config
│ ├── docker-compose.yml # Service orchestration
│ ├── routers/
│ │ └── bot_router.py # Bot API endpoints
│ ├── services/
│ │ ├── unsplash_service.py # Unsplash API integration
│ │ └── bot_service.py # Marcin bot automation
│ └── data/ # Data storage
│
├── docs/ # Documentation
│ ├── CONTRIBUTING.md
│ ├── DEPLOYMENT.md
│ └── SECURITY.md
│
├── Screenshots/ # UI screenshots
├── docker-compose.yml # Multi-service orchestration
├── LICENSE # MIT License
└── README.md # This file
1. Clone the repository
git clone https://github.com/AbdolHamidDev/HooksDream.git
cd HooksDream
2. Start with Docker (Recommended) 🚀
# Start all services (MongoDB + Backend + Frontend)
docker compose up -d
# View logs
docker compose logs -f
# Access the app
# Frontend: http://localhost:5173
# Backend: http://localhost:5000
# MongoDB: mongodb://localhost:27017
See DOCKER_DEV.md for detailed Docker setup and troubleshooting.
3. Or run locally with npm:
# Install all dependencies
npm run install:all
# Start both backend and frontend
npm run dev
4. Or manual setup:
cd backend
npm install
# Configure environment
cp .env.example .env
# Edit .env with your MongoDB URI, JWT secret, and Cloudinary credentials
# Start development server
npm run dev
cd frontend
npm install
# Configure environment
cp .env.example .env
# Set VITE_API_URL and VITE_SOCKET_URL
# Start development server
npm run dev
cd pyBackend
python -m venv venv
# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
pip install -r requirements.txt
# Configure environment
cp .env.example .env
# Start server
python run.py
# or
uvicorn main:app --reload
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/auth/register | User registration |
| POST | /api/auth/login | User login |
| POST | /api/auth/verify-otp | OTP verification |
| GET | /api/auth/me | Get current user |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/users/:id | Get user profile |
| PUT | /api/users/:id | Update user profile |
| GET | /api/users/:id/posts | Get user posts |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/posts | Get feed |
| POST | /api/posts | Create post |
| PUT | /api/posts/:id | Update post |
| DELETE | /api/posts/:id | Delete post |
| POST | /api/posts/:id/like | Like/unlike post |