In this guide (8 items)

Architecture Overview

Project-agnostic catalog. Part of the Diagram Catalog. Covers: high-level architectural pattern, hexagonal implementation, module structure.

Replace com.example.platform / platform-service placeholders with your project’s actual package and service name when applying patterns.

1. Architecture Overview

1.1 Main Architectural Pattern

The project implements Hexagonal Architecture (Ports & Adapters) combined with Clean Architecture, structured in clearly defined layers:

1
┌─────────────────────────────────────────────────────────────┐
2
│        Entry Points (Inbound Adapters — Infrastructure)     │
3
│  REST, GraphQL, Schedulers, Webhooks, Kafka Consumers       │
4
└──────────────────┬──────────────────────────────────────────┘
5
                   │ (Inbound Ports)
6
┌─────────────────▼────────────────────────────────────────┐
7
│                Application Layer                          │
8
│  • Use Cases (Business Logic)                             │
9
│  • Inbound Ports (Command/Query Interfaces)               │
10
│  • Outbound Ports (Repository/Publisher Interfaces)       │
11
│  • Commands (Input DTOs)                                  │
12
└──────────────┬─────────────────┬──────────────────────────┘
13
               │                 │ (Outbound Ports)
14
┌──────────────▼─┐  ┌────────────▼────────────────────┐
15
│  Domain Layer  │  │     Driven Adapters             │
16
│  • Entities    │  │  • JDBC Repositories            │
17
│  • Value Objs  │  │  • Kafka Publishers             │
18
│  • Exceptions  │  │  • Redis Cache                  │
19
│  • Utils       │  │  • Metrics Publishers           │
20
└────────────────┘  └─────────────────────────────────┘

1.2 Core Principles

Dependency Inversion: All dependencies point inward (toward Domain)
Port-Based Design: All external communication through ports
Framework Independence: Domain and Application layers are pure Kotlin
Testability: Ports enable easy mocking and unit testing
Single Responsibility: Each layer has a clear, distinct purpose

2. Hexagonal Architecture Implementation

2.1 Layers Description

Domain Layer (Core/Center)

Location: domain/
Purpose: Contains business entities and domain logic
Dependencies: None (completely independent)
Contains:
- Organization, User (Entities)
- OrganizationStatus, Roles (Enums)
- OrganizationNotFoundException (Domain Exceptions)
- MdcUtil, TraceContextUtil (Domain Utilities)

Application Layer (Use Cases)

Location: application/
Purpose: Orchestrates business workflows
Dependencies: Domain only
Contains:
- Inbound Ports: Define how external world invokes the app
- Outbound Ports: Define how app communicates with infrastructure
- Use Cases: Implement business logic using domain entities
- Commands: Input DTOs for use cases

Infrastructure Layer (Adapters)

Location: infrastructure/
Purpose: Implements technical details
Dependencies: Application, Domain, External libraries
Contains:
- Entry Points:
  - rest-controller: REST API endpoints.
  - graphql-controllers: GraphQL schema and resolvers.
  - webhooks-controller: External webhook handlers.
  - scheduler-task: Periodic background tasks.
  - kafka-consumer: Message queue consumers.
- Driven Adapters: JDBC, Kafka, Redis, Metrics

Bootstrap Layer (Configuration)

Location: bootstrap/
Purpose: Dependency injection and app configuration
Dependencies: All other layers
Contains:
- Spring Boot configuration
- Bean definitions
- Application properties

2.2 Complete Layer Diagram

1
┌─────────────────────────────────────────────────────────────────┐
2
│                        BOOTSTRAP LAYER                          │
3
│  • Spring Boot Configuration (UseCaseConfig, ScheduleConfig)    │
4
│  • Dependency Injection (Connects Ports ↔ Adapters)             │
5
│  • Application Properties (application.yml)                     │
6
└────────────────────────┬────────────────────────────────────────┘
7
                         │ wires dependencies
8
        ┌────────────────┴────────────────┐
9
        │                                 │
10
┌───────▼────────────────────┐   ┌────────▼──────────────────────┐
11
│   ENTRY POINTS             │   │   DRIVEN ADAPTERS             │
12
│   (Infrastructure)         │   │   (Infrastructure)            │
13
│                            │   │                               │
14
│ • REST Controllers         │   │ • JDBC Repositories           │
15
│   - OrganizationController │   │   - OrganizationRepoAdapter   │
16
│                            │   │   - UserRepositoryAdapter     │
17
│ • Schedulers               │   │   - OutboxRepositoryAdapter   │
18
│   - OutboxTaskScheduler    │   │   - JdbcTransaction<R>        │
19
│                            │   │                               │
20
│ • Filters                  │   │ • Kafka Publishers            │
21
│   - TraceIdFilter          │   │   - OrganizationKafkaAdapter  │
22
│                            │   │   - UserKafkaAdapter          │
23
└────────────┬───────────────┘   │   - OutboxKafkaAdapter        │
24
             │ implements         │                               │
25
             │ inbound ports      │ • Redis Cache                 │
26
             │                    │   - OrganizationCacheAdapter  │
27
┌────────────▼────────────────────▼───────────────────────────────┐
28
│                    APPLICATION LAYER                            │
29
│                                                                  │
30
│  ┌──────────────────────────────────────────────────────────┐  │
31
│  │                    INBOUND PORTS                         │  │
32
│  │  • CreateOrganizationPort                                │  │
33
│  │  • GetOrganizationByIdPort                               │  │
34
│  │  • ChangeOrganizationStatusPort                          │  │
35
│  │  • SendOutboxMessagesPort (SDK)                          │  │
36
│  └────────────┬─────────────────────────────────────────────┘  │
37
│               │ implemented by                                  │
38
│  ┌────────────▼─────────────────────────────────────────────┐  │
39
│  │                    USE CASES                             │  │
40
│  │  • CreateOrganizationUseCase                             │  │
41
│  │  • GetOrganizationByIdUseCase                            │  │
42
│  │  • ChangeOrganizationStatusUseCase                       │  │
43
│  │  • SendOutboxMessagesUseCase (SDK)                       │  │
44
│  └────────────┬─────────────────────────────────────────────┘  │
45
│               │ depends on                                      │
46
│  ┌────────────▼─────────────────────────────────────────────┐  │
47
│  │                   OUTBOUND PORTS                         │  │
48
│  │  Repositories:                                           │  │
49
│  │    • OrganizationRepositoryPort                          │  │
50
│  │    • UserRepositoryPort                                  │  │
51
│  │    • OutboxRepositoryPort (SDK)                          │  │
52
│  │                                                          │  │
53
│  │  Messaging:                                              │  │
54
│  │    • MessagePublisherPort (SDK — consumed ONLY by the    │  │
55
│  │      SDK dispatcher, NEVER by application use cases)     │  │
56
│  │                                                          │  │
57
│  │  Domain factories (no annotations):                      │  │
58
│  │    • EventMessageFactory (SDK)                           │  │
59
│  │    • OutboxEventFactory (SDK)                            │  │
60
│  │                                                          │  │
61
│  │  Support:                                                │  │
62
│  │    • TransactionPort<R>                                  │  │
63
│  │    • ChainablePort<T>                                    │  │
64
│  └──────────────────────────────────────────────────────────┘  │
65
│                                                                  │
66
│  ┌──────────────────────────────────────────────────────────┐  │
67
│  │                      COMMANDS                            │  │
68
│  │  • CreateOrganizationCommand                             │  │
69
│  │  • CommandMappers (to Domain)                            │  │
70
│  └──────────────────────────────────────────────────────────┘  │
71
└────────────────────────┬─────────────────────────────────────┘
72
                         │ uses
