# zevolution/netflix-hexagonal-architecture architecture

> Architecture diagram of the GitHub repository zevolution/netflix-hexagonal-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zevolution/netflix-hexagonal-architecture
- Repository: https://github.com/zevolution/netflix-hexagonal-architecture

## Overview

This Spring service exposes a lookup for software by author and name, returning repository details from a configured Git provider. The request enters through the REST API, passes through a use case and repository abstraction, and is handled by a GitHub or GitLab data source; the README describes switching providers. Provider responses are mapped into the shared Software entity and then to the API representation. The tree and excerpts support the GitLab adapter’s calls; GitHub adapter wiring and provider selection are less fully shown, so those links are documented or marked unverified.

Main entry points: [`src/main/java/dev/zevolution/netflixhexaarch/repositories/SoftwareRepository.java`](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/repositories/SoftwareRepository.java) (Repository port), [`src/main/java/dev/zevolution/netflixhexaarch/datasources/GitlabSoftwaresDataSource.java`](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/GitlabSoftwaresDataSource.java) (GitLab adapter), [`src/main/java/dev/zevolution/netflixhexaarch/transportlayers/restapi/AuthorsApiImpl.java`](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/transportlayers/restapi/AuthorsApiImpl.java) (Authors endpoint), [`src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GithubReposClient.java`](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GithubReposClient.java) (GitHub repository client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_authors_api["Authors endpoint"]
  node_api_mapper["Response mapper"]
end

subgraph group_domain["Application Domain"]
  node_use_case["Software lookup"]
  node_repository["Repository port"]
  node_software["Software entity<br/>[Software.java]"]
end

subgraph group_providers["Git Providers"]
  node_github_source["GitHub adapter"]
  node_github_client["GitHub repository client"]
  node_gitlab_source["GitLab adapter"]
  node_gitlab_client["GitLab users client"]
  node_provider_dtos["Provider response models"]
  node_provider_mapper["Provider mapper"]
end

subgraph group_operations["Runtime Support"]
  node_exception_advice["Exception advice"]
  node_api_exception["API error model"]
  node_metrics["Metrics configuration<br/>[MetricsConfig.java]"]
  node_application["Application bootstrap<br/>[Application.java]"]
end

node_caller(("API caller"))
node_github_service(("GitHub service"))
node_gitlab_service(("GitLab service"))

node_caller -->|"requests"| node_authors_api
node_authors_api -->|"invokes"| node_use_case
node_authors_api -->|"maps response"| node_api_mapper
node_use_case -->|"queries"| node_repository
node_repository -->|"returns"| node_software
node_api_mapper -->|"maps entity"| node_software
node_github_source -->|"implements"| node_repository
node_gitlab_source -->|"implements"| node_repository
node_gitlab_source -->|"calls"| node_gitlab_client
node_gitlab_source -->|"maps projects"| node_provider_mapper
node_github_source -.->|"calls"| node_github_client
node_github_client -.->|"fetches repository"| node_github_service
node_gitlab_client -.->|"fetches users/projects"| node_gitlab_service
node_gitlab_client -->|"returns models"| node_provider_dtos
node_github_client -->|"returns model"| node_provider_dtos
node_provider_mapper -->|"maps from"| node_provider_dtos
node_provider_mapper -->|"maps to"| node_software
node_exception_advice -->|"creates errors"| node_api_exception

click node_authors_api "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/transportlayers/restapi/AuthorsApiImpl.java"
click node_api_mapper "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/transportlayers/mapper/SoftwareMapper.java"
click node_use_case "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/interactors/GetSoftwareByAuthorAndSoftwareNameUseCase.java"
click node_repository "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/repositories/SoftwareRepository.java"
click node_software "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/entities/Software.java"
click node_github_source "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/GithubSoftwaresDataSource.java"
click node_github_client "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GithubReposClient.java"
click node_gitlab_source "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/GitlabSoftwaresDataSource.java"
click node_gitlab_client "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GitlabUsersClient.java"
click node_provider_dtos "https://github.com/zevolution/netflix-hexagonal-architecture/tree/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/services/data/response"
click node_provider_mapper "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/services/mapper/SoftwareMapper.java"
click node_exception_advice "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/configs/ExceptionAdviceConfiguration.java"
click node_api_exception "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/configs/RESTAPIException.java"
click node_metrics "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/configs/MetricsConfig.java"
click node_application "https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/Application.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_authors_api,node_api_mapper toneBlue
class node_use_case,node_repository,node_software toneAmber
class node_github_source,node_github_client,node_gitlab_source,node_gitlab_client,node_provider_dtos,node_provider_mapper,node_caller toneMint
class node_exception_advice,node_api_exception,node_metrics,node_application toneRose
class node_github_service,node_gitlab_service toneIndigo
```

## Components

### REST API

- [Authors endpoint](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/transportlayers/restapi/AuthorsApiImpl.java): `src/main/java/dev/zevolution/netflixhexaarch/transportlayers/restapi/AuthorsApiImpl.java`
- [Response mapper](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/transportlayers/mapper/SoftwareMapper.java): `src/main/java/dev/zevolution/netflixhexaarch/transportlayers/mapper/SoftwareMapper.java`

### Application Domain

- [Software lookup](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/interactors/GetSoftwareByAuthorAndSoftwareNameUseCase.java): `src/main/java/dev/zevolution/netflixhexaarch/interactors/GetSoftwareByAuthorAndSoftwareNameUseCase.java`
- [Repository port](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/repositories/SoftwareRepository.java): `src/main/java/dev/zevolution/netflixhexaarch/repositories/SoftwareRepository.java`
- [Software entity](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/entities/Software.java): `src/main/java/dev/zevolution/netflixhexaarch/entities/Software.java`

### Git Providers

- [GitHub adapter](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/GithubSoftwaresDataSource.java): `src/main/java/dev/zevolution/netflixhexaarch/datasources/GithubSoftwaresDataSource.java`
- [GitHub repository client](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GithubReposClient.java): `src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GithubReposClient.java`
- [GitLab adapter](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/GitlabSoftwaresDataSource.java): `src/main/java/dev/zevolution/netflixhexaarch/datasources/GitlabSoftwaresDataSource.java`
- [GitLab users client](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GitlabUsersClient.java): `src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GitlabUsersClient.java`
- [Provider response models](https://github.com/zevolution/netflix-hexagonal-architecture/tree/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/services/data/response): `src/main/java/dev/zevolution/netflixhexaarch/datasources/services/data/response`
- [Provider mapper](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/datasources/services/mapper/SoftwareMapper.java): `src/main/java/dev/zevolution/netflixhexaarch/datasources/services/mapper/SoftwareMapper.java`

### Runtime Support

- [Exception advice](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/configs/ExceptionAdviceConfiguration.java): `src/main/java/dev/zevolution/netflixhexaarch/configs/ExceptionAdviceConfiguration.java`
- [API error model](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/configs/RESTAPIException.java): `src/main/java/dev/zevolution/netflixhexaarch/configs/RESTAPIException.java`
- [Metrics configuration](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/configs/MetricsConfig.java): `src/main/java/dev/zevolution/netflixhexaarch/configs/MetricsConfig.java`
- [Application bootstrap](https://github.com/zevolution/netflix-hexagonal-architecture/blob/main/src/main/java/dev/zevolution/netflixhexaarch/Application.java): `src/main/java/dev/zevolution/netflixhexaarch/Application.java`

### Other components

- **API caller**
- **GitHub service**
- **GitLab service**

## Connections

- API caller → Authors endpoint: requests (evidence: `README.md`)
- Authors endpoint → Software lookup: invokes (evidence: `src/main/java/dev/zevolution/netflixhexaarch/transportlayers/restapi/AuthorsApiImpl.java`)
- Authors endpoint → Response mapper: maps response (evidence: `src/main/java/dev/zevolution/netflixhexaarch/transportlayers/restapi/AuthorsApiImpl.java`)
- Software lookup → Repository port: queries (evidence: `src/main/java/dev/zevolution/netflixhexaarch/interactors/GetSoftwareByAuthorAndSoftwareNameUseCase.java`)
- Repository port → Software entity: returns (evidence: `src/main/java/dev/zevolution/netflixhexaarch/repositories/SoftwareRepository.java`)
- Response mapper → Software entity: maps entity (evidence: `src/main/java/dev/zevolution/netflixhexaarch/transportlayers/mapper/SoftwareMapper.java`)
- GitHub adapter → Repository port: implements (evidence: `src/main/java/dev/zevolution/netflixhexaarch/datasources/GithubSoftwaresDataSource.java`)
- GitLab adapter → Repository port: implements (evidence: `src/main/java/dev/zevolution/netflixhexaarch/datasources/GitlabSoftwaresDataSource.java`)
- GitLab adapter → GitLab users client: calls (evidence: `src/main/java/dev/zevolution/netflixhexaarch/datasources/GitlabSoftwaresDataSource.java`)
- GitLab adapter → Provider mapper: maps projects (evidence: `src/main/java/dev/zevolution/netflixhexaarch/datasources/GitlabSoftwaresDataSource.java`)
- GitHub adapter → GitHub repository client: calls (evidence: `src/main/java/dev/zevolution/netflixhexaarch/datasources/GithubSoftwaresDataSource.java`)
- GitHub repository client → GitHub service: fetches repository
- GitLab users client → GitLab service: fetches users/projects
- GitLab users client → Provider response models: returns models (evidence: `src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GitlabUsersClient.java`)
- GitHub repository client → Provider response models: returns model (evidence: `src/main/java/dev/zevolution/netflixhexaarch/datasources/services/GithubReposClient.java`)
- Provider mapper → Provider response models: maps from (evidence: `src/main/java/dev/zevolution/netflixhexaarch/datasources/services/mapper/SoftwareMapper.java`)
- Provider mapper → Software entity: maps to (evidence: `src/main/java/dev/zevolution/netflixhexaarch/datasources/services/mapper/SoftwareMapper.java`)
- Exception advice → API error model: creates errors (evidence: `src/main/java/dev/zevolution/netflixhexaarch/configs/ExceptionAdviceConfiguration.java`)
