# upstart-commerce/diffson architecture

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

- Interactive diagram: https://gitdiagram.com/upstart-commerce/diffson
- Repository: https://github.com/upstart-commerce/diffson

## Overview

##### Project Type and Purpose
- This is a Scala multi-module library (not a full-stack app) whose purpose is to compute JSON diffs and apply JSON patches/merge patches according to RFC-6901, RFC-6902, and RFC-7396.
- It exposes a core diff/patch engine plus “adapter” modules for popular JSON libraries (Circe, Play-JSON, Spray-JSON) and a testkit for conformance tests.

##### Top-Level Module Structure
- /core: the heart of the library, implements `Diff`, `Patch`, `Jsony` type class, LCS and merge-patch logic, no JSON-library dependencies.
- /circe, /playJson, /sprayJson: each has jvm & shared subprojects. They provide instances of `Jsony` and codecs (`Encoder`/`Decoder` or `Format`) for their respective JSON library.
- /testkit: jvm & shared subprojects containing conformance tests against the RFC specs, resource files, and test harnesses.
- project/, build.sbt, plugins.sbt, build.properties: SBT multi-project build configuration.
- .github, .travis.yml, LICENSE, README.markdown: CI, contributor guides, documentation.

##### Main Components
- Core module (diffson-core)
- Adapter modules: diffson-circe, diffson-playJson, diffson-sprayJson
- Testkit modules
- External dependencies: cats (for MonadError), the three JSON libraries (Circe, Play-JSON, Spray-JSON)
- Build system (SBT)

##### Relationships and Data Flows
- External libraries feed into adapters (e.g. Circe → diffson-circe).
- The build system orchestrates compilation of all subprojects.

##### Architectural Patterns and Principles
- Modular layering: core is JSON-library-agnostic; adapters inject type-class instances.
- Type-class-based extensibility: new JSON libraries can be supported by providing a `Jsony` instance.
- Separation of concerns: computation logic vs serialization logic vs testing.
- SBT multi-project structure for clean module boundaries.

##### Essential Elements
- Annotation of key classes in core (e.g. `Diff`, `Patch`, `Jsony`) and in adapters (`DiffsonProtocol`, codecs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Module
    subgraph "Core Module"
        CORE["diffson-core"]:::core
    end

    %% Adapter Modules
    subgraph "Adapter Modules"
        subgraph "Circe Adapter"
            CIRCE_SHARED["diffson-circe-shared"]:::adapter
            CIRCE_JVM["diffson-circe-jvm"]:::adapter
        end
        subgraph "Play-JSON Adapter"
            PLAY_SHARED["diffson-playJson-shared"]:::adapter
            PLAY_JVM["diffson-playJson-jvm"]:::adapter
        end
        subgraph "Spray Adapter"
            SPRAY["diffson-sprayJson"]:::adapter
        end
    end

    %% Testkit Modules
    subgraph "Testkit Modules"
        TK_SHARED["diffson-testkit-shared"]:::testkit
        TK_JVM["diffson-testkit-jvm"]:::testkit
    end

    %% External Libraries
    subgraph "External Libraries"
        CATS["cats"]:::external
        CIRCE_LIB["Circe"]:::external
        PLAY_LIB["Play-JSON"]:::external
        SPRAY_LIB["Spray-JSON"]:::external
    end

    %% Build System & CI
    subgraph "Build & CI"
        SBT["SBT Build"]:::build
        CI[".travis.yml / .github"]:::build
    end

    %% Dependencies
    CIRCE_SHARED -->|depends on| CORE
    CIRCE_JVM -->|depends on| CORE
    PLAY_SHARED -->|depends on| CORE
    PLAY_JVM -->|depends on| CORE
    SPRAY -->|depends on| CORE

    TK_SHARED -->|tests| CORE
    TK_SHARED -->|tests| CIRCE_SHARED
    TK_SHARED -->|tests| PLAY_SHARED
    TK_SHARED -->|tests| SPRAY
    TK_JVM -->|tests| CORE
    TK_JVM -->|tests| CIRCE_SHARED
    TK_JVM -->|tests| PLAY_SHARED
    TK_JVM -->|tests| SPRAY

    CATS -->|provides MonadError| CORE
    CATS -->|provides MonadError| CIRCE_SHARED
    CATS -->|provides MonadError| PLAY_SHARED
    CATS -->|provides MonadError| SPRAY

    CIRCE_LIB -->|JSON library| CIRCE_SHARED
    PLAY_LIB -->|JSON library| PLAY_SHARED
    SPRAY_LIB -->|JSON library| SPRAY

    SBT -->|orchestrates| CORE
    SBT -->|orchestrates| CIRCE_SHARED
    SBT -->|orchestrates| CIRCE_JVM
    SBT -->|orchestrates| PLAY_SHARED
    SBT -->|orchestrates| PLAY_JVM
    SBT -->|orchestrates| SPRAY
    SBT -->|orchestrates| TK_SHARED
    SBT -->|orchestrates| TK_JVM
    CI -->|runs| SBT

    %% Click Events
    click CORE "https://github.com/upstart-commerce/diffson/tree/master/core/src/main/scala/diffson"
    click CIRCE_JVM "https://github.com/upstart-commerce/diffson/blob/master/circe/jvm/src/test/scala/diffson/conformance/CirceConformance.scala"
    click CIRCE_SHARED "https://github.com/upstart-commerce/diffson/blob/master/circe/shared/src/main/scala/diffson/circe/package.scala"
    click PLAY_JVM "https://github.com/upstart-commerce/diffson/blob/master/playJson/jvm/src/test/scala/diffson/playJson/conformance/PlayJsonConformance.scala"
    click PLAY_SHARED "https://github.com/upstart-commerce/diffson/blob/master/playJson/shared/src/main/scala/diffson/playJson/DiffsonProtocol.scala"
    click SPRAY "https://github.com/upstart-commerce/diffson/blob/master/sprayJson/src/main/scala/gnieh/diffson/sprayJson/DiffsonProtocol.scala"
    click SPRAY "https://github.com/upstart-commerce/diffson/blob/master/sprayJson/src/test/scala/diffson/sprayJson/conformance/SprayJsonConformance.scala"
    click TK_JVM "https://github.com/upstart-commerce/diffson/blob/master/testkit/jvm/src/main/scala/diffson/conformance/TestRfcConformance.scala"
    click TK_SHARED "https://github.com/upstart-commerce/diffson/blob/master/testkit/shared/src/main/scala/diffson/TestProtocol.scala"
    click SBT "https://github.com/upstart-commerce/diffson/blob/master/build.sbt"
    click CI "https://github.com/upstart-commerce/diffson/blob/master/.travis.yml"

    %% Styles
    classDef core fill:#ffefd5,stroke:#d2691e,stroke-width:2px;
    classDef adapter fill:#e0ffff,stroke:#20b2aa,stroke-width:2px;
    classDef testkit fill:#fff0f5,stroke:#db7093,stroke-width:2px;
    classDef external fill:#f0fff0,stroke:#32cd32,stroke-width:2px;
    classDef build fill:#f5f5f5,stroke:#808080,stroke-width:2px;
```
