# stretchr/objx architecture

> Architecture diagram of the GitHub repository stretchr/objx, 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/stretchr/objx
- Repository: https://github.com/stretchr/objx

## Overview

##### Project type and purpose
- Objx is an open-source Go package (“library”) for working with map[string]interface{}) and JSON.
- It provides a core Map/Value API, various convenience methods (Get, Is*, Int, Str, etc.), plus a code-generation subsystem to produce type-specific accessor code.

##### File structure
- Top-level Go files:
– accessors.go, conversions.go, map.go, mutations.go, security.go, value.go – these implement the core API layers.
– type_specific.go, type_specific_codegen.go – code that drives per-type generation.
– codegen/ – templates and test fixtures used to generate additional code.
- Other files: Taskfile.yml (automation), .github/workflows/go.yml (CI), README.md, tests.go (test helpers), go.mod/go.sum (module info).

##### README for additional insights
- Core functionality (“objx.Map”, “Get”, default values, dot/array notation).
- Mentions JSON ingestion (“FromJSON”), type assertions, iteration.

##### Main components and interactions
a. Core API Layer
– Package “objx” exposing Map and Value types
– Functions: FromJSON/MustFromJSON, Get, iteration, type-assertion helpers
b. Conversion Layer
– conversions.go provides type conversions and defaults
– value.go wraps raw interface{} values under Value type
c. Mutation & Accessor Layer
– accessors.go / mutations.go implement setter/mutator methods (Append, Set, etc.)
d. Security/Sanitization Layer
– security.go ensures safe handling of untrusted data
e. Codegen Subsystem
– codegen/ folder with template.txt, array-access.txt, types_list.txt
– type_specific_codegen.go reads templates, emits type-specific code (via go generate or Taskfile)
f. Test Suite
– *_test.go files validate each component, plus end-to-end simple_example_test.go

##### Architectural patterns & design principles
- Modular layering: API → conversion → security → codegen → tests
- Separation of concerns: codegen isolates template logic from core runtime
- Extensibility: new types added by updating templates and types_list.txt
- Automation: Taskfile and go generate workflows

##### Essential elements
- Clear labels on all components (e.g., “objx.Map API”, “conversions.go”, “codegen/template.txt”).
- Go module boundary (go.mod) as the outer frame.

## Diagram (Mermaid)

