This project is a backend application built with Spring Boot that scores GitHub repositories based on their popularity. The scoring is determined using the number of stars, forks, and the recency of updates. The application is structured using Domain-Driven Design (DDD) principles.

[User API Request]
     ↓
[Spring Boot REST Controller]
     ↓
[Service Layer]
     ↓
[GitHub API Client] → [GitHub Search API]
     ↓
[Scoring Algorithm] → [Score each repository]
     ↓
[Return JSON result]

• Score GitHub repositories using a custom popularity algorithm
• Search by language, creation date
• Clean architecture using DDD principles
• Unit and integration testing
• RESTful API with JSON responses
• Uses openfeign for sync GitHub API repository
• Dockerized application

• Open Feign was chosen for blocking HTTP calls, suitable for not high scalability and aligned with Spring Webmvc.
• if it was a high-load application, we would consider using WebClient for non-blocking calls.
• The solution avoids over-engineering by keeping the data model simple and focusing on clarity and testability.
• Domain-Driven Design was applied at a pragmatic level to separate core concerns, without excessive abstraction.

de.redcare.githubscore
├── domain             → Core domain models
├── application        → Business logic and services
├── infrastructure     → GitHub API client integration
└── web.controller     → REST controllers

Endpoint: GET /api/v1/repos

Query Parameters:

• language — Programming language to filter
• createdAfter — Repositories created after this date (YYYY-MM-DD)

Example Request:

curl --location 'http://localhost:8080/api/v1/repos?searchQuery=test&language=css&sortBy=forks&sortOrder=desc&pageNumber=1&pageSize=99&createdAfter=2025-05-23' \
--header 'accept: */*' \

Example Response:

[
  {
    "id": 978406357,
    "name": "Discord-Token-Login",
    "url": "https://api.github.com/repos/xPOURY4/Discord-Token-Login",
    "language": "CSS",
    "stars": 46,
    "forks": 38,
    "lastUpdated": "2025-05-22T08:59:46Z",
    "score": "20%"
  }
]

• GithubRepositoryE2ETest.java — End-to-end test for the GitHub repository scoring service with wiremock
• GithubScoringServiceTest - Test the core logic of getting data and assigning scores
• GitHubFallbackTest — check the fallback behavior of the gitHub API client
• GitHubErrorDecoderTest - test the error handling of the GitHub API client and other unit tests for various components.

• Java 21
• Spring Boot 3.3.5
• Spring webmvc
• openfeign
• cache
• JUnit 5
• Mockito
• RESTful APIs

git clone https://github.com/ShiboTanany/GithubScoringService.git
cd GithubScoringService
./mvnw spring-boot:run

or

git clone https://github.com/ShiboTanany/GithubScoringService.git
cd GithubScoringService
sh build-and-run.sh 

⚙️ Configuration The application is configured via application.yml, with support for environment variable overrides to facilitate deployment flexibility.

🔧 General Settings

yaml:
 spring:
  application:
   name: GitHubScoreService

Name: The application is registered as GitHubScoreService.

🚀 Server

server:
  port: ${PORT:8080}

Override with PORT environment variable.

📦 Caching

spring:
  cache:
    type: caffeine
    caffeine:
      spec: maximumSize=100,expireAfterWrite=1h

Maximum Entries: 100

Expiration: 1 hour after write

🔍 Cache Monitoring

management:
  endpoint:
    cache:
      enabled: true
  endpoints:
    web:
      exposure:
        include: cache

Cache actuator endpoint is enabled and exposed for inspection.

🌐 GitHub API Integration

github:
  api:
    debug: true
    base-url: ${GITHUB_URL:https://api.github.com}
    timeout: ${TIMEOUT:5000}
    max-timeout: ${MAX_TIMEOUT:10000}
    retry:
      max-attempts: ${MAX_ATTEMPT:3}
      backoff-delay-ms: ${BACKOFF_DELAY_MS:1000}

🧮 Scoring Configuration

scoring:
  normalize: true
  weights:
    stars: ${STARS_WEIGHT:0.5}
    forks: ${FORKS_WEIGHT:0.3}
    recency: ${RECENCY_WEIGHT:0.2}
  maximums:
    stars: ${MAX_STARS:100000}
    forks: ${MAX_FORKS:50000}
    recencyDays: ${MAX_RECENCY_DAYS:365}

Weights: Control how much each metric contributes to the repository score

All values can be overridden using environment variables for easy tuning.

📡 Feign Compression

feign:
  compression:
    request:
      enabled: true
    response:
      enabled: true

Enables gzip compression for Feign client requests and responses to optimize bandwidth usage.

ErrorResponse The ErrorResponse is a standard way our API sends error information back to clients. It helps you understand what went wrong when a request fails.

What’s inside an ErrorResponse?

Details (optional) If an error involves specific fields (like form validation), details contains a list of those with messages: