# discord4j/discord-json architecture

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

- Interactive diagram: https://gitdiagram.com/discord4j/discord-json
- Repository: https://github.com/discord4j/discord-json

## Overview

##### Project type and purpose
- This is an open-source, multi-module Java library (“discord-json”) that defines immutable Jackson-annotated domain objects representing Discord’s REST and Gateway JSON schemas.
- It’s published to Maven Central, built with Gradle under JDK 11, and provides two supplementary modules (“api” and “encoding”) in addition to the core JSON model definitions.

##### File structure
- Top level: build scripts (build.gradle, settings.gradle), root Gradle wrapper, CI configuration (jitpack.yml, .github/workflows/gradle.yml), license, README.
- Modules:
- core (implicit root module under src/main/java/discord4j/discordjson/json and json/gateway) – defines all JSON data classes.
- api – an independent Gradle subproject exposing Jackson modules and interfaces for downstream consumers (discord4j.discordjson.possible packages).
- encoding – another subproject providing Jackson encoders/decoders (discordjson.encoding packages) for ID and “possible” types.
- Tests for each module under src/test/java and resources under src/test/resources.
- Configuration: logback.xml, Gradle properties, .editorconfig, .gitignore.

##### README for additional insights
- Describes the library’s goal: “Discord entity domain now available as immutable Jackson objects.”
- Mentions dependencies: Immutables, Jackson Databind, JDK 11.