73
┌────────────────────────▼─────────────────────────────────────┐
74
│                      DOMAIN LAYER                             │
75
│                                                               │
76
│  • Entities: Organization, User                              │
77
│  • Value Objects: (future implementation)                    │
78
│  • Enums: OrganizationStatus, Roles                          │
79
│  • Exceptions: OrganizationNotFoundException                 │
80
│  • Utils: MdcUtil, TraceContextUtil                          │
81
│                                                               │
82
│  ⚠️  NO DEPENDENCIES - Pure Kotlin                            │
83
└───────────────────────────────────────────────────────────────┘

3. Module Structure

3.1 Directory Tree

1
platform-service/
2
│
3
├── domain/                              # Core business logic
4
│   └── src/main/kotlin/.../domain/
5
│       ├── Organization.kt
6
│       ├── User.kt
7
│       ├── enums/
8
│       │   ├── OrganizationStatus.kt
9
│       │   └── Roles.kt
10
│       ├── exception/
11
│       │   └── OrganizationNotFoundException.kt
12
│       ├── support/
13
│       │   └── OutboxMessage.kt
14
│       └── util/
15
│           ├── MdcUtil.kt
16
│           └── TraceContextUtil.kt
17
│
18
├── application/                         # Use cases and ports
19
│   └── src/main/kotlin/.../
20
│       ├── port/
21
│       │   ├── inbound/                # Entry contracts (service-owned)
22
│       │   │   ├── CreateOrganizationPort.kt
23
│       │   │   ├── GetOrganizationByIdPort.kt
24
│       │   │   └── ChangeOrganizationStatusPort.kt
25
│       │   │   # SendOutboxMessagesPort lives in codehuntersio-sdk-event-messaging
26
│       │   │
27
│       │   └── outbound/               # Exit contracts (service-owned)
28
│       │       └── repository/
29
│       │           ├── OrganizationRepositoryPort.kt
30
│       │           ├── UserRepositoryPort.kt
31
│       │           └── support/
32
│       │               ├── TransactionPort.kt
33
│       │               ├── TransactionCallbackPort.kt
34
│       │               └── ChainablePort.kt
35
│       │       # NO publisher/ folder.
36
│       │       # OutboxRepositoryPort + MessagePublisherPort + OutboxEventFactory
37
│       │       # come from codehuntersio-sdk-event-messaging — inject directly in use cases.
38
│       │
39
│       └── usecase/                    # Business logic
40
│           └── organization/
41
│               ├── CreateOrganizationUseCase.kt
42
│               ├── GetOrganizationByIdUseCase.kt
43
│               ├── ChangeOrganizationStatusUseCase.kt
44
│               └── command/
45
│                   ├── CreateOrganizationCommand.kt
46
│                   └── mapper/
47
│                       └── CommandMapper.kt
48
│
49
├── infrastructure/                      # Technical implementations
50
│   ├── entry-points/                   # Inbound adapters
51
│   │   ├── rest-controller/
52
│   │   │   └── .../controller/organization/
53
│   │   │       ├── OrganizationController.kt
54
│   │   │       └── model/
55
│   │   │           ├── request/
56
│   │   │           │   └── CreateOrganizationRequest.kt
57
│   │   │           └── response/
58
│   │   │               ├── CreatedOrganizationResponse.kt
59
│   │   │               └── OrganizationResponse.kt
60
│   │   │
61
│   │   └── scheduler-task/
62
│   │       └── OutboxTaskScheduler.kt
63
│   │
64
│   └── driven-adapters/                # Outbound adapters
65
│       ├── jdbc-repository/
66
│       │   └── OrganizationRepositoryAdapter.kt
67
│       ├── kafka-producer/
68
│       │   └── OrganizationKafkaPublisherAdapter.kt
69
│       ├── redis-cache/
70
│       │   └── OrganizationCacheAdapter.kt
71
│       └── metrics-publisher/
72
│           └── OrganizationMetricsAdapter.kt
73
│
74
└── bootstrap/                           # Configuration
75
    └── src/main/kotlin/.../config/
76
        ├── UseCaseConfig.kt
77
        ├── ScheduleConfig.kt
78
        └── resources/
79
            └── application.yml