Short URLs - A modern URL shortening service built with Go, MongoDB, and React. Create tiny URLs from long ones and track click analytics.

Explore the docs » API Documentation · Report Bug · Request Feature

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. API Documentation
5. Architecture
6. Roadmap
7. Contributing
8. License
9. Contact
10. Acknowledgments

Short URLs is a comprehensive URL shortening service that allows users to create shortened versions of long URLs while providing click tracking and analytics. This project demonstrates modern web development practices with a microservices architecture.

• URL Shortening: Convert long URLs into short, memorable links
• Click Tracking: Monitor and analyze click statistics
• User Authentication: Secure user registration and login
• RESTful API: Clean, documented API endpoints
• Modern Frontend: React-based user interface
• Docker Support: Easy deployment with Docker Compose
• Analytics Dashboard: Visual representation of URL performance

• Space Efficiency: Perfect for social media, SMS, and email sharing
• Branding: Create memorable, branded short links
• Analytics: Track engagement and click-through rates
• Convenience: Easy to remember and share

This section lists the major frameworks and libraries used to build this project.

• Go - Primary programming language
• Chi - HTTP router and middleware
• MongoDB Go Driver - Official MongoDB driver
• Viper - Configuration management
• JWT-Go - JWT authentication

• React - JavaScript library for building user interfaces
• Material-UI - React UI framework
• Recharts - Composable charting library

• Docker - Containerization
• Docker Compose - Multi-container orchestration

This is an example of how you can set up the project locally. Follow these simple steps to get a local copy up and running.

This is an example of how to list things you need to use the software and how to install them.

• Go (>= v1.13)

  # macOS
  brew install go
  
  # Ubuntu/Debian
  sudo apt-get install golang-go
  
  # Windows
  # Download from https://golang.org/dl/

• MongoDB (>= v4.2.1)

  # macOS
  brew install mongodb/brew/mongodb-community
  
  # Ubuntu/Debian
  sudo apt-get install mongodb
  
  # Windows
  # Download from https://www.mongodb.com/try/download/community

• Node.js (>= 14.0.0)

  # macOS
  brew install node
  
  # Ubuntu/Debian
  curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash -
  sudo apt-get install -y nodejs
  
  # Windows
  # Download from https://nodejs.org/

• Docker (>= 19.03)

  # macOS
  brew install docker
  
  # Ubuntu/Debian
  sudo apt-get install docker.io docker-compose
  
  # Windows
  # Download from https://www.docker.com/products/docker-desktop

1. Clone the repository

   git clone https://github.com/gyaan/short-urls.git
   cd short-urls

2. Run with Docker Compose

   docker-compose -f build/package/docker-compose.yml up

3. Access the application

   • Backend API: http://localhost:8080
   • Frontend: http://localhost:3000

1. Clone the repository

   git clone https://github.com/gyaan/short-urls.git
   cd short-urls

2. Set up MongoDB

   # Start MongoDB service
   sudo systemctl start mongod
   
   # Or run MongoDB manually
   mongod --dbpath /path/to/data/directory

3. Configure the application

   # Copy and edit the configuration file
   cp config/config.yaml.example config/config.yaml
   # Edit config/config.yaml with your settings

4. Run the backend

   # Install dependencies
   go mod download
   
   # Run the application
   go run cmd/short-urls/main.go

5. Run the frontend

   cd web
   npm install
   npm start

# Register a new user
POST /api/auth/register
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123"
}

# Login
POST /api/auth/login
{
  "email": "john@example.com",
  "password": "password123"
}

# Create a short URL
POST /api/short-urls
Authorization: Bearer <token>
{
  "url": "https://example.com/very-long-url"
}

# Get all short URLs
GET /api/short-urls?page=1&limit=10
Authorization: Bearer <token>

# Get specific short URL
GET /api/short-urls/{id}
Authorization: Bearer <token>

# Update short URL status
PUT /api/short-urls/{id}
Authorization: Bearer <token>
{
  "status": 1
}

# Delete short URL
DELETE /api/short-urls/{id}
Authorization: Bearer <token>

# Redirect to original URL
GET /{short-url-identifier}

1. Sign up/Login: Create an account or sign in
2. Create Short URLs: Enter a long URL to get a shortened version
3. Manage URLs: View, edit, and delete your short URLs
4. Analytics: Monitor click statistics and performance

For detailed API documentation, see the API Documentation or explore the Postman Collection.

short-urls/
├── cmd/                    # Application entry points
│   └── short-urls/        # Main application
├── internal/              # Private application code
│   ├── config/           # Configuration management
│   ├── handler/          # HTTP request handlers
│   ├── middleware/       # HTTP middleware
│   ├── models/           # Data models
│   ├── repositories/     # Data access layer
│   └── router/           # Route definitions
├── pkg/                  # Public libraries
│   ├── pagination/       # Pagination utilities
│   ├── url/             # URL validation
│   └── url_shortner/    # URL shortening algorithm
├── web/                  # React frontend
├── config/               # Configuration files
├── docs/                 # Documentation
└── api/                  # API documentation

• Backend: Go with Chi router and MongoDB
• Frontend: React with Material-UI
• Authentication: JWT tokens
• Database: MongoDB with official Go driver
• Deployment: Docker and Docker Compose

• Add URL expiration functionality
• Implement click analytics dashboard
• Add bulk URL import/export
• Create mobile application
• Add URL customization (custom short codes)
• Implement rate limiting
• Add API rate limiting
• Create admin dashboard
• Add URL preview functionality
• Implement URL password protection

See the open issues for a full list of proposed features and known issues.

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

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

• Follow Go best practices and conventions
• Write tests for new functionality
• Update documentation for API changes
• Use conventional commit messages
• Ensure all tests pass before submitting PR

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

Gyaan - @gyaan - gyaan@example.com

Project Link: https://github.com/gyaan/short-urls

• Best README Template - For this amazing README template
• Go Chi Router - Lightweight HTTP router
• Material-UI - React UI framework
• MongoDB Go Driver - Official MongoDB driver
• Viper - Configuration solution for Go applications
• JWT-Go - JWT implementation in Go