🧬 Konture: Kotlin Architecture Testing Guardrails

Konture is a stack- and build-tool agnostic Kotlin architecture testing library for Android, Kotlin Multiplatform (KMP), and JVM backend projects. It combines real project structure (captured directly from your project's build graph) with AST-based static analysis and a premium, architecture-agnostic Fluent Lambda DSL to enforce boundaries on any test framework.

---

🛡️ The problem

In multi-module, multi-layer projects, architecture erodes through small shortcuts. For example, a feature module might declare a "sideways" dependency on a sibling feature.

Konture helps developers analyze project structure and enforce architectural rules and boundaries directly inside the test suite.

---

🔑 Key Capabilities

• 📦 Platform & Stack Agnostic: Works seamlessly across Android, Kotlin Multiplatform (KMP), and Kotlin backend projects (Spring Boot, Ktor, etc.).
• 📐 Architecture Agnostic: Set constraints for any design pattern (Clean, Layered, MVVM, Hexagonal, DDD) without layout restrictions.
• 🛠️ Build Tool Agnostic: Engineered to support multiple build systems, with deep, native support for Gradle and Maven environments.
• 🧪 Test Framework Agnostic: Runs as a pure JVM library, compatible with JUnit 4, JUnit 5, JUnit 6, Kotest, TestBalloon, or any other runner.
• ✍️ Fluent Lambda DSL: Write expressive, readable assertions for module dependencies, package isolation, interface adherence, and naming conventions.
• 🤖 AI-Agent Friendly: Includes dedicated prompts and custom skills for autonomous integration and code generation:
  • 🤖 Installation: Automated Gradle project setup.
  • ✍️ AI Test Writing Guide: Context-rich master prompt for writing compile-safe DSL tests.

---

🚀 Getting Started

Tip

🤖 Automated Setup: Save time by using our 🤖 integrate-konture prompt/skill to let an AI assistant automatically configure your Gradle project and generate tests. See the AI Prompts Catalog for details.

Installation

Gradle

1. Apply the plugin in your root settings.gradle.kts:

plugins {
    id("io.github.baole.konture") version "1.0.1"
}

2. Add the dependency in your test module's build.gradle.kts (e.g. konture-test/build.gradle.kts):

plugins {
    kotlin("jvm")
}

dependencies {
    testImplementation("io.github.baole:konture:1.0.1")
}

Important

We recommend running your architectural guards in a dedicated test module, such as :konture-test (see our sample module).

Note

For alternative Gradle plugin setup formats, refer to the Gradle Plugin Portal.

Maven

1. Add the Konture Maven Plugin to your dedicated test module's pom.xml (e.g., konture-test/pom.xml):

<plugin>
    <groupId>io.github.baole.konture</groupId>
    <artifactId>konture-maven-plugin</artifactId>
    <version>1.0.1</version>
    <executions>
        <execution>
            <phase>process-test-resources</phase>
            <goals>
                <goal>generate-layout</goal>
            </goals>
        </execution>
    </executions>
</plugin>

2. Add the dependency to the same module's pom.xml:

<dependency>
    <groupId>io.github.baole</groupId>
    <artifactId>konture</artifactId>
    <version>1.0.1</version>
    <scope>test</scope>
</dependency>

Write Your First Guardrail

Create a unit test to enforce architectural boundaries and conventions. Since Konture is completely architecture-agnostic, you can configure guardrails that match your codebase's custom patterns:

import io.github.baole.konture.architecture
import org.junit.jupiter.api.Test

class ArchitectureGuardrails {

    @Test
    fun `domain layer should be completely isolated from data and UI layers`() {
        architecture {
            // 🎯 Select modules via wildcard pattern matching
            modules {
                that().haveNameMatching(":core:domain**")
                should().mustNotDependOn(":core:data**")
                andShould().mustNotDependOn(":feature:**")
            }
        }
    }

    @Test
    fun `repositories inside domain must be declared as interfaces`() {
        architecture {
            // 🎯 Select classes inside domain package
            classes {
                that().inPackage("..domain..")
                that().nameEndsWith("Repository")
                should().beInterfaces()
            }
        }
    }
}

📖 Documentation

Visit our official GitHub Pages Documentation Site or explore the resources directly:

• 🚀 Installation: Manual integration guide.
• 📐 Usage Guide: Writing your first tests and running checks.
• ⚙️ Configuration: Plugin custom parameters and wildcard matching mechanics.
• 🛡️ Architecture Baselines: Freeze and manage pre-existing technical debt.
• 🤖 AI Prompts & Skills Catalog: Dedicated prompts for autonomous setup and test generation.
• 🧩 Core Concepts: Static-analysis engine details.
• 📜 Recipes: Templates for common guardrails (layer isolation, interface conventions, etc.).
• 🏢 showcases: Real-world configurations (Now in Android, KotlinConf, Ktor, etc.).

🤝 Contributing

We welcome all contributions! Please check our Contribution Guidelines (or the online Contributing Guide) for local setup, build commands, and PR workflows.

Thanks to all our amazing contributors!

📄 License

This project is licensed under the Apache License, Version 2.0.