{"id":24308851,"url":"https://github.com/hamidfarmani/tiny-url-clone","last_synced_at":"2026-04-17T18:32:17.003Z","repository":{"id":270228964,"uuid":"909693047","full_name":"hamidfarmani/tiny-url-clone","owner":"hamidfarmani","description":"A microservices-based URL shortening service with Spring Boot, including API Gateway, Eureka Discovery, Config Server, and distributed storage using Cassandra and PostgreSQL.","archived":false,"fork":false,"pushed_at":"2024-12-29T14:22:08.000Z","size":29,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-06T20:17:09.251Z","etag":null,"topics":["apigateway","configurationserver","discovery-service","microservice","springboot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hamidfarmani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-29T14:02:19.000Z","updated_at":"2024-12-29T14:34:48.000Z","dependencies_parsed_at":"2024-12-29T15:37:33.628Z","dependency_job_id":null,"html_url":"https://github.com/hamidfarmani/tiny-url-clone","commit_stats":null,"previous_names":["hamidfarmani/tiny-url-clone"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hamidfarmani/tiny-url-clone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidfarmani%2Ftiny-url-clone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidfarmani%2Ftiny-url-clone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidfarmani%2Ftiny-url-clone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidfarmani%2Ftiny-url-clone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hamidfarmani","download_url":"https://codeload.github.com/hamidfarmani/tiny-url-clone/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidfarmani%2Ftiny-url-clone/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31940811,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T17:29:20.459Z","status":"ssl_error","status_checked_at":"2026-04-17T17:28:47.801Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apigateway","configurationserver","discovery-service","microservice","springboot"],"created_at":"2025-01-17T05:11:45.005Z","updated_at":"2026-04-17T18:32:16.985Z","avatar_url":"https://github.com/hamidfarmani.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tiny URL (clone) Microservices Project\n\n## **Overview**\nThis project is a microservices-based implementation of a URL shortening service inspired by platforms like TinyURL. The architecture incorporates modern best practices for scalability, fault tolerance, and maintainability.\n\n### **Key Features**\n- **URL Shortening**: Converts long URLs into short, easily shareable links.\n- **Dynamic Service Discovery**: Services are registered and discovered dynamically via Eureka.\n- **Centralized Configuration Management**: Uses Spring Cloud Config for centralized configuration.\n- **Load Balancing**: API Gateway and service-to-service communication use load-balanced requests.\n- **Key Management Service (KGS)**: Efficient generation and storage of unique keys for shortened URLs.\n- **API Gateway**: A single entry point for all clients.\n\n---\n\n## **Architecture**\nThe project follows a microservices architecture with the following components:\n\n### **1. API Gateway**\n- Acts as the single entry point for all client requests.\n- Handles routing to the appropriate services.\n- Provides centralized logging, monitoring, and request transformation.\n\n### **2. Discovery Service (Eureka)**\n- Manages service registration and discovery.\n- Allows dynamic scaling of services without manual reconfiguration.\n\n### **3. Config Service**\n- Centralized configuration management using Spring Cloud Config.\n- Stores environment-specific configurations.\n\n### **4. Key Generation Service (KGS)**\n- Generates unique keys for the URL shortening service.\n- Uses a buffer and replenishment mechanism for efficient key management.\n- Backed by a PostgreSQL database.\n\n### **5. URL Service**\n- Handles URL creation, storage, and retrieval.\n- Interacts with KGS to fetch unique keys.\n- Uses Cassandra for scalable and efficient data storage.\n\n---\n\n## **Tech Stack**\n\n### **Backend**\n- **Java 21**: For modern and efficient server-side development.\n- **Spring Boot**: Framework for building microservices.\n- **Spring Cloud**: For API Gateway, service discovery, and config management.\n- **PostgreSQL**: Database for the KGS.\n- **Cassandra**: Database for storing URLs.\n\n### **Infrastructure**\n- **Docker**: Containerized deployment for all services.\n- **Eureka**: Service discovery and registry.\n- **Spring Cloud Config**: Centralized configuration management.\n\n### **Tools**\n- **Feign**: For inter-service communication.\n- **Load Balancer**: Built-in Spring Cloud load balancing for distributed services.\n- **Virtual Threads**: Lightweight concurrency for key generation and replenishment.\n\n---\n\n## **Getting Started**\n\n### **1. Clone the Repository**\n```bash\ngit clone https://github.com/hamidfarmani/tiny-url-clone.git\ncd tiny-url-clone\n```\n\n### **2. Prerequisites**\n- **Java 21**\n- **Docker** and **Docker Compose**\n- **Maven**\n\n### **3. Build and Run Services**\n\n#### **Build All Services**\n```bash\nmvn clean install\n```\n\n#### **Run Using Docker Compose**\nEnsure you have a `docker-compose.yml` file to start all services:\n```bash\ndocker-compose up --build\n```\n\nThis will start:\n- Eureka Discovery Service\n- Config Service\n- API Gateway\n- KGS\n- URL Service\n\n---\n\n## **Service Details**\n\n### **1. API Gateway**\n- **Port**: `8084`\n- **Base URL**: `http://\u003cgateway-host\u003e:8084`\n- **Endpoints**:\n    - `/kgs/**`: Routes requests to KGS.\n    - `/api/**`: Routes requests to URL Service.\n\n### **2. Discovery Service (Eureka)**\n- **Port**: `8761`\n- **Dashboard**: `http://localhost:8761`\n\n### **3. Config Service**\n- **Port**: `8888`\n- **Configuration Files Location**: `src/main/resources/configurations`\n- **Default Config Endpoint**: `http://localhost:8888/{application}/{profile}`\n\n### **4. Key Generation Service (KGS)**\n- **Port**: `8081`\n- **Endpoints**:\n    - `GET /kgs/fetch`: Fetches a batch of unique keys.\n    - `GET /kgs/monitor/unused-keys/check`: Monitors unused keys.\n\n### **5. URL Service**\n- **Port**: `8082`\n- **Endpoints**:\n    - `POST /api/create`: Creates a new shortened URL.\n    - `GET /api/{shortUrl}`: Retrieves the original URL for a given short URL.\n\n---\n\n## **Environment Variables**\n\n### **Eureka Discovery Service**\n- `EUREKA_INSTANCE_HOSTNAME`: Hostname of the Eureka server.\n\n### **Config Service**\n- `SPRING_PROFILES_ACTIVE`: Active profile (e.g., `dev`, `prod`).\n\n### **KGS**\n- `SPRING_DATASOURCE_URL`: JDBC URL for PostgreSQL.\n- `SPRING_DATASOURCE_USERNAME`: Database username.\n- `SPRING_DATASOURCE_PASSWORD`: Database password.\n\n### **URL Service**\n- `SPRING_DATA_CASSANDRA_CONTACT_POINTS`: Cassandra cluster contact points.\n- `SPRING_DATA_CASSANDRA_PORT`: Cassandra port.\n- `SPRING_DATA_CASSANDRA_KEYSPACE_NAME`: Keyspace name.\n\n---\n\n## **Development Notes**\n\n### **1. Running Services Locally**\n- Start Eureka first (`8761`), followed by Config Service (`8888`), and then the other services.\n- Use `localhost` for development and update `/etc/hosts` if testing logical names.\n\n### **2. Testing API Gateway**\n- Test API Gateway routing using:\n  ```bash\n  curl http://localhost:8084/kgs/fetch?count=10\n  ```\n\n### **3. Debugging Tips**\n- Check Eureka Dashboard to verify service registrations.\n- Use `docker logs \u003ccontainer-name\u003e` to debug Docker services.\n\n---\n\n## **Future Enhancements**\n- Add user authentication and authorization.\n- Implement rate limiting in API Gateway.\n- Add telemetry for request tracking and usage analytics.\n- Deploy services to Kubernetes for production scalability.\n\n---\n\n## **Contributors**\n- **Hamid Farmani** - [GitHub](https://github.com/hamidfarmani)\n\nFeel free to contribute by submitting issues or pull requests!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamidfarmani%2Ftiny-url-clone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhamidfarmani%2Ftiny-url-clone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamidfarmani%2Ftiny-url-clone/lists"}