hackathon/docs/architecture/hexagonal-architecture-analysis.md

Hexagonal Architecture Analysis for HTTP Sender Plugin (HSP)

Document Version: 1.0 Date: 2025-11-19 Analyst: Hive Mind Analyst Agent Status: Recommended Architecture

---

Executive Summary

RECOMMENDATION: ✅ Hexagonal Architecture is HIGHLY SUITABLE for the HSP system.

The hexagonal (ports and adapters) architecture pattern provides optimal alignment with the HSP requirements, particularly for testability, maintainability, and compliance needs. The clear separation of business logic from external dependencies enables effective mock testing, supports ISO-9001/EN 50716 compliance, and facilitates the producer-consumer pattern with multi-threaded virtual threads.

Key Benefits:

• Superior testability with clear port boundaries
• Clean separation enabling independent testing of HTTP polling and gRPC transmission
• Natural alignment with producer-consumer pattern
• Enhanced maintainability for long-term support (Req-Norm-6)
• Simplified compliance documentation (Req-Norm-1, Req-Norm-2)

---

1. Hexagonal Architecture Overview

1.1 Core Principles

Hexagonal architecture (also known as ports and adapters) organizes code around:

1. Core Domain Logic (Hexagon center)

   • Business rules independent of external concerns
   • Pure Java/Kotlin with no framework dependencies
   • Defines interfaces (ports) for external interactions

2. Ports (Interfaces)

   • Primary ports: Driven by external actors (inbound)
   • Secondary ports: Drive external systems (outbound)
   • Technology-agnostic contracts

3. Adapters (Implementations)

   • Primary adapters: HTTP endpoints, configuration files
   • Secondary adapters: HTTP clients, gRPC clients, loggers
   • Pluggable implementations

1.2 Benefits for HSP

• Testability: Mock any adapter without changing core logic
• Flexibility: Swap implementations (e.g., REST → gRPC polling)
• Clarity: Explicit dependencies and boundaries
• Maintainability: Changes isolated to specific adapters
• Compliance: Clear documentation of system boundaries

---

2. Port Identification for HSP

2.1 Primary Ports (Inbound)

These are interfaces that external actors use to interact with the system:

Port 1: Configuration Management

interface ConfigurationPort {
    fun loadConfiguration(): HSPConfiguration
    fun reloadConfiguration(): Result<Unit>
    fun validateConfiguration(config: HSPConfiguration): ValidationResult
}

Purpose: Load and validate device configurations Adapter: YAML file reader (io.github.config4k or similar) Testing: Mock with in-memory configuration

Port 2: Health Check API

interface HealthCheckPort {
    fun getHealthStatus(): HealthStatus
    fun isHealthy(): Boolean
    fun getDetailedMetrics(): HealthMetrics
}

Purpose: Provide health monitoring endpoint Adapter: HTTP server (Ktor, Javalin, or embedded Jetty) Testing: Mock HTTP requests without actual server

Port 3: Lifecycle Management

interface LifecyclePort {
    fun start(): Result<Unit>
    fun stop(): Result<Unit>
    fun restart(): Result<Unit>
}

Purpose: Control HSP startup/shutdown Adapter: Main application controller Testing: Unit tests without system-level operations

2.2 Secondary Ports (Outbound)

These are interfaces the core domain uses to interact with external systems:

Port 4: HTTP Data Collection

interface HttpPollingPort {
    suspend fun pollDevice(device: DeviceConfiguration): Result<DeviceData>
    fun supportsDevice(deviceType: String): Boolean
}

Purpose: Retrieve data from HTTP endpoints Adapter: Ktor HTTP client with device-specific implementations Testing: MockEngine for controlled responses (Req-Test-2)

Port 5: gRPC Transmission

interface DataTransmissionPort {
    suspend fun sendData(data: CollectorData): Result<Unit>
    fun openStream(): Result<StreamHandle>
    fun closeStream(): Result<Unit>
}

Purpose: Stream data to Collector Core via gRPC Adapter: gRPC Kotlin client stub Testing: In-process gRPC server (Req-Test-3)

Port 6: Logging & Monitoring

