{"id":21558696,"url":"https://github.com/hyunk3l/hexagonal-architecture-kotlin-template","last_synced_at":"2026-01-19T22:05:09.710Z","repository":{"id":48791813,"uuid":"414980804","full_name":"Hyunk3l/hexagonal-architecture-kotlin-template","owner":"Hyunk3l","description":"The purpose of this template is to avoid repeating, over and over again, the same basic packages structure, gradle and configurations. With this template we can generate a service from scratch following \"DDD Style\" hexagonal architecture (aka Ports \u0026 Adapters)","archived":false,"fork":false,"pushed_at":"2025-04-08T19:40:00.000Z","size":1148,"stargazers_count":18,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-08T20:33:23.963Z","etag":null,"topics":["copier-template","ddd-architecture","gradle","hexagonal-architecture","kotlin","ports-and-adapters","spring","spring-boot","template"],"latest_commit_sha":null,"homepage":"","language":"Jinja","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/Hyunk3l.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-08T12:37:00.000Z","updated_at":"2025-04-08T19:39:45.000Z","dependencies_parsed_at":"2024-02-13T08:29:37.170Z","dependency_job_id":"a3b7a3ac-dc2b-46e9-b89f-0ccc9113a408","html_url":"https://github.com/Hyunk3l/hexagonal-architecture-kotlin-template","commit_stats":null,"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hyunk3l%2Fhexagonal-architecture-kotlin-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hyunk3l%2Fhexagonal-architecture-kotlin-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hyunk3l%2Fhexagonal-architecture-kotlin-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hyunk3l%2Fhexagonal-architecture-kotlin-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hyunk3l","download_url":"https://codeload.github.com/Hyunk3l/hexagonal-architecture-kotlin-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248199847,"owners_count":21063771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["copier-template","ddd-architecture","gradle","hexagonal-architecture","kotlin","ports-and-adapters","spring","spring-boot","template"],"created_at":"2024-11-24T08:15:35.675Z","updated_at":"2026-01-05T21:20:06.566Z","avatar_url":"https://github.com/Hyunk3l.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"![hexagonal-architecture](./assets/hexagonal-architecture.png)\n\n![flujo de trabajo de ejemplo](https://github.com/Hyunk3l/hexagonal-architecture-kotlin-template/actions/workflows/build.yml/badge.svg)\n\n# Hexagonal Architecture Kotlin Template\n\nThe purpose of this template is to avoid repeating, over and over again, the same basic packages structure, gradle and configurations.\nNote: this is just a skeleton with a silly example. Is good to start a project with it, but if you want to see a production ready and fully tested project with a lot of examples, please visit my friend [Albert Llousas Team Management repository](https://github.com/albertllousas/team-management-microservice).\n\nThe current packages structure has been popularized by Vaughn Vernon, the author of [Implementing Domain-Driven Design](https://www.goodreads.com/book/show/15756865-implementing-domain-driven-design)\nand [Domain-Driven Design Distilled](https://www.goodreads.com/book/show/28602719-domain-driven-design-distilled) and you can see an example in\nhis [Github Repository](https://github.com/VaughnVernon/IDDD_Samples/tree/master/iddd_collaboration/src/main/java/com/saasovation/collaboration).\nThe structure is a mix of [Alistair Cockburn's Ports \u0026 Adapters Pattern](https://alistair.cockburn.us/hexagonal-architecture/) and DDD concepts. In fact, if you know the original Hexagonal Architecture article,\nyou will see that the packages structure is not familiar to you, but you may recognize the concepts embedded (Ports \u0026 Adapters). \nIn the `src` directory you will see the following packages: \n```\n.\n├── application\n├── domain\n└── infrastructure\n```\nThe `application` package is the place where we will put all the Application Services (aka Use Cases) classes.\n\nThe `domain` package will host all the pure Domain classes, such as Aggregates, Value Objects, Entities, Domain Events, Repositories etc. Usually this package also hosts PORTS (CustomerRepository is an example of a Port).\n\nThe `infrastructure` package instead, is the place were we put all the infrastructure concerns, such as framework, configurations and concrete implementations. You will see an `adapters` package\nthat contains Inbound and Outbound Adapters, that are concrete implementations of Ports, defined in the `domain` package.\n\n### Short introduction to Testing\nThe silly example provided is, of course, tested (using Outside-In TDD).\nThis project is following the typical [Testing Pyramid](https://martinfowler.com/bliki/TestPyramid.html), but adapted to (Micro)services.\n![testing-pyramid](./assets/testing-pyramid.jpg)\n\nYou will see that there are three different types of tests and each one of them has a concrete scope.\n\n- **End-To-End Tests** have been excluded on purpose, since their scope is broader than a single service.\n\n- **Component Tests**: this is a kind of test that have been popularized in Microservices Patterns (See [Service Component Tests](https://microservices.io/patterns/testing/service-component-test.html)),\nbut at the end is just another name for the well known Acceptance Tests. The scope is to test the service itself, in isolation, \"mocking\" external dependencies such as database (using [TestContainers](https://www.testcontainers.org/) for instance) and external services (using [Wiremock](http://wiremock.org/) for instance).\n\n- **Integration Tests**: this kind of tests are run in isolation, there is no real call to an external service or a real database.\nHere we include repositories, clients, controllers, consumers, producers tests etc. We can also include Contract Tests (extending Controller tests, for instance, to check contract with Consumers using some kind of tool like Pact.io).\n\n- **Unit Tests**: and finally we \"unit test\" what's the most important part of the service: the Domain. Here we include all the tests for Aggregates, Value Objects, Entities, Domain Events, Application Services (aka Use Cases), Domain Services etc.\n\nFor a full overview, have a look at [my article on Medium](https://fabridinapoli.medium.com/component-vs-integration-vs-unit-tests-in-microservices-architecture-e0aa389f93d1).\n\n## How to run\nFirst you will need to install [Copier](https://github.com/copier-org/copier) on your local machine.\nThis is an open-source tool to copy directories and files from one place to another also using templates.\nTo install it, run in your console: `pip install copier`\nThen to copy this template, run the following command:\n```\ncopier https://github.com/Hyunk3l/hexagonal-architecture-kotlin-template.git put-your-directory-here\n```\nyou will be asked about a few configurations (name of the package, project etc.).\nOnce done, open your `put-your-directory-here`.\n\n## How to run tests\nAs you already know, there are three type of tests. You can run them separately or together:\n- Component: `./gradlew componentTest`\n- Integration: `./gradlew integrationTest`\n- Unit: `./gradlew unitTest`\n\nTo run them together: `./gradlew test`\n\n## How to run locally\nIf you really want to run your service locally (why would you? It's fully covered with multiple layers of tests), run the following commands:\n\n1. Run containers `docker-compose up`\n2. Run the service `./gradlew bootRun`\n\n## Caveats\n- Domain is anemic: just a silly example :)\n- Not publishing Domain Events: maybe in the future I will.\n- In memory repository has not been tested (on purpose). Maybe in the future I'll add a real db repository implementation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyunk3l%2Fhexagonal-architecture-kotlin-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyunk3l%2Fhexagonal-architecture-kotlin-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyunk3l%2Fhexagonal-architecture-kotlin-template/lists"}