EdTech · Backend Engineering · 2025

Microservice backend with hexagonal architecture and a 5-layer security pipeline

A content and learning platform built as a set of independent Kotlin/Spring Boot 3 microservices. The authentication service follows strict Hexagonal Architecture with domain, use-case, and adapter layers. GitHub Actions pipelines run five parallel security scans per service with a hard gate blocking any High or Critical finding before deployment to Managed Kubernetes.

  • 4Services / repositories
  • 5Security scan layers
  • HexArchitecture pattern
  • Dev + ProdEnvironments
Microservice backend with hexagonal architecture and a 5-layer security pipeline

Context

A learning platform that needed a maintainable, secure backend from day one

The project required an authentication and content delivery backend that could grow across multiple teams without accumulating technical debt. The codebase had to be easy to test, easy to replace individual components, and safe to deploy — with no security shortcuts. The platform serves registered users through a React frontend and exposes its services via an API gateway.

Challenge

Clean internal design, two environments, and a zero-tolerance security policy

The authentication service needed to be fully decoupled — domain logic with no framework dependencies, use cases defined as ports, and Spring Boot only in the adapter and boot layers. Two Kubernetes environments (dev and prod) needed independent deployment pipelines triggered by different git events. Every service needed a complete security scan on every pipeline run, with automated rollback available if anything went wrong in production.

Solution

Hexagonal architecture services with a reusable security pipeline

Each service was built as an independent Gradle multi-module project. The authentication service strictly applies Hexagonal Architecture. GitHub Actions pipelines are built from composable reusable workflows, keeping each service's pipeline DRY while running the full security suite.

Hexagonal architecture

The authentication service is split into domain (User entity, value objects: Email, UserId, PasswordHash, FirstName, LastName), usecase (RegisterUserUseCase, AuthenticateUserUseCase with ports: UserRepository, TokenIssuerPort, PasswordEncoderPort, ClockPort, AuditLogRepository), adapters (REST, JPA, security — BCrypt and JWT implementations), and boot layers. No Spring annotation in domain or usecase code.

Multi-service layout

Four repositories: rldp-uigateway-service (auth, Kotlin/Spring Boot 3, JDK 21, PostgreSQL/JPA), cms-guideservice (CMS/content, Spring Boot + Thymeleaf), rldp-uigateway (API gateway), and rldp-client (React 19 + TypeScript + Vite + Bootstrap 5). Each deploys independently via its own GitHub Actions pipeline.

5-layer security pipeline

Every service runs: Gitleaks (secret detection, any leak = pipeline fail), Semgrep SAST (Java/Kotlin rules), Trivy SCA (dependency vulnerability scan), Trivy Image (container vulnerability scan), and OWASP ZAP DAST (full scan against deployed URL). A unified Security Gate aggregates all reports — zero High/Critical findings allowed before deployment proceeds.

Dev / prod environments

Dev pipelines trigger on git tags (`deploy-dev*`), deploying to the `rldp-dev` Kubernetes namespace with SHA-based image tags. Prod pipelines trigger on release branches, deploying to the `rldp` namespace with branch-name tags. Helm charts per service, images in GHCR, rollback workflows available for both environments.

Engineering approach

How it was built

01

Architecture design

Defined the hexagonal layer boundaries for the auth service — domain entities and value objects first, then use-case ports, then adapters. Designed the Gradle multi-module build structure (domain, usecase, adapters/rest, adapters/security, adapters/db-jpa, boot).

02

Security pipeline

Built reusable workflow files for each scan tool (Semgrep, Trivy SCA, Trivy Image, Gitleaks, OWASP ZAP). Implemented the Security Gate job that downloads all scan artifacts, aggregates High/Critical counts, and fails the pipeline if any threshold is exceeded.

03

Kubernetes setup

Created Helm charts per service with configmap-based config injection, separate secrets management workflow, and imagePullSecret handling. Configured dev and prod namespaces with independent Helm release names and rollback workflows.

04

Client & gateway

Built the React 19 frontend with TypeScript, Vite, and Bootstrap 5. Connected client through the API gateway to backend services. Wired the CMS guide service with Thymeleaf for server-side content rendering.

Results

Measured impact

  • 4Independent services
  • 5Security scan types
  • 0High/Critical CVEs in prod
  • HexZero-framework domain layer
  • AutoRollback capability

Technology

Stack & capabilities

  • Kotlin
  • Spring Boot 3
  • JDK 21
  • Hexagonal Architecture
  • PostgreSQL
  • Spring Data JPA
  • JWT
  • React 19
  • TypeScript
  • Vite
  • Kubernetes
  • Helm
  • GitHub Actions
  • Semgrep
  • Trivy
  • OWASP ZAP
  • Gitleaks
  • GHCR

Facing a similar challenge?

Start a project