A modern, containerized URL shortener with analytics tracking. Built with React frontend and Flask backend, optimized for Docker deployment.
- URL Shortening: Create short links with custom TTL
- Analytics Tracking: Monitor clicks, IPs, user agents, and geographic data
- Real-time Dashboard: View link performance and statistics
- Containerized: Fully dockerized with optimized images
- Persistent Storage: Data persistence with Docker volumes
- Health Monitoring: Built-in health checks for both services
# Clone the repository
git clone https://github.com/iamindrajitdan/linkpulse.git
cd linkpulse
# Build and run both services
docker-compose up --build
# Run in background
docker-compose up -d --buildcd frontend
docker build -t linkpulse-frontend .
docker run -p 3000:3000 linkpulse-frontendcd backend
docker build -t linkpulse-backend .
docker run -p 5000:5000 linkpulse-backend- Frontend: http://localhost:3000
- Backend API: http://localhost:5000/dev
- Health Check: http://localhost:5000/dev/health
| Method | Endpoint | Description |
|---|---|---|
| POST | /dev/shorten |
Create short link |
| GET | /u/<slug> |
Redirect to original URL |
| GET | /dev/analytics/<slug> |
Get link analytics |
| GET | /dev/stats/<slug> |
Get link statistics |
| GET | /dev/health |
Health check |
- Framework: React 18 with Vite
- Styling: Tailwind CSS
- HTTP Client: Axios
- Deployment: Served with
servepackage
- Framework: Flask with CORS support
- Server: Gunicorn WSGI server
- Storage: File-based JSON storage
- Architecture: Clean architecture with separated layers
- Multi-stage build (reduces image size by ~60%)
- Alpine Linux base (minimal OS footprint)
- Non-root user for security
- Health checks for monitoring
- Static file serving with
serve
- Python slim image (smaller than full Python)
- Single layer dependency installation
- Production WSGI server (Gunicorn)
- Non-root user for security
- Comprehensive health checks
- Docker & Docker Compose
- Node.js 18+ (for local development)
- Python 3.11+ (for local development)
cd frontend
npm install
npm run devcd backend
pip install -r requirements.txt
python local_server.pycd backend
python -m pytest tests/LinkPulse/
├── frontend/ # React frontend
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── App.jsx # Main app component
│ │ └── main.jsx # Entry point
│ ├── Dockerfile # Frontend container
│ └── package.json # Dependencies
├── backend/ # Flask backend
│ ├── src/ # Source code
│ │ ├── data_layer.py # Data access layer
│ │ ├── logic_layer.py # Business logic
│ │ ├── models.py # Data models
│ │ └── services.py # Service layer
│ ├── tests/ # Test suite
│ ├── Dockerfile # Backend container
│ └── requirements.txt # Python dependencies
├── docker-compose.yml # Multi-container setup
└── README.md # This file
We welcome contributions! Please follow these steps:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
- Follow existing code style and patterns
- Add tests for new features
- Update documentation as needed
- Ensure Docker builds pass
- Test both frontend and backend changes
This project is licensed under the MIT License - see the LICENSE file for details.
- Built with modern web technologies
- Containerized for easy deployment
- Designed for scalability and maintainability
If you encounter any issues or have questions:
- Open an issue on GitHub
- Check existing issues for solutions
- Contribute improvements via pull requests
Made with ❤️ by the LinkPulse community