a. Main components:
- Gradle Build System (root)
- Core JSON Model Module (“core”)
- API Module (“api”)
- Encoding Module (“encoding”)
- External Dependencies: Jackson Databind, Immutables, JDK libraries
- Test Harness (unit tests + test resources)
- Consumers (Discord4J library, third-party applications)
b. Relationships and interactions:
- Build System orchestrates compilation of all modules and runs tests.
- core defines immutable data classes; api and encoding declare dependencies on core.
- api provides Jackson modules to plug domain types into Jackson’s ObjectMapper.
- encoding supplies custom serializers/deserializers plugged into Jackson.
- Consumers import the published JARs (core, api, encoding) via Maven Central.
c. Architectural patterns and design principles:
- Modularization – clear separation of model, API, encoding logic.
- Layered abstraction – core data → API integration layer → encoding/serialization layer.
- Convention-based packaging for JSON schema and gateway events.
d. Key technologies and libraries:
- Build: Gradle, JDK 11, Gradle Wrapper
- JSON mapping: Jackson Databind, custom Jackson Modules
- Immutables (for generating immutable value objects)
- Testing: JUnit, JSON fixtures under test/resources

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    subgraph "Build System"
        Build["Gradle Build System"]:::build
    end

    %% Core Module
    subgraph "Core JSON Model Module"
        Domain["REST Schema Classes"]:::internal
        Gateway["Gateway Schema Classes"]:::internal
        CoreTests["Core Module Tests"]:::test
        RestResources["REST Test Resources"]:::test
        GatewayResources["Gateway Test Resources"]:::test
    end

    %% API Module
    subgraph "API Module"
        Possible["Possible Interfaces & Module"]:::internal
        IdAbstraction["ID Abstraction"]:::internal
        Experimental["Experimental Annotation"]:::internal
    end

    %% Encoding Module
    subgraph "Encoding Module"
        IdEncoding["ID Encodings"]:::internal
        PossibleEncoding["Possible Type Encodings"]:::internal
        EncTests1["SpecGeneratorTest.java"]:::test
        EncTests2["MessageCreateSpecGenerator.java"]:::test
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Jackson["Jackson Databind"]:::external
        Immutables["Immutables"]:::external
        JDK["JDK Libraries (JDK 11)"]:::external
    end

    %% Test Harness Fixtures
    subgraph "Test Harness Fixtures"
        FixturesREST["REST JSON Fixtures"]:::test
        FixturesGW["Gateway JSON Fixtures"]:::test
        CommonLogback["Common logback.xml"]:::test
    end

    %% CI Configuration
    subgraph "CI Configuration"
        GitHub["GitHub Actions"]:::ci
        Jitpack["JitPack Config"]:::ci
    end

    %% Consumers
    Consumers["Consumers\n(Discord4J, 3rd-party)"]:::consumer

    %% Connections - Build orchestration
    Build --> CoreTests
    Build --> EncTests1
    Build --> EncTests2
    Build --> Domain
    Build --> Gateway
    Build --> Possible
    Build --> IdAbstraction
    Build --> Experimental
    Build --> IdEncoding
    Build --> PossibleEncoding

    %% Module dependencies
    Domain --> Possible
    Domain --> IdEncoding
    Domain --> PossibleEncoding
    Gateway --> Possible
    Gateway --> IdEncoding
    Gateway --> PossibleEncoding

    %% API & Encoding integrate with external libs
    Possible --> Jackson
    Possible --> Immutables
    IdAbstraction --> Jackson
    Experimental --> Jackson
    IdEncoding --> Jackson
    PossibleEncoding --> Jackson

    %% Testing dependencies
    CoreTests --> Domain
    CoreTests --> RestResources
    CoreTests --> GatewayResources
    EncTests1 --> IdEncoding
    EncTests1 --> PossibleEncoding
    EncTests2 --> IdEncoding
    EncTests2 --> PossibleEncoding
    FixturesREST --> CoreTests
    FixturesGW --> CoreTests
    FixturesREST --> EncTests1
    FixturesGW --> EncTests1

    %% CI
    GitHub --> Build
    Jitpack --> Build

    %% Consumers import published artifacts
    Consumers --> Possible
    Consumers --> IdEncoding
    Consumers --> Domain

    %% Click Events
    click Build "https://github.com/discord4j/discord-json/blob/master//build.gradle"
    click Domain "https://github.com/discord4j/discord-json/tree/master//src/main/java/discord4j/discordjson/json"
    click Gateway "https://github.com/discord4j/discord-json/tree/master//src/main/java/discord4j/discordjson/json/gateway"
    click CoreTests "https://github.com/discord4j/discord-json/blob/master//src/test/java/discord4j/discordjson/DataMappingTest.java"
    click RestResources "https://github.com/discord4j/discord-json/tree/master//src/test/resources/rest"
    click GatewayResources "https://github.com/discord4j/discord-json/tree/master//src/test/resources/gateway"
    click Possible "https://github.com/discord4j/discord-json/tree/master//api/src/main/java/discord4j/discordjson/possible"
    click IdAbstraction "https://github.com/discord4j/discord-json/blob/master//api/src/main/java/discord4j/discordjson/Id.java"
    click Experimental "https://github.com/discord4j/discord-json/blob/master//api/src/main/java/discord4j/discordjson/annotation/Experimental.java"
    click IdEncoding "https://github.com/discord4j/discord-json/tree/master//encoding/src/main/java/discord4j/discordjson/encoding"
    click PossibleEncoding "https://github.com/discord4j/discord-json/tree/master//encoding/src/main/java/discord4j/discordjson/encoding/possible"
    click EncTests1 "https://github.com/discord4j/discord-json/blob/master//src/test/java/discord4j/discordjson/encoding/SpecGeneratorTest.java"
    click EncTests2 "https://github.com/discord4j/discord-json/blob/master//src/test/java/discord4j/discordjson/encoding/MessageCreateSpecGenerator.java"
    click GitHub "https://github.com/discord4j/discord-json/blob/master//.github/workflows/gradle.yml"
    click Jitpack "https://github.com/discord4j/discord-json/blob/master//jitpack.yml"

    %% Styles
    classDef build fill:#f9f,stroke:#333,stroke-width:1px;
    classDef internal fill:#bbf,stroke:#333,stroke-width:1px;
    classDef external fill:#e2e,stroke:#333,stroke-width:1px;
    classDef consumer fill:#bfb,stroke:#333,stroke-width:1px;
    classDef test fill:#ffb,stroke:#333,stroke-width:1px;
    classDef ci fill:#fc9,stroke:#333,stroke-width:1px;
```