interface LoggingPort {
    fun logInfo(message: String, context: Map<String, Any> = emptyMap())
    fun logWarning(message: String, context: Map<String, Any> = emptyMap())
    fun logError(message: String, error: Throwable? = null, context: Map<String, Any> = emptyMap())
    fun logMetric(name: String, value: Double, tags: Map<String, String> = emptyMap())
}

Purpose: Application logging and metrics Adapter: SLF4J with Logback Testing: In-memory log capture

Port 7: Time & Scheduling

interface SchedulingPort {
    fun scheduleAtFixedRate(initialDelay: Duration, period: Duration, task: suspend () -> Unit): Job
    fun currentTime(): Instant
}

Purpose: Device polling scheduling Adapter: Kotlin coroutines with virtual threads Testing: Controllable time source for deterministic tests

---

3. Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                    PRIMARY ADAPTERS                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ YAML Config  │  │ HTTP Health  │  │  CLI/Main    │      │
│  │   Reader     │  │   Endpoint   │  │  Controller  │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                  │                  │              │
│         ▼                  ▼                  ▼              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │            PRIMARY PORTS (Inbound)                   │   │
│  │  • ConfigurationPort                                 │   │
│  │  • HealthCheckPort                                   │   │
│  │  • LifecyclePort                                     │   │
│  └──────────────────────┬───────────────────────────────┘   │
│                         │                                    │
│  ┌──────────────────────▼─────────────────────────────┐    │
│  │                                                      │    │
│  │           CORE DOMAIN LOGIC (HEXAGON)              │    │
│  │                                                      │    │
│  │  • Device Management                                │    │
│  │  • Data Collection Orchestration                    │    │
│  │  • Producer-Consumer Coordination                   │    │
│  │  • Configuration Validation                         │    │
│  │  • Health Status Calculation                        │    │
│  │                                                      │    │
│  └──────────────────────┬───────────────────────────────┘   │
│                         │                                    │
│  ┌──────────────────────▼─────────────────────────────┐    │
│  │          SECONDARY PORTS (Outbound)                 │    │
│  │  • HttpPollingPort                                  │    │
│  │  • DataTransmissionPort                             │    │
│  │  • LoggingPort                                      │    │
│  │  • SchedulingPort                                   │    │
│  └──────────────────────┬───────────────────────────────┘   │
│                         │                                    │
│         ┌───────────────┼───────────────┐                   │
│         ▼               ▼               ▼                   │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐       │
│  │ Ktor HTTP    │ │ gRPC Kotlin  │ │ SLF4J +      │       │
│  │   Client     │ │    Client    │ │  Logback     │       │
│  └──────────────┘ └──────────────┘ └──────────────┘       │
│                    SECONDARY ADAPTERS                        │
└─────────────────────────────────────────────────────────────┘

---

4. Alignment with HSP Requirements

4.1 Testability Requirements

Requirement: Mock HTTP servers and gRPC servers for testing (Req-Test-2, Req-Test-3)

Hexagonal Support: ✅ EXCELLENT

• HTTP Mocking: HttpPollingPort can be mocked with predetermined responses
• gRPC Mocking: DataTransmissionPort allows in-process test servers
• No Real Network: Core domain tests run without actual HTTP/gRPC
• Test Doubles: Easily create fake, stub, or mock implementations

Example Test Structure:

class DataCollectionOrchestratorTest {
    private val mockHttpPolling = mockk<HttpPollingPort>()
    private val mockTransmission = mockk<DataTransmissionPort>()
    private val testScheduler = TestSchedulingPort() // Controllable time

    private val orchestrator = DataCollectionOrchestrator(
        httpPolling = mockHttpPolling,
        transmission = mockTransmission,
        scheduler = testScheduler
    )

    @Test
    fun `should collect data from multiple devices concurrently`() {
        // Arrange
        coEvery { mockHttpPolling.pollDevice(any()) } returns Result.success(testData)
        coEvery { mockTransmission.sendData(any()) } returns Result.success(Unit)

        // Act
        orchestrator.collectFromAllDevices()

        // Assert
        coVerify(exactly = 1000) { mockHttpPolling.pollDevice(any()) }
        coVerify(atLeast = 1) { mockTransmission.sendData(any()) }
    }
}

