How upstart-commerce/diffson works
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).