Hexagonal Architecture Template

📌 Overview

This repository is a Kotlin + Spring Boot backend template built using Hexagonal Architecture (Ports & Adapters).

It is designed to be used as a GitHub Template, so you can quickly bootstrap new backend services with a clean, scalable structure.

---

🚀 Getting Started (Using This Template)

1. Create a New Repository

Click "Use this template" on GitHub and create your new project.

---

2. Run Setup Script

After cloning your new repository:

chmod +x scripts/setup.sh
./scripts/setup.sh

---

3. Provide Required Inputs

The script will ask for:

• Project name (e.g. order-service)
• Base package (e.g. com.yourcompany.orderservice)

---

4. What the Script Does

✅ Renames:

• Project (hamlet → your project name)

✅ Updates:

• pom.xml (artifactId, name)
• README.md
• Kotlin package declarations

✅ Refactors:

• Package structure (com.lucienvirecourt.hamlet → your package)

✅ Cleans:

• Removes template setup script after execution

---

5. Next Steps

./mvnw clean install -DskipTests -U
docker-compose -f bootstrap/src/main/resources/docker/docker-compose.dev.yml up
./mvnw spring-boot:run -pl bootstrap

---

🧱 Architecture

This project follows Hexagonal Architecture:

          ┌──────────────────────────┐
          │        Adapter           │
          │ (GraphQL / REST / JPA)   │
          └──────────┬───────────────┘
                     │
          ┌──────────▼───────────────┐
          │      Application         │
          │   (Use Cases / Ports)    │
          └──────────┬───────────────┘
                     │
          ┌──────────▼───────────────┐
          │        Domain            │
          │   (Pure Business Logic)  │
          └──────────────────────────┘

---

📂 Modules

model (Domain Layer)

• Core business models
• Framework-independent

---

application (Use Cases)

• Business logic

• Ports:

  • port.in (use cases)
  • port.out (interfaces)

---

adapter (Infrastructure)

• Inbound:

  • GraphQL
  • REST

• Outbound:

  • JPA (database)

---

bootstrap (Entry Point)

• Spring Boot startup
• Configuration
• Flyway migrations
• Docker setup

---

🔄 Example Flow

Create User:

1. Request → GraphQL/REST (adapter)
2. → CreateUserUseCase
3. → CreateUserService
4. → UserRepository
5. → JPA Adapter
6. → Response

---

🗃️ Database & Migrations

Uses Flyway.

Location:

bootstrap/src/main/resources/db.migration

---

🐳 Running Locally

Start Database

docker-compose -f bootstrap/src/main/resources/docker/docker-compose.dev.yml up

Run Application

./mvnw spring-boot:run -pl bootstrap

---

⚙️ Configuration

Profiles:

• dev
• staging
• prod

Files:

application.yml
application-dev.yml
application-staging.yml
application-prod.yml

---

🧪 Testing

./mvnw test

---

🎯 Why This Template?

• ✅ Clean Architecture (Hexagonal)
• ✅ Scalable for microservices
• ✅ Framework-independent domain
• ✅ Easy to test
• ✅ Ready-to-use Flyway + Docker setup

---

🛠️ Customization Notes

• Default package:

  com.lucienvirecourt.hamlet
  

• This will be replaced by the setup script

---

⚠️ Notes

• macOS & Linux are supported
• If script fails, check sed compatibility
• Always review changes before committing

---

🚀 Future Improvements

• GitHub Actions CI
• Authentication module
• Observability (metrics + logging)
• Event-driven support

---

👨‍💻 Author

Template built for scalable backend systems using Kotlin & Spring Boot.