4.2 Producer-Consumer Pattern (Req-Arch-7)

Requirement: Implement producer-consumer with buffering

Hexagonal Support: ✅ NATURAL FIT

• Port Separation: HttpPollingPort (producer) and DataTransmissionPort (consumer) are separate
• Core Orchestration: Domain logic manages the buffer/queue between ports
• Adapter Independence: HTTP polling and gRPC transmission evolve independently

Architecture:

class DataCollectionOrchestrator(
    private val httpPolling: HttpPollingPort,
    private val transmission: DataTransmissionPort,
    private val scheduler: SchedulingPort
) {
    private val dataBuffer = Channel<CollectorData>(capacity = 10000) // Req-Arch-7

    // Producer: Polls devices and puts data in buffer
    suspend fun produceData() {
        devices.forEach { device ->
            val data = httpPolling.pollDevice(device).getOrNull()
            if (data != null) {
                dataBuffer.send(data)
            }
        }
    }

    // Consumer: Takes from buffer and transmits via gRPC
    suspend fun consumeData() {
        for (data in dataBuffer) {
            transmission.sendData(data)
        }
    }
}

4.3 Multi-Threaded Virtual Threads (Req-Arch-6)

Requirement: Use virtual threads for concurrent device polling

Hexagonal Support: ✅ COMPATIBLE

• Adapter Agnostic: Virtual threads implementation in adapters
• Domain Coordination: Core orchestrates concurrency via ports
• Testing Simplicity: Mock ports execute synchronously in tests

Implementation:

// Domain code (hexagon center) - concurrency-agnostic
interface SchedulingPort {
    suspend fun runConcurrently(tasks: List<suspend () -> Unit>)
}

// Adapter implementation - uses virtual threads
class VirtualThreadSchedulingAdapter : SchedulingPort {
    override suspend fun runConcurrently(tasks: List<suspend () -> Unit>) {
        withContext(Dispatchers.IO.limitedParallelism(1000)) { // Virtual threads
            tasks.map { task ->
                async { task() }
            }.awaitAll()
        }
    }
}

// Test adapter - sequential execution for determinism
class TestSchedulingAdapter : SchedulingPort {
    override suspend fun runConcurrently(tasks: List<suspend () -> Unit>) {
        tasks.forEach { it() } // Sequential for predictable tests
    }
}

4.4 Compliance Requirements (Req-Norm-1, Req-Norm-2)

Requirement: ISO-9001 and EN 50716 compliance

Hexagonal Support: ✅ STRONG

• Clear Boundaries: Ports provide explicit system interfaces for documentation
• Traceability: Each port maps to specific requirements
• Change Control: Adapter changes don't affect core domain (stability)
• Testing Evidence: Port-based testing provides audit trail

Documentation Benefits:

Port: HttpPollingPort
├── Requirement: Req-Func-1 (HTTP polling)
├── Requirement: Req-Func-3 (1000 devices)
├── Test Coverage: DataCollectionTest.kt (98%)
├── Implementations:
│   ├── KtorHttpPollingAdapter (production)
│   └── MockHttpPollingAdapter (testing)
└── Compliance: EN 50716 §4.2.1 (data acquisition)

4.5 Maintainability (Req-Norm-6)

Requirement: Long-term maintenance without specialized knowledge

Hexagonal Support: ✅ EXCELLENT

• Self-Documenting: Port interfaces clearly express system boundaries
• Modular Changes: Replace adapters without core domain changes
• Technology Isolation: Framework dependencies confined to adapters
• Upgrade Path: Swap libraries (e.g., Ktor → OkHttp) by changing adapter only

Example Evolution:

Year 1: Ktor HTTP client adapter
Year 3: Migrate to new HTTP library
  → Change: KtorHttpPollingAdapter → NewLibraryHttpPollingAdapter
  → Unchanged: HttpPollingPort interface, core domain logic
  → Impact: Isolated to one adapter

Year 5: Add new device protocol (e.g., MQTT)
  → Add: MqttPollingPort interface
  → Add: PahoMqttPollingAdapter
  → Unchanged: Existing HTTP and gRPC ports
  → Impact: Additive, no modification to existing code

