# mangiucugna/json_repair architecture

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

- Interactive diagram: https://gitdiagram.com/mangiucugna/json_repair
- Repository: https://github.com/mangiucugna/json_repair

## Overview

##### Project type and purpose
- This is a standalone, open-source Python library and CLI tool (“json_repair”) whose sole purpose is to take malformed JSON strings or streams, repair them using simple heuristics, and return either a valid JSON string or a native Python object.

##### File structure
- Top-level folders:
- src/json_repair: the core package
- docs: static demo site sources (HTML/JS/CSS)
- tests: unit tests and performance tests
- Key modules under src/json_repair:
- __main__.py – CLI entry point
- json_repair.py – public API (repair_json, loads, load, from_file)
- json_parser.py – low-level BNF-based parser and scanner
- json_context.py – parse state and token management
- object_comparer.py – logic to compare/merge default values
- string_file_wrapper.py – adapter for file/stream inputs
- Configuration/build:
- pyproject.toml + requirements.txt for packaging
- GitHub Actions workflows for test & publish
- pre-commit for linting/testing

##### README for additional insights
- No external runtime dependencies beyond the Python standard library (uses json.loads under the hood unless skipped)
- Demonstrates both library usage (API) and CLI usage
- Mentions performance-tuning flags (skip_json_loads, stream_stable) and non-Latin handling (ensure_ascii)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User["User / Caller"]:::external

    %% Adapters
    subgraph "Adapters"
        CLI_Adapter["CLI Adapter\n(__main__.py)"]:::adapter
        Input_Wrapper["Input Wrapper\n(string_file_wrapper.py)"]:::adapter
    end

    %% Core Domain
    subgraph "Core Domain"
        Core_Init["Package Init\n(__init__.py)"]:::core
        Type_Stubs["Type Stubs\n(py.typed)"]:::core
        API_Layer["API Layer\n(json_repair.py)"]:::core
        Parser["Parser Engine\n(json_parser.py)"]:::core
        Context["Parser Context\n(json_context.py)"]:::core
        Repair_Logic["Repair Logic\n(object_comparer.py)"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Stdlib_JSON["Python stdlib json"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Tests["Tests & Examples\ntests/"]:::infra
        CI_Test["CI Workflow: Test\n(.github/workflows/python-package.yml)"]:::infra
        CI_Publish["CI Workflow: Publish\n(.github/workflows/python-publish.yml)"]:::infra
        Docs_HTML["Docs HTML\n(docs/index.html)"]:::infra
        Docs_JS["Docs JS\n(docs/index.js)"]:::infra
        Docs_CSS["Docs CSS\n(docs/styles.css)"]:::infra
        Docs_APP["Docs App\n(docs/app.py)"]:::infra
        Packaging_TOML["Packaging Config\n(pyproject.toml)"]:::infra
        Packaging_REQ["Requirements\n(requirements.txt)"]:::infra
    end

    %% Data flows
    User -->|"invokes"| CLI_Adapter
    User -->|"direct API call"| API_Layer
    CLI_Adapter -->|"calls"| API_Layer
    API_Layer -->|"reads input"| Input_Wrapper
    Input_Wrapper -->|"provides tokens"| Parser
    Parser -->|"updates state"| Context
    Context -->|"feeds tokens"| Repair_Logic
    API_Layer -->|"flags: skip_json_loads,\nstream_stable"| Repair_Logic
    Repair_Logic -->|"delegates to"| Stdlib_JSON
    Stdlib_JSON -->|"returns JSON\nstring/object"| User

    %% Click events
    click CLI_Adapter "https://github.com/mangiucugna/json_repair/blob/main/src/json_repair/__main__.py"
    click API_Layer "https://github.com/mangiucugna/json_repair/blob/main/src/json_repair/json_repair.py"
    click Parser "https://github.com/mangiucugna/json_repair/blob/main/src/json_repair/json_parser.py"
    click Context "https://github.com/mangiucugna/json_repair/blob/main/src/json_repair/json_context.py"
    click Repair_Logic "https://github.com/mangiucugna/json_repair/blob/main/src/json_repair/object_comparer.py"
    click Input_Wrapper "https://github.com/mangiucugna/json_repair/blob/main/src/json_repair/string_file_wrapper.py"
    click Core_Init "https://github.com/mangiucugna/json_repair/blob/main/src/json_repair/__init__.py"
    click Type_Stubs "https://github.com/mangiucugna/json_repair/blob/main/src/json_repair/py.typed"
    click Tests "https://github.com/mangiucugna/json_repair/tree/main/tests/"
    click CI_Test "https://github.com/mangiucugna/json_repair/blob/main/.github/workflows/python-package.yml"
    click CI_Publish "https://github.com/mangiucugna/json_repair/blob/main/.github/workflows/python-publish.yml"
    click Docs_HTML "https://github.com/mangiucugna/json_repair/blob/main/docs/index.html"
    click Docs_JS "https://github.com/mangiucugna/json_repair/blob/main/docs/index.js"
    click Docs_CSS "https://github.com/mangiucugna/json_repair/blob/main/docs/styles.css"
    click Docs_APP "https://github.com/mangiucugna/json_repair/blob/main/docs/app.py"
    click Packaging_TOML "https://github.com/mangiucugna/json_repair/blob/main/pyproject.toml"
    click Packaging_REQ "https://github.com/mangiucugna/json_repair/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#add8e6,stroke:#000,stroke-width:1px
    classDef adapter fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#ffa500,stroke:#000,stroke-width:1px
    classDef infra fill:#d3d3d3,stroke:#000,stroke-width:1px
```
