v0.2.0

0.2.0 (2026-01-03)

✨ Features

• docs: add Docusaurus documentation website and project infrastructure (03093fc)
• infra: add CI/CD workflows and comprehensive project documentation (cacd506)

🐛 Bug Fixes

• docs: update repository URLs to reflect new ownership (c659f77)
• docs: update repository URLs to reflect new ownership (e229ff7)

v0.1.0

🎉 Structus v0.1.0 - Initial Release

Structus - Kotlin Architecture Toolkit is a pure Kotlin JVM library providing foundational building blocks for implementing Explicit Architecture—a synthesis of Domain-Driven Design (DDD), Command/Query Separation (CQS), and Event-Driven Architecture (EDA).

This initial release establishes a production-ready foundation for building large-scale, maintainable applications using clean architecture principles while remaining completely framework-agnostic.

---

🎯 What is Structus?

Structus serves as a shared kernel for enterprise applications, defining interfaces and base classes for core business concepts and architectural patterns. It eliminates boilerplate code and enforces best practices without coupling your application to any specific framework.

Key Highlights

• ✅ Pure Kotlin - No framework dependencies (Spring, Ktor, Micronaut, etc.)
• ✅ Coroutine-Ready - All I/O operations use suspend functions
• ✅ Minimal Dependencies - Only Kotlin stdlib + kotlinx-coroutines-core (1.9.0)
• ✅ 100% Documented - Comprehensive KDoc on all public APIs
• ✅ Framework-Agnostic - Works with any framework or pure Kotlin
• ✅ AI-Agent Friendly - Includes .ai/ directory with templates and prompts
• ✅ Production-Ready - Explicit API mode, code coverage, quality checks

---

📦 Installation

Gradle (Kotlin DSL)

dependencies {
    implementation("com.melsardes.libraries:structus-kotlin:0.1.0")
}

Gradle (Groovy)

dependencies {
    implementation 'com.melsardes.libraries:structus-kotlin:0.1.0'
}

Maven

<dependency>
    <groupId>com.melsardes.libraries</groupId>
    <artifactId>structus-kotlin</artifactId>
    <version>0.1.0</version>
</dependency>

---

🏗️ Architecture Components

Domain Layer (com.melsardes.libraries.structus.domain)

Core Building Blocks

Entity

Abstract base class for identity-based domain objects with proper equality semantics based on ID rather than attributes.

Features:

• Generic ID type support
• Proper equals/hashCode implementation based on identity
• Comprehensive documentation on identity vs attribute equality
• Thread-safe design

ValueObject

Marker interface for immutable, attribute-based objects designed to work seamlessly with Kotlin data classes.

Features:

• Immutability guidelines
• Validation pattern recommendations
• Attribute-based equality semantics
• Integration with Kotlin data classes

AggregateRoot

Extends Entity with sophisticated event management capabilities. Serves as the consistency boundary and transactional entry point for aggregates.

Features:

• Event Management:

  • recordEvent(event: DomainEvent) - Protected method for internal event recording
  • domainEvents: List<DomainEvent> - Public read-only property for event retrieval
  • clearEvents() - Post-publish cleanup method
  • eventCount(), hasEvents() - Helper methods for event inspection

• Lifecycle Management:

  • markAsCreated(by: String, at: Instant) - Track entity creation
  • markAsUpdated(by: String, at: Instant) - Track modifications
  • softDelete(by: String, at: Instant) - Soft delete support
  • restore(by: String, at: Instant) - Restore deleted entities
  • isDeleted(), isActive() - Status checks
  • incrementVersion() - Optimistic locking support

• Best Practices:

  • Thread-safety documentation
  • Transaction boundary guidelines
  • Event sourcing compatibility
  • Comprehensive usage examples

Repository

Marker interface establishing the contract for all repository interfaces.

Features:

• Clear separation between interface (domain) and implementation (infrastructure)
• Guidelines for suspend functions
• Collection-like API design patterns
• Query method naming conventions

Event Infrastructure

DomainEvent

Base interface for all domain events with required metadata.

Properties:

• eventId: String - Unique event identifier
• occurredAt: Instant - Timestamp using Kotlin multiplatform time API
• aggregateId: String - Source aggregate identifier
• eventType: String - Event type discriminator

Features:

• Past-tense naming conventions
• Event sourcing compatibility
• Serialization guidelines
• Immutability requirements

BaseDomainEvent

Abstract base implementation providing default event metadata generation with automatic UUID generation and timestamp capture.

