Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rblessings/urlradar
A dynamic URL redirection service for Professionals with Advanced User Analytics.
https://github.com/rblessings/urlradar
github-actions java kafka oauth2 spring-boot testcontainers
Last synced: 5 days ago
JSON representation
A dynamic URL redirection service for Professionals with Advanced User Analytics.
- Host: GitHub
- URL: https://github.com/rblessings/urlradar
- Owner: rblessings
- License: mit
- Created: 2024-12-28T00:15:31.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-01-20T22:52:14.000Z (7 days ago)
- Last Synced: 2025-01-20T23:24:49.673Z (7 days ago)
- Topics: github-actions, java, kafka, oauth2, spring-boot, testcontainers
- Language: Java
- Homepage:
- Size: 144 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# URLradar - Secure & Seamless URL Redirection Service
---
## Overview
**Secure and Up-to-Date Links for Professionals**
**URLradar** is a dynamic URL redirection service designed to help professionals manage and maintain their links across
various digital platforms.
*Key benefits:*
* Easily update destinations without changing shared links.
* Prevent broken links due to website changes.
* Ideal for resumes, portfolios, social media, and more.
URLradar simplifies link management for job seekers, entrepreneurs, and anyone with an online presence.
[](https://github.com/rblessings/urlradar/actions/workflows/build-test-dockerize-deploy.yml)
---
## Table of Contents
- [Features](#features)
- [Technical Features](#technical-features)
- [Entity-Relationship Overview](#entity-relationship-overview)
- [Installation](#installation)
- [API Usage](#api-usage)
- [License](#license)
---
## Features
### Core Features
- **URL Redirection**: Redirect a static URL to a new destination without altering the shared link on CVs, LinkedIn
profiles, portfolios, etc.
- **URL Shortening**: Transform long URLs into concise, custom short links for easier sharing. Example:
`https://urlradar.io/{username}/{randomcode}`.
- **Analytics**: Track URL performance through detailed analytics, including click counts, geographical data, and
referral sources.
- **Real-Time Link Updates**: Instantly update the destination of any redirected URL to keep links accurate and
up-to-date across platforms.
- **Customizable Branding**: Create branded short URLs that align with your personal or professional identity.
---
## Technical Features
**URLradar** employs modern technologies to ensure scalability, security, and performance.
### Key Technical Components:
- **Security**:
- **OAuth2 & JWT**: Secure user authentication and authorization with OAuth2 and JSON Web Tokens for seamless
integration with third-party platforms.
- **Encryption**: All data and URL redirects are encrypted in transit using HTTPS.
- **Fault Tolerance**:
- **Circuit Breaker**: Resilience mechanisms to prevent cascading failures during service disruptions.
- **Retries & Resilience**: Implemented using Resilience4J for retry logic and fault-tolerant network communication.
- **Distributed System**:
- **Kafka**: Enables high-throughput, real-time data streaming for user analytics (click counts, geography,
referrals) and facilitates decoupled microservice communication.
- **MongoDB**: The system utilizes a NoSQL database to manage redirection data, analytics, and user profiles. This
architecture supports efficient full-text search and indexing of URLs, ensuring rapid lookups and high-performance
analytics.
- **Caching**:
- **Redis**: Leverages Redis to cache frequently accessed URL redirection and analytics data (click counts,
geography, referrals). This improves performance, reduces database load, and ensures data freshness through
periodic updates and efficient memory management with eviction policies.
- **Session Management**:
- **Spring Session**: Enables centralized session management for consistent handling across multiple instances or
deployments, enhancing scalability, security, and session persistence.
- **Scalable Architecture**:
- Microservices architecture designed for horizontal scaling to accommodate growing traffic.
- Dockerized services for simplified deployment and scaling in cloud environments (AWS, GCP, Azure).
- **Cloud-Native**:
- This application is designed for deployment within a **Kubernetes cluster**, enabling seamless scalability, high
availability, and fault tolerance. Containerized using **Docker** for efficient packaging and portability.
---
## **Entity-Relationship Overview**
### **Entities**
#### **1. User**
- **Attributes:**
- `UserID (PK)`
- `FirstName`
- `LastName`
- `Username`
- `Email`
- `PasswordHash`
- `CreatedAt`
- `UpdatedAt`
- `Version`
- **Relationships:**
- A user can own multiple **URLs**.
- A user can have multiple **sessions**.
#### **2. URL**
- **Attributes:**
- `URLID (PK)`
- `ShortCode`
- `OriginalURL`
- `DestinationURL`
- `CustomAlias`
- `UserID (FK)`
- `CreatedAt`
- `UpdatedAt`
- `IsActive`
- **Relationships:**
- A URL has many **Analytics** records.
- Belongs to a **User**.
#### **3. Analytics**
- **Attributes:**
- `AnalyticsID (PK)`
- `URLID (FK)`
- `ClickCount`
- `Referrer`
- `Geography`
- `Timestamp`
- **Relationships:**
- Belongs to a **URL**.
- The `Geography` field shows the most frequent location, not all geographies. For detailed counts, a separate
analytics system is needed. It’s recommended to use IP geolocation services (e.g., MaxMind, IPinfo) to determine
the user’s country or region from their IP address for more accurate geographic data.
---
## **Kafka Topics**
### **1. `click-events`**
- **Purpose:** Captures real-time click data.
- **Producers:** URL redirection service.
- **Consumers:** Analytics service, monitoring service.
- **Message Schema:**
```json
{
"URLID": "string",
"Referrer": "string",
"Geography": "string",
"Timestamp": "ISO8601 string"
}
```
### **2. `analytics-updates`**
- **Purpose:** Propagates aggregated analytics data to dependent services.
- **Producers:** Analytics service.
- **Consumers:** Caching service, notification service.
- **Message Schema:**
```json
{
"URLID": "string",
"ClickCount": "integer",
"TopGeography": "string",
"TopReferrer": "string"
}
```
---
## **MongoDB Collections**
1. **`users`**:
- Example Document:
```json
{
"UserID": "user_12345",
"Username": "rblessings",
"firstName": "Ranzy",
"lastName": "Blessings",
"Email": "[email protected]",
"PasswordHash": "hashed_password",
"version": "0",
"CreatedAt": "2025-01-01T10:00:00Z",
"UpdatedAt": "2025-01-15T12:00:00Z"
}
```
2. **`urls`**:
- Example Document:
```json
{
"URLID": "url_12345",
"ShortCode": "abc123",
"OriginalURL": "https://example.com",
"DestinationURL": "https://new-example.com",
"CustomAlias": "my-link",
"UserID": "user_12345",
"CreatedAt": "2025-01-01T10:00:00Z",
"UpdatedAt": "2025-01-15T12:00:00Z",
"IsActive": true
}
```
3. **`analytics`**:
- Example Document:
```json
{
"AnalyticsID": "analytics_12345",
"URLID": "url_12345",
"ClickCount": 200,
"Referrer": "https://google.com",
"Geography": "US",
"Timestamp": "2025-01-20T14:30:00Z"
}
```
---
## **Redis Caching**
### **Key Structures**
#### **1. User Cache**
- **Key Format:** `user-email-cache:[email protected]`
- **Value:** The value is a serialized `UserDTO` object.
#### **2. URL Cache**
- **Key Format:** `short-url-cache:abc123`
- **Value:** Implementation pending.
#### **3. Analytics Cache**
- **Key Format:** `analytics-cache:url_12345`
- **Value:** Implementation pending.
---
## Installation
Follow these steps to set up the **URLradar** project locally or deploy it to the cloud.
### Prerequisites
Ensure the following tools are installed:
- [Docker v27.4.1](https://www.docker.com/get-started): (or latest).
- [Docker Compose v2.32.1](https://www.docker.com/get-started): (or latest).
- [Java 23](https://docs.aws.amazon.com/corretto/latest/corretto-23-ug/downloads-list.html): (or latest).
### Local Setup with Docker
To run the project locally using Docker:
1. Clone the repository:
```bash
git clone https://github.com/rblessings/urlradar.git
cd urlradar
```
2. Build and run the Docker containers:
```bash
docker compose up --build -d
```
This will start the following services:
- **MongoDB**: Stores user data and redirection records.
- **Redis**: Caching layer for efficient URL lookups.
- **Kafka**: handles event streaming for distributed communication, enabling real-time analytics on user data and
URL performance with low-latency, high-throughput processing.
- **Authorization server**: OAuth2 OIDC JWT Authentication Server.
3. To start the **Backend (API)** Core URL redirection and analytics service:
```bash
SPRING_PROFILES_ACTIVE=dev ./gradlew clean bootRun
```
**Note:** This command automatically runs the `compose.yaml` file to start the Backend (API) service and its
dependencies, offering an alternative to `docker compose up --build -d`.
---
## API Usage
As part of our development process, we utilize **Spring REST Docs** to generate accurate and up-to-date documentation
for our REST APIs. This approach offers several key advantages:
* **Test-driven Documentation**: By coupling documentation generation with automated tests, we ensure that the API
documentation is always aligned with the actual code, reducing discrepancies between what is documented and what is
implemented.
* **Enforcing Test Coverage**: Writing tests to generate documentation enforces the creation of test cases for all API
endpoints, improving the overall quality and reliability of the codebase.
* **Accurate and Up-to-Date**: Spring REST Docs ensures that the documentation is generated from real API interactions,
reflecting the actual request and response formats, headers, and payloads used in production.
During development, you can generate the REST API documentation locally by running the following command:
```bash
./gradlew clean test asciidoctor
```
Once the build completes, the generated documentation will be available in the **build/docs** directory.
To view the documentation:
1. Navigate to the `build/docs/asciidoc` directory.
2. Open the `index.html` file in your browser.
This will present an interactive documentation page where you can find detailed information on how to make requests to
test the app's APIs.
---
## **How to Contribute**
We welcome contributions from developers of all skill levels! Here’s how you can get started:
1. **Fork the Repository:** Create a personal copy of the repo.
2. **Explore Issues:** Check the [issue tracker](https://github.com/rblessings/urlradar/issues) for open issues or
feature requests.
3. **Create a Branch:** Work on your feature or bug fix in a separate branch.
4. **Submit a Pull Request:** Once ready, submit a PR for review.
### **Areas to Contribute**
- **Feature Development:** Implement new features such as custom analytics or advanced reporting.
- **Bug Fixes:** Help identify and resolve issues.
- **Documentation:** Improve or expand the existing documentation.
- **Testing:** Write unit and integration tests to ensure reliability.
---
## License
This project is open-source software released under the [MIT License](https://opensource.org/licenses/MIT).