# ekino/jcv architecture

> Architecture diagram of the GitHub repository ekino/jcv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ekino/jcv
- Repository: https://github.com/ekino/jcv

## Overview

Based on our analysis of the provided file tree and README, this project is a Java/Kotlin-based open-source library called “JSON Content Validator (JCV)”. Its purpose is to provide a JSON comparator with embedded validators for making assertions on JSON content in tests. It is structured as a multi-module Gradle project with several modules that extend the core functionality (jcv-core) into integrations with AssertJ, Hamcrest, and WireMock.

##### Overall Architecture Identification
- Project Type & Purpose: Emphasize that JCV is a testing utility library designed to simplify JSON content assertions. The main core module provides the underlying JSON comparison logic and validator interfaces, and the “integration” modules (jcv-assertj, jcv-hamcrest, jcv-wiremock) serve as adapters for different testing frameworks.
- Project Structure: The repository is divided into submodules (jcv-core, jcv-assertj, jcv-hamcrest, jcv-wiremock) each addressing a specific testing integration.

##### Main Components to Illustrate
- Build System & Configuration:
- Gradle build scripts (build.gradle.kts, gradlew, gradlew.bat, gradle wrapper).
- GitHub workflows (.github/workflows) and configuration files (e.g., .editorconfig, gradle.properties) showing the build, test, release, and quality pipelines.

- Core Module (jcv-core):
- The heart of the library. Include components/classes such as JsonComparator, various JSON validators (like DefaultJsonValidator), comparator implementations (JsonComparator.kt, comparator classes including ContainsComparator, DateTimeFormatComparator, etc.), and initializers for comparators.
- Sub-packages like “core”, “comparator”, “initializer”, “validator” – these demonstrate a layered or modular design internally.

- Integration Modules:
- jcv-assertj: Provides an AssertJ-based assertion layer. Show that it depends on jcv-core and extends its capabilities with a fluent JSON assertion API.
- jcv-hamcrest: Implements Hamcrest matchers for JSON validations. Connect it to the core module, illustrating its reuse of the underlying JSON comparison functionality.
- jcv-wiremock: Allows integration with WireMock for stubbing and validating JSON requests/responses using JCV. Note its usage of a custom WireMock extension (e.g., JcvRequestMatcherExtension) that hooks into the core validation logic.

- Testing and Examples:
- The file structure includes several test directories (src/test, both in Java and Kotlin) and resource JSON files that provide ready-made examples.

##### Relationships and Interactions
- The dependency of each integration module on jcv-core.
- The build pipeline influencing all modules via the Gradle configuration.
- The test components interacting with both the core and integration modules to validate different use cases.
- How external libraries (JSONassert, AssertJ, Hamcrest, WireMock) interact with corresponding modules by being passed into the system (for example, through dependency injection or extension registration in WireMock).