```mermaid
flowchart TD
    ExternalApp["External Application\n(go get & use objx)"]:::external

    subgraph "Go Module Boundary"
        subgraph "Runtime Packages"
            subgraph "Core API Layer" 
                Map["map.go"]:::runtime
                Value["value.go"]:::runtime
                Doc["doc.go"]:::runtime
            end
            subgraph "Conversion Layer"
                Conv["conversions.go"]:::runtime
            end
            subgraph "Mutation & Accessor Layer"
                Accessors["accessors.go"]:::runtime
                Mutations["mutations.go"]:::runtime
            end
            subgraph "Security/Sanitization Layer"
                Sec["security.go"]:::runtime
            end
        end

        subgraph "Code Generation Subsystem"
            TypeSpec["type_specific.go"]:::codegen
            CodeGen["type_specific_codegen.go"]:::codegen
            subgraph "Templates"
                ArrayTemp["codegen/array-access.txt"]:::codegen
                Temp["codegen/template.txt"]:::codegen
                TempTest["codegen/template_test.txt"]:::codegen
                TypesList["codegen/types_list.txt"]:::codegen
            end
        end

        subgraph "Test Suite" 
            direction TB
            AT["accessors_test.go"]:::test
            CT["conversions_test.go"]:::test
            MT["map_test.go"]:::test
            MutT["mutations_test.go"]:::test
            ST["security_test.go"]:::test
            SET["simple_example_test.go"]:::test
            TST["type_specific_test.go"]:::test
            CGT["type_specific_codegen_test.go"]:::test
            VT["value_test.go"]:::test
            FT["fixture_test.go"]:::test
            TH["tests.go"]:::test
            TT["tests_test.go"]:::test
        end

        subgraph "Infrastructure & Automation"
            TF["Taskfile.yml"]:::infra
            CI[".github/workflows/go.yml"]:::infra
            GM["go.mod"]:::infra
            GS["go.sum"]:::infra
        end
    end

    ExternalApp -->|"uses API"| Map
    Map -->|"calls"| Conv
    Conv -->|"sanitizes via"| Sec
    Map -->|"mutates via"| Accessors
    Accessors -->|"uses"| Mutations
    CodeGen -->|"generates code into"| Map
    Temp -->|"template processing"| CodeGen
    ArrayTemp -->|"template processing"| CodeGen
    TempTest -->|"test fixture for"| CodeGen
    TypesList -->|"type definitions for"| TypeSpec
    TypeSpec -->|"drives generation"| CodeGen
    TF -->|"triggers"| CodeGen
    CI -->|"runs tests & build"| AT
    CI -->|"runs tests & build"| CT
    CI -->|"runs tests & build"| MT
    CI -->|"runs tests & build"| MutT
    CI -->|"runs tests & build"| ST
    CI -->|"runs tests & build"| SET
    CI -->|"runs tests & build"| TST
    CI -->|"runs tests & build"| CGT
    CI -->|"runs tests & build"| VT
    CI -->|"runs tests & build"| FT
    CI -->|"runs tests & build"| TH
    CI -->|"runs tests & build"| TT

    click Map "https://github.com/stretchr/objx/blob/master/map.go"
    click Value "https://github.com/stretchr/objx/blob/master/value.go"
    click Doc "https://github.com/stretchr/objx/blob/master/doc.go"
    click Conv "https://github.com/stretchr/objx/blob/master/conversions.go"
    click Accessors "https://github.com/stretchr/objx/blob/master/accessors.go"
    click Mutations "https://github.com/stretchr/objx/blob/master/mutations.go"
    click Sec "https://github.com/stretchr/objx/blob/master/security.go"
    click TypeSpec "https://github.com/stretchr/objx/blob/master/type_specific.go"
    click CodeGen "https://github.com/stretchr/objx/blob/master/type_specific_codegen.go"
    click ArrayTemp "https://github.com/stretchr/objx/blob/master/codegen/array-access.txt"
    click Temp "https://github.com/stretchr/objx/blob/master/codegen/template.txt"
    click TempTest "https://github.com/stretchr/objx/blob/master/codegen/template_test.txt"
    click TypesList "https://github.com/stretchr/objx/blob/master/codegen/types_list.txt"
    click AT "https://github.com/stretchr/objx/blob/master/accessors_test.go"
    click CT "https://github.com/stretchr/objx/blob/master/conversions_test.go"
    click MT "https://github.com/stretchr/objx/blob/master/map_test.go"
    click MutT "https://github.com/stretchr/objx/blob/master/mutations_test.go"
    click ST "https://github.com/stretchr/objx/blob/master/security_test.go"
    click SET "https://github.com/stretchr/objx/blob/master/simple_example_test.go"
    click TST "https://github.com/stretchr/objx/blob/master/type_specific_test.go"
    click CGT "https://github.com/stretchr/objx/blob/master/type_specific_codegen_test.go"
    click VT "https://github.com/stretchr/objx/blob/master/value_test.go"
    click FT "https://github.com/stretchr/objx/blob/master/fixture_test.go"
    click TH "https://github.com/stretchr/objx/blob/master/tests.go"
    click TT "https://github.com/stretchr/objx/blob/master/tests_test.go"
    click TF "https://github.com/stretchr/objx/blob/master/Taskfile.yml"
    click CI "https://github.com/stretchr/objx/blob/master/.github/workflows/go.yml"
    click GM "https://github.com/stretchr/objx/blob/master/go.mod"
    click GS "https://github.com/stretchr/objx/blob/master/go.sum"

    classDef runtime fill:#b3cde3,stroke:#005b96,color:#03396c
    classDef codegen fill:#c7e9c0,stroke:#228B22,color:#006400
    classDef infra fill:#d9d9d9,stroke:#666,color:#333
    classDef test fill:#ffffff,stroke-dasharray: 5 5,stroke:#999,color:#000
    classDef external fill:#fdd0a2,stroke:#e6550d,color:#a63603
```