MessageOutboxRepository

Complete implementation of the Transactional Outbox Pattern to solve the dual-write problem in distributed systems.

Methods:

• save(message: OutboxMessage) - Save event to outbox table
• findUnpublished(limit: Int) - Find unpublished messages with pagination
• markAsPublished(messageId: String) - Mark message as successfully published
• incrementRetryCount(messageId: String) - Track retry attempts
• deleteOldPublishedMessages(olderThan: Instant) - Cleanup old messages
• findFailedMessages(maxRetries: Int) - Detect failed events

Includes:

• OutboxMessage data class with factory methods
• Database schema examples for PostgreSQL, MySQL, SQL Server
• Retry strategy documentation
• Idempotency guidelines

Result

Explicit error handling type replacing exception-based flows with type-safe success/failure semantics.

Features:

• Result.Success<T> - Successful operation with value
• Result.Failure - Failed operation with error message and optional exception
• Type-safe error handling
• Railway-oriented programming support
• Extension functions for mapping and chaining

---

Application Layer (com.melsardes.libraries.structus.application)

Commands (application.commands)

Command

Marker interface for write operations representing intent to change state.

Features:

• Imperative naming conventions (CreateOrder, UpdateCustomer)
• Validation strategy documentation
• Immutability requirements
• Data class compatibility

CommandHandler<C, R>

Interface for executing business logic with operator invoke support.

Signature:

suspend operator fun invoke(command: C): R

Features:

• Orchestration pattern documentation
• Transaction boundary guidelines
• Error handling strategies (exceptions vs Result types)
• Comprehensive implementation examples
• One-to-one command-to-handler mapping
• Suspend function support for async operations

CommandBus

Central command dispatcher providing type-safe routing.

Methods:

• register(handler: CommandHandler<C, R>) - Register command handlers
• dispatch(command: C): R - Execute commands through registered handlers

Features:

• Middleware/interceptor pattern support
• Implementation examples: simple, logging, transactional, validating
• Type-safe command routing
• Error propagation strategies

Queries (application.queries)

Query

Marker interface for read operations with question-based naming conventions.

Features:

• Question-based naming (GetOrderById, FindCustomersByName)
• CQRS pattern documentation
• Optimization strategies (projections, caching, denormalization)
• Read-only guarantee enforcement

QueryHandler<Q, R>

Interface for data retrieval operations.

Signature:

suspend operator fun invoke(query: Q): R

Features:

• Read-only guarantee enforcement
• Pagination support examples
• Projection patterns for optimized data transfer
• No transaction required documentation
• Caching strategy recommendations

Events (application.events)

DomainEventPublisher

Interface for publishing events to external systems.

Methods:

• publish(event: DomainEvent) - Single event publishing
• publishBatch(events: List<DomainEvent>) - Batch event publishing

Features:

• Transactional Outbox Pattern integration
• Implementation examples for Kafka, RabbitMQ, in-memory
• Event routing strategies
• Serialization guidelines
• Error handling and retry logic
• Idempotency recommendations

DomainEventHandler

Interface for handling domain events asynchronously with support for event-driven workflows.

---

🛠️ Build Configuration

Gradle Setup

• Gradle: 9.1.0 with Kotlin DSL
• Kotlin: 2.2.0 with explicit API mode enabled
• Java Toolchain: 21
• JaCoCo: Code coverage with 50% minimum threshold
• Maven Publishing: GitHub Packages support
• Artifacts: Main JAR, Sources JAR, Javadoc JAR

Dependencies

// Only external dependency
api("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")

// Test dependencies
testImplementation("org.jetbrains.kotlin:kotlin-test")
testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.9.0")
testImplementation("io.mockk:mockk:1.13.12")

Zero framework dependencies - No Spring, Ktor, Micronaut, R2DBC, JDBC, Hibernate, or any framework-specific libraries.

Quality Enforcement

• ✅ Explicit API mode for main sources (strict documentation requirements)
• ✅ Disabled for test sources to reduce boilerplate
• ✅ JUnit 5 test framework
• ✅ Comprehensive compiler options
• ✅ 100% public API documentation coverage

---

📚 Documentation

Comprehensive Documentation Suite

README.md

Complete library overview with:

• Installation instructions
• Quick start guide
• Architecture component descriptions
• Advanced patterns (Transactional Outbox, CQRS)
• Integration examples for Spring Boot and Ktor

QUICK_REFERENCE.md

• Package structure overview
• Core concepts comparison tables
• Common patterns with code examples
• Feature implement...