# michalmuskala/jason architecture

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

- Interactive diagram: https://gitdiagram.com/michalmuskala/jason
- Repository: https://github.com/michalmuskala/jason

## Overview

##### Main Components
- Core Library (lib/): This includes the key modules:
- jason.ex: Acts as the entry point wrapping and coordinating the JSON parsing and generation.
- decoder.ex and encoder.ex: Contain the logic for parsing (decoding) JSON text into Elixir data structures and generating (encoding) JSON strings.
- formatter.ex: Manages pretty-printing and custom-formatting for output.
- fragment.ex: Provides support for injecting already encoded JSON fragments.
- Additional modules (codegen.ex, helpers.ex, ordered_object.ex, sigil.ex) supply supplementary functionalities such as utility functions, custom structures, and possibly compile-time code generation.

- Testing and Quality Assurance:
- test/ directory: Contains unit tests for validating encoding, decoding, formatting, and additional helper functions.
- formatter_test_suite and json_test_suite: These directories hold sample JSON cases (both correct and edge cases) to test the strict compliance with JSON standards.

- Benchmarking:
- bench/ directory: Contains benchmark scripts (encode.exs, decode.exs) and dataset files (e.g., giphy.json, pokedex.json, blockchain.json, etc.), which are used to run performance tests and generate reports.

##### Relationships and Dependencies
- The central Jason module coordinates the work and delegates to the specific encoder/decoder modules.
- The encoder and decoder modules interface with helper modules to process JSON formatting, error detection, and conformance with RFC 8259 and ECMA 404.
- Formatter is a bridge between encoder output and producing a readable JSON representation when pretty-printing is enabled.
- The fragment module is used within the generator chain to allow the injection of pre-encoded JSON without re-processing it.
- Testing and benchmarks are separate concerns that depend on the core modules but are executed in isolated environments (unit tests and performance runs).

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each module has a specific purpose (parsing versus formatting versus fragment handling), keeping the code modular and extendable.
- Protocol Implementation: The library leverages Elixir protocols (as indicated in the README for encoding custom data types) to allow extensibility in JSON encoding.
- Test-Driven Approach: With dedicated suites and benchmarks, the design ensures strict conformance to JSON standards as well as high-performance goals.
- Reusability: The core functionality is exposed as a library that can be integrated into other systems (e.g., Ecto, Plug) without modification.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library"
        J["Jason (Main Entry)"]:::core
        D["JSON Decoder"]:::core
        E["JSON Encoder"]:::core
        F["Formatter (Pretty-printing)"]:::core
        R["JSON Fragment Handler"]:::core
        C["Code Generation"]:::core
        H["Helpers Utilities"]:::core
        O["Ordered Object"]:::core
        S["Sigil (Custom Literal)"]:::core
    end

    %% Testing and Benchmarking
    subgraph "Testing and Benchmarking"
        U["Unit Tests"]:::test
        FT["Formatter Test Suite"]:::test
        JT["JSON Test Suite"]:::test
        B["Benchmarking Suite"]:::bench
    end

    %% Core Modules Relationships
    J -->|"to_encode"| E
    J -->|"to_decode"| D
    E -->|"formats"| F
    E -->|"injects"| R
    E -->|"uses"| H
    D -->|"uses"| H
    H -->|"aids"| C
    E -->|"supports_order"| O
    J -->|"handles_custom"| S

    %% Testing/Benchmarking Relationships
    U ---|"tests_main"| J
    U ---|"tests_encoder"| E
    U ---|"tests_decoder"| D
    U ---|"tests_formatter"| F
    U ---|"tests_helpers"| H
    U ---|"tests_ordered"| O
    U ---|"tests_sigil"| S

    FT ---|"validates_format"| F
    JT ---|"validates_compliance"| J
    B ---|"benchmarks_encoder"| E
    B ---|"benchmarks_decoder"| D

    %% Click Events for Core Library Components
    click J "https://github.com/michalmuskala/jason/blob/master/lib/jason.ex"
    click D "https://github.com/michalmuskala/jason/blob/master/lib/decoder.ex"
    click E "https://github.com/michalmuskala/jason/blob/master/lib/encoder.ex"
    click F "https://github.com/michalmuskala/jason/blob/master/lib/formatter.ex"
    click R "https://github.com/michalmuskala/jason/blob/master/lib/fragment.ex"
    click C "https://github.com/michalmuskala/jason/blob/master/lib/codegen.ex"
    click H "https://github.com/michalmuskala/jason/blob/master/lib/helpers.ex"
    click O "https://github.com/michalmuskala/jason/blob/master/lib/ordered_object.ex"
    click S "https://github.com/michalmuskala/jason/blob/master/lib/sigil.ex"

    %% Click Events for Testing and Benchmarking Components
    click U "https://github.com/michalmuskala/jason/tree/master/test/"
    click FT "https://github.com/michalmuskala/jason/tree/master/formatter_test_suite"
    click JT "https://github.com/michalmuskala/jason/tree/master/json_test_suite"
    click B "https://github.com/michalmuskala/jason/tree/master/bench"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef test fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef bench fill:#fff3cd,stroke:#333,stroke-width:2px;
```
