# fasterxml/jackson-core architecture

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

- Interactive diagram: https://gitdiagram.com/fasterxml/jackson-core
- Repository: https://github.com/fasterxml/jackson-core

## Overview

##### Project type and purpose
- This is an open‑source Java library (“jackson‑core”) providing low‑level streaming abstractions for parsing and generating data (JSON by default, but extensible to other formats).
- It defines core interfaces (JsonFactory, JsonParser, JsonGenerator, TokenStreamFactory, ObjectCodec, TreeCodec) and default JSON implementations, on which higher‑level data binding (jackson‑databind) and alternative format modules (Smile, XML, CSV, YAML, Protobuf, CBOR) build.

##### File structure
- Top‑level build/config scripts: pom.xml, mvnw(.cmd), release scripts, GitHub Actions workflows.
- src/main/java/com/fasterxml/jackson/core: core API and abstractions (Factory, Parser/Generator base classes, IO, filtering, format detection, utilities, versioning).
- src/main/java/com/fasterxml/jackson/core/json and json/async: default JSON parser/generator implementations and non‑blocking I/O.
- src/main/resources/META‑INF/services: ServiceLoader entry point for pluggable JsonFactory.
- moditect and site: JPMS module descriptor and documentation site config.
- docs: packaged Javadoc for multiple versions.
- src/test: extensive unit and fuzz tests covering every package.

##### README for additional insights
- Core abstraction vs JSON‑specific separation.
- No runtime dependencies (JUnit only for testing).
- Usage pattern: clients obtain a reusable JsonFactory (builder pattern), then create JsonParser/JsonGenerator.
- Extensibility via ServiceLoader for alternate formats.

##### Main components and relationships (to appear
a. Client Layer
– Application code or jackson‑databind’s ObjectMapper calls JsonFactory (builder) → JsonParser/JsonGenerator.
b. Core Abstractions Module
– TokenStreamFactory, JsonFactory, JsonFactoryBuilder, JsonParser/JsonGenerator interfaces, ObjectCodec, TreeCodec, JsonStreamContext, JsonToken.
– StreamReadFeature/StreamWriteFeature, FormatFeature, StreamReadConstraints/StreamWriteConstraints, ErrorReportConfiguration.
c. JSON Implementation Module
– JSON‑specific parser/generator: ByteSourceJsonBootstrapper, ReaderBasedJsonParser, UTF8JsonGenerator, JsonGeneratorImpl, NonBlockingUtf8JsonParser, FilteringParserDelegate/FilteringGeneratorDelegate.
d. I/O & Utility Module
– IOContext, InputDecorator/OutputDecorator, ByteArrayFeeder/ByteBufferFeeder, BufferRecycler, TextBuffer, DataOutputAsStream, JsonStringEncoder.
e. Extensibility/Plugin Points
– META‑INF/services entry for JsonFactory, DataFormatDetector/DataFormatMatcher for autodetecting format.
– Other format modules implement the same interfaces and register via ServiceLoader.
f. Test & Fuzzing Suite (optional to show as separate module)

##### Architectural patterns and design principles
- Factory & Builder patterns: JsonFactoryBuilder → JsonFactory → Parser/Generator.
- Decorator pattern: InputDecorator/OutputDecorator wraps raw inputs/outputs.
- Delegation pattern: FilteringParserDelegate, FilteringGeneratorDelegate extend core parser/generator behavior.
- Strategy/ServiceLoader: pluggable JsonFactory implementations for various formats.
- Modular layering: core abstractions <— JSON implementation <— format‑specific modules <— data binding.

##### Elements
- Module/Package clusters with clear labels.
- Notes on patterns (e.g., “Factory”), and ServiceLoader for plugin discovery.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client/DataBinding Layer"
        Client["Application / ObjectMapper"]:::client
    end

    %% Core Abstractions Module
    subgraph "Core Abstractions Module"
        JsonFactoryBuilder["JsonFactoryBuilder"]:::core
        JsonFactory["JsonFactory"]:::core
        JsonParser["JsonParser"]:::core
        JsonGenerator["JsonGenerator"]:::core
    end

    %% JSON Implementation Module
    subgraph "JSON Implementation Module"
        ByteBootstrap["ByteSourceJsonBootstrapper"]:::impl
        ReaderParser["ReaderBasedJsonParser"]:::impl
        UTF8Gen["UTF8JsonGenerator"]:::impl
        NonBlocParser["NonBlockingJsonParser"]:::impl
        FilterParser["FilteringParserDelegate"]:::impl
    end

    %% I/O & Utilities Module
    subgraph "I/O & Utilities Module"
        IOContext["IOContext"]:::io
        ByteFeeder["ByteArrayFeeder"]:::io
        BufferRec["BufferRecycler"]:::io
    end

    %% Extensibility / Plugin Points
    subgraph "Extensibility / Plugin Points"
        FormatDetector["DataFormatDetector"]:::plugin
        ServiceLoader["ServiceLoader (META-INF)"]:::plugin
    end

    %% Test & Fuzz Suite
    subgraph "Test & Fuzz Suite"
        Tests["Unit & Fuzz Tests"]:::test
    end

    %% Connections
    Client -->|"1: configure factory"| JsonFactoryBuilder
    JsonFactoryBuilder -->|"build"| JsonFactory
    JsonFactory -->|"2: create parser"| JsonParser
    JsonFactory -->|"2: create generator"| JsonGenerator
    JsonParser -->|"uses bootstrap"| ByteBootstrap
    JsonParser -->|"reads stream"| ReaderParser
    JsonGenerator -->|"writes output"| UTF8Gen
    JsonParser -->|"non-blocking"| NonBlocParser
    JsonParser -->|"filtering"| FilterParser
    IOContext -->|"decorates"| JsonParser
    IOContext -->|"decorates"| JsonGenerator
    ByteFeeder -->|"feeds data to"| NonBlocParser
    BufferRec -->|"recycles buffers for"| IOContext
    FormatDetector -->|"autodetects format for"| JsonFactory
    ServiceLoader -->|"discovers implementations for"| JsonFactory
    Tests -->|"tests modules"| JsonFactoryBuilder
    Tests --> JsonParser
    Tests --> ByteBootstrap
    Tests --> IOContext

    %% Click Events
    click JsonFactoryBuilder "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/JsonFactoryBuilder.java"
    click JsonFactory "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/JsonFactory.java"
    click JsonParser "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/JsonParser.java"
    click JsonGenerator "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/JsonGenerator.java"
    click ByteBootstrap "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/json/ByteSourceJsonBootstrapper.java"
    click ReaderParser "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/json/ReaderBasedJsonParser.java"
    click UTF8Gen "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/json/UTF8JsonGenerator.java"
    click NonBlocParser "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/json/async/NonBlockingJsonParser.java"
    click FilterParser "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/filter/FilteringParserDelegate.java"
    click IOContext "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/io/IOContext.java"
    click ByteFeeder "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/async/ByteArrayFeeder.java"
    click BufferRec "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/util/BufferRecycler.java"
    click FormatDetector "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/java/com/fasterxml/jackson/core/format/DataFormatDetector.java"
    click ServiceLoader "https://github.com/fasterxml/jackson-core/blob/2.19/src/main/resources/META-INF/services/com.fasterxml.jackson.core.JsonFactory"

    %% Styles
    classDef client fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef impl fill:#d9d9f5,stroke:#333,stroke-width:1px
    classDef io fill:#e6f7ff,stroke:#333,stroke-width:1px
    classDef plugin fill:#fff2cc,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef test fill:#f2f2f2,stroke:#999,stroke-dasharray: 5 5,stroke-width:1px
```