---

5. Comparison with Alternative Architectures

5.1 Layered Architecture

Structure: Presentation → Business → Persistence layers

Pros:

• Simple to understand
• Traditional pattern familiar to many developers

Cons for HSP:

• ❌ Tight coupling to infrastructure (HTTP/gRPC in lower layers)
• ❌ Difficult to mock external dependencies
• ❌ Business logic can leak into layers
• ❌ Less flexible for producer-consumer separation

Verdict: Less suitable than hexagonal for testability requirements

5.2 Microservices Architecture

Structure: Separate services for polling, buffering, and transmission

Pros:

• Independent scaling
• Technology diversity

Cons for HSP:

• ❌ Over-engineering for a single plugin
• ❌ Network overhead between services
• ❌ Increased operational complexity
• ❌ Harder to test as integrated system
• ❌ Deployment complexity conflicts with Req-Norm-5 (standard installation)

Verdict: Too complex for HSP scope; hexagonal provides modularity without distribution overhead

5.3 Event-Driven Architecture

Structure: Events and message brokers for communication

Pros:

• Natural fit for producer-consumer
• Decoupled components

Cons for HSP:

• ❌ Requires message broker infrastructure
• ❌ More complex than needed for in-process communication
• ❌ Debugging complexity
• ❌ Testing requires broker mocking

Verdict: Adds unnecessary complexity; hexagonal's port-based producer-consumer is simpler

5.4 Clean Architecture (Layered + Hexagonal Hybrid)

Structure: Entities → Use Cases → Interface Adapters → Frameworks

Pros:

• Very similar to hexagonal
• Explicit use case layer

Cons for HSP:

• ⚠️ More layers than needed for HSP complexity
• ⚠️ Additional abstraction may not add value

Verdict: Viable alternative, but hexagonal is sufficient and simpler for HSP

---

6. Hexagonal Architecture Recommendations for HSP

6.1 Project Structure

hsp/
├── domain/                           # Core hexagon (no external dependencies)
│   ├── model/                        # Domain entities
│   │   ├── Device.kt
│   │   ├── DeviceData.kt
│   │   ├── HSPConfiguration.kt
│   │   └── HealthStatus.kt
│   ├── port/                         # Port interfaces
│   │   ├── primary/                  # Inbound ports
│   │   │   ├── ConfigurationPort.kt
│   │   │   ├── HealthCheckPort.kt
│   │   │   └── LifecyclePort.kt
│   │   └── secondary/                # Outbound ports
│   │       ├── HttpPollingPort.kt
│   │       ├── DataTransmissionPort.kt
│   │       ├── LoggingPort.kt
│   │       └── SchedulingPort.kt
│   └── service/                      # Domain services (business logic)
│       ├── DataCollectionOrchestrator.kt
│       ├── ConfigurationValidator.kt
│       └── HealthMonitor.kt
│
├── adapter/                          # Adapter implementations
│   ├── primary/                      # Inbound adapters
│   │   ├── config/
│   │   │   └── YamlConfigurationAdapter.kt
│   │   ├── http/
│   │   │   └── KtorHealthCheckAdapter.kt
│   │   └── cli/
│   │       └── MainApplicationAdapter.kt
│   └── secondary/                    # Outbound adapters
│       ├── http/
│       │   ├── KtorHttpPollingAdapter.kt
│       │   └── device/               # Device-specific implementations
│       │       ├── SiemensAdapter.kt
│       │       ├── WagoAdapter.kt
│       │       └── BeckhoffAdapter.kt
│       ├── grpc/
│       │   └── GrpcTransmissionAdapter.kt
│       ├── logging/
│       │   └── Slf4jLoggingAdapter.kt
│       └── scheduling/
│           └── CoroutineSchedulingAdapter.kt
│
├── test/                             # Test adapters and utilities
│   ├── adapter/
│   │   ├── MockHttpPollingAdapter.kt
│   │   ├── InProcessGrpcAdapter.kt
│   │   └── TestSchedulingAdapter.kt
│   └── fixture/
│       └── TestDataFactory.kt
│
└── main/
    └── Application.kt                # Dependency injection and wiring

6.2 Dependency Injection