##### Architectural Patterns and Design Principles
- Modularization: Each module stands alone with its own test suite and build file (organizing responsibilities and dependencies).
- Layered/Adapter Pattern: The core module abstracts JSON validation, while each adapter/integration layer (AssertJ, Hamcrest, WireMock) transforms validation results into idiomatic assertions for different frameworks.
- Configuration and Extensibility: Indicate that the configuration files (in the config/detekt directory, for instance) enforce code quality, and the library supports custom validations (as seen with embedded notations like {#uuid#} or {#date_time_format:iso_instant#}).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI Pipeline
    subgraph "Build & CI Pipeline"
        BS1("Gradle Build Scripts") 
        BS2("GitHub Workflows")
        BS3("Code Quality Config")
    end

    %% JCV Core Module
    subgraph "JCV Core"
        CC("JSON Comparator")
        CP("Comparators")
        CI("Initializers")
        CV("Validators")
        JC("Java Core Classes")
    end

    %% Integration Modules
    subgraph "Integration Modules"
        IA("jcv-assertj")
        IH("jcv-hamcrest")
        IW("jcv-wiremock")
    end

    %% Test Harness
    subgraph "Test Harness"
        TC("Core Tests")
        TA("AssertJ Tests")
        TH("Hamcrest Tests")
        TW("WireMock Tests")
    end

    %% External Dependencies
    EX("External Libraries"):::external

    %% Connections from Build & CI to Core and Integration Modules
    BS1 -->|"builds"| CC
    BS1 -->|"builds"| IA
    BS1 -->|"builds"| IH
    BS1 -->|"builds"| IW

    BS2 -->|"CI_for"| CC
    BS2 -->|"CI_for"| IA
    BS2 -->|"CI_for"| IH
    BS2 -->|"CI_for"| IW

    BS3 -->|"quality_for"| CC
    BS3 -->|"quality_for"| IA
    BS3 -->|"quality_for"| IH
    BS3 -->|"quality_for"| IW

    %% Core Module extended by Integration Modules
    CC -->|"extended_by"| IA
    CC -->|"extended_by"| IH
    CC -->|"extended_by"| IW

    %% External Libraries utilized by Integration Modules
    EX -->|"used_by"| IA
    EX -->|"used_by"| IH
    EX -->|"used_by"| IW

    %% Tests interacting with Modules
    TC -->|"tests"| CC
    TA -->|"tests"| IA
    TH -->|"tests"| IH
    TW -->|"tests"| IW

    %% Click Events for Build & CI
    click BS1 "https://github.com/ekino/jcv/blob/master/build.gradle.kts"
    click BS2 "https://github.com/ekino/jcv/tree/master/.github/workflows"
    click BS3 "https://github.com/ekino/jcv/blob/master/config/detekt/detekt.yml"

    %% Click Events for JCV Core Module
    click CC "https://github.com/ekino/jcv/blob/master/jcv-core/src/main/kotlin/com/ekino/oss/jcv/core/JsonComparator.kt"
    click CP "https://github.com/ekino/jcv/blob/master/jcv-core/src/main/kotlin/com/ekino/oss/jcv/core/comparator/ContainsComparator.kt"
    click CI "https://github.com/ekino/jcv/blob/master/jcv-core/src/main/kotlin/com/ekino/oss/jcv/core/initializer/DateTimeFormatComparatorInitializer.kt"
    click CV "https://github.com/ekino/jcv/blob/master/jcv-core/src/main/kotlin/com/ekino/oss/jcv/core/validator/DefaultJsonValidator.kt"
    click JC "https://github.com/ekino/jcv/blob/master/jcv-core/src/main/java/com/ekino/oss/jcv/core/JsonContextMatcher.java"

    %% Click Events for Integration Modules
    click IA "https://github.com/ekino/jcv/blob/master/jcv-assertj/src/main/kotlin/com/ekino/oss/jcv/assertion/assertj/JsonCompareAssert.kt"
    click IH "https://github.com/ekino/jcv/blob/master/jcv-hamcrest/src/main/kotlin/com/ekino/oss/jcv/assertion/hamcrest/JsonCompareMatcher.kt"
    click IW "https://github.com/ekino/jcv/blob/master/jcv-wiremock/src/main/kotlin/com/ekino/oss/jcv/assertion/wiremock/JcvRequestMatcherExtension.kt"

    %% Click Events for Test Harness
    click TC "https://github.com/ekino/jcv/tree/master/jcv-core/src/test"
    click TA "https://github.com/ekino/jcv/tree/master/jcv-assertj/src/test"
    click TH "https://github.com/ekino/jcv/tree/master/jcv-hamcrest/src/test"
    click TW "https://github.com/ekino/jcv/tree/master/jcv-wiremock/src/test/kotlin/com/ekino/oss/jcv/assertion/wiremock/"

    %% Styles
    classDef build fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef integration fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef external fill:#FFCCCB,stroke:#000,stroke-width:2px;
    classDef test fill:#D3D3D3,stroke:#000,stroke-width:2px;

    class BS1,BS2,BS3 build;
    class CC,CP,CI,CV,JC core;
    class IA,IH,IW integration;
    class EX external;
    class TC,TA,TH,TW test;
```