Use Koin for lightweight dependency injection:

// Application.kt - Wire adapters to ports
fun main() {
    startKoin {
        modules(hspModule)
    }

    val lifecycle: LifecyclePort = get()
    lifecycle.start()
}

val hspModule = module {
    // Primary adapters
    single<ConfigurationPort> { YamlConfigurationAdapter("config.yaml") }
    single<HealthCheckPort> { KtorHealthCheckAdapter(port = 8080) }
    single<LifecyclePort> { MainApplicationController(get(), get()) }

    // Secondary adapters
    single<HttpPollingPort> { KtorHttpPollingAdapter() }
    single<DataTransmissionPort> { GrpcTransmissionAdapter(get()) }
    single<LoggingPort> { Slf4jLoggingAdapter() }
    single<SchedulingPort> { CoroutineSchedulingAdapter() }

    // Domain services
    single { DataCollectionOrchestrator(get(), get(), get(), get()) }
    single { ConfigurationValidator() }
    single { HealthMonitor(get(), get()) }
}

// Test configuration
val testModule = module {
    single<HttpPollingPort> { MockHttpPollingAdapter() }
    single<DataTransmissionPort> { InProcessGrpcAdapter() }
    single<SchedulingPort> { TestSchedulingAdapter() }
    // ... other test adapters
}

6.3 Testing Strategy

Unit Tests (Domain Logic)

// Test core domain without any adapters
class DataCollectionOrchestratorTest {
    private val mockConfig = mockk<ConfigurationPort>()
    private val mockPolling = mockk<HttpPollingPort>()
    private val mockTransmission = mockk<DataTransmissionPort>()
    private val mockScheduler = mockk<SchedulingPort>()

    private val orchestrator = DataCollectionOrchestrator(
        config = mockConfig,
        polling = mockPolling,
        transmission = mockTransmission,
        scheduler = mockScheduler
    )

    @Test
    fun `should validate configuration before starting`() {
        // Pure domain logic test
    }
}

Integration Tests (With Real Adapters)

// Test adapters with real implementations
class KtorHttpPollingAdapterTest {
    private val mockServer = MockEngine { request ->
        respond(
            content = """{"value": 42.5}""",
            headers = headersOf("Content-Type", "application/json")
        )
    }

    private val adapter = KtorHttpPollingAdapter(mockServer)

    @Test
    fun `should parse JSON response correctly`() {
        // Adapter-specific test with mock HTTP engine
    }
}

End-to-End Tests

// Test full system with test adapters
class HSPSystemTest {
    @Test
    fun `should collect data from 1000 devices and transmit via gRPC`() {
        startKoin { modules(testModule) } // Use test adapters

        val lifecycle: LifecyclePort = get()
        lifecycle.start()

        // Verify behavior through test adapters
        val mockPolling = get<HttpPollingPort>() as MockHttpPollingAdapter
        assertEquals(1000, mockPolling.pollCount)
    }
}

6.4 Compliance Documentation

Hexagonal architecture facilitates compliance documentation:

# ISO-9001 Requirement Traceability Matrix

| Requirement ID | Description | Port | Adapter | Test Coverage |
|----------------|-------------|------|---------|---------------|
| Req-Func-1 | HTTP polling | HttpPollingPort | KtorHttpPollingAdapter | 98% |
| Req-Func-2 | gRPC streaming | DataTransmissionPort | GrpcTransmissionAdapter | 95% |
| Req-Func-6 | Health monitoring | HealthCheckPort | KtorHealthCheckAdapter | 100% |
| Req-Arch-6 | Virtual threads | SchedulingPort | CoroutineSchedulingAdapter | 92% |
| Req-Arch-7 | Producer-consumer | DataCollectionOrchestrator | - | 97% |

---

7. Pros and Cons Summary

Advantages for HSP

✅ Superior Testability

• Clear boundaries enable comprehensive mocking (Req-Test-2, Req-Test-3)
• Domain logic tests run instantly without network I/O
• 100% code coverage achievable

✅ Maintainability

• Port interfaces serve as documentation (Req-Norm-6)
• Technology changes isolated to adapters
• Easy onboarding for new developers

✅ Compliance Support

• Explicit traceability from requirements to ports (Req-Norm-1, Req-Norm-2)
• Change impact analysis simplified
• Audit-friendly structure

✅ Flexibility

• Add new device protocols without modifying core
• Swap HTTP/gRPC implementations easily
• Support multiple configurations (test, production)

✅ Producer-Consumer Pattern

• Natural separation via ports (Req-Arch-7)
• Domain orchestrates buffer between polling and transmission
• Clear concurrency boundaries

✅ Virtual Thread Support

• Adapter-level implementation (Req-Arch-6)
• Domain remains concurrency-agnostic
• Test adapters can run sequentially

Potential Challenges

⚠️ Initial Learning Curve

• Developers unfamiliar with hexagonal may need training
• More interfaces than traditional layered architecture
• Mitigation: Comprehensive documentation, code examples

⚠️ More Files

• Ports + adapters = more files than monolithic code
• Directory structure more complex
• Mitigation: Clear naming conventions, logical grouping

⚠️ Interface Overhead

• Every external interaction requires a port interface
• Could feel like boilerplate for small features
• Mitigation: Ports provide long-term value; use code generation if needed

⚠️ Dependency Injection Required

• Need DI framework (Koin, Dagger) to wire adapters
• Additional configuration
• Mitigation: Koin is lightweight; configuration is one-time cost

Overall Assessment

Pros significantly outweigh cons for HSP. The initial investment in hexagonal structure pays dividends in testability, maintainability, and compliance—all critical requirements for HSP.

---

8. Implementation Roadmap

Phase 1: Foundation (Week 1-2)

1. Define core domain models (Device, DeviceData, HSPConfiguration)
2. Define primary ports (ConfigurationPort, HealthCheckPort, LifecyclePort)
3. Define secondary ports (HttpPollingPort, DataTransmissionPort, LoggingPort, SchedulingPort)
4. Set up project structure and Koin DI

Phase 2: Core Domain Logic (Week 3-4)

1. Implement DataCollectionOrchestrator (producer-consumer logic)
2. Implement ConfigurationValidator
3. Implement HealthMonitor
4. Write domain service unit tests (using mocks)

Phase 3: Adapters (Week 5-7)

1. Implement primary adapters (YAML config, HTTP health endpoint)
2. Implement secondary adapters (Ktor HTTP client, gRPC client)
3. Implement device-specific polling adapters (Siemens, Wago, Beckhoff)
4. Write adapter integration tests

Phase 4: Testing Infrastructure (Week 8)

1. Create mock adapters for testing
2. Create test data factories
3. Write end-to-end tests
4. Verify Req-Test-2 (mock HTTP) and Req-Test-3 (mock gRPC)

Phase 5: Integration & Documentation (Week 9-10)

1. Wire all components together
2. Performance testing (1000 devices, Req-Func-3)
3. Create traceability matrix for compliance
4. Document architecture decisions

---

9. Conclusion

Hexagonal architecture is the optimal choice for the HTTP Sender Plugin system. It directly addresses the critical requirements:

1. Testability: Port-based mocking enables comprehensive testing without real HTTP/gRPC servers (Req-Test-2, Req-Test-3)
2. Producer-Consumer Pattern: Natural separation between polling and transmission ports (Req-Arch-7)
3. Virtual Threads: Implementation detail in scheduling adapter (Req-Arch-6)
4. Compliance: Clear boundaries and traceability (Req-Norm-1, Req-Norm-2)
5. Maintainability: Self-documenting structure and technology isolation (Req-Norm-6)

The architecture provides a solid foundation for long-term maintenance, supports regulatory requirements, and enables rapid testing—all essential for a mission-critical data collection system.

Next Steps:

1. Review this analysis with the development team
2. Approve hexagonal architecture decision
3. Proceed to detailed design phase with port/adapter specifications
4. Begin implementation following the roadmap above

---

Appendix: References

• Alistair Cockburn, "Hexagonal Architecture" (2005)
• Robert C. Martin, "Clean Architecture" (2017)
• Vaughn Vernon, "Implementing Domain-Driven Design" (2013)
• ISO-9001:2015 Quality Management Systems
• EN 50716:2020 Railway Applications Standard