# ibireme/yymodel architecture

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

- Interactive diagram: https://gitdiagram.com/ibireme/yymodel
- Repository: https://github.com/ibireme/yymodel

## Overview

##### Project type and purpose
- This is an open-source, high-performance Objective-C model-to-JSON (and back) conversion framework (YYModel), complete with an example Benchmark app and test suite.

##### File structure
- Top-level components:
– /YYModel: core source (NSObject+YYModel.*, YYClassInfo.*, YYModel.*)
– /Framework: Xcode framework project (YYModel.xcodeproj) for building the library
– /Benchmark: iOS app (ModelBenchmark.xcodeproj) that measures conversion performance
– /YYModelTests: XCTest cases verifying correctness and edge cases
– Podspec, Carthage & manual installation config files

##### README for insights
- Exposes a simple API:
– yy_modelWithJSON: JSON → Model
– yy_modelToJSONObject: Model → JSON
- Supports mapping, nested models, container generics, custom transforms, NSCoding/NSCopying/Hash/Equal/Description
- Relies on ObjC runtime reflection (YYClassInfo) and Foundation JSON parsing/serialization

##### Main components & their interactions

A. Clients / Integrators
- CocoaPods, Carthage, Manual import
- Your application code or Benchmark App
→ calls

B. YYModel Public API Layer
- Category on NSObject: yy_modelWithJSON:, yy_modelToJSONObject, yy_modelEncodeWithCoder, etc.
→ orchestrates

C. Core Conversion Engine
1. JSON Parser / Serializer (Foundation’s NSJSONSerialization)
2. Reflection Module (YYClassInfo)
3. Property Mapper (modelCustomPropertyMapper)
4. Container Class Resolver (modelContainerPropertyGenericClass)
5. Custom Transform Hooks (modelCustomTransformFromDictionary / ToDictionary)
→ uses

D. Model Objects
- User-defined classes (e.g. GitHubUser, FEWeiboModel, SwiftGithubUser)
- Populated via KVC / direct ivar access

E. Output
- NSDictionary / JSON data
- NSCoding archive, copy, hash, equality, description

F. Quality & Packaging
- Test Suite (YYModelTests) runs through all feature cases
- Benchmark App measures performance
- Podspec / Carthage support / .xcodeproj for framework

##### Architectural patterns & design principles
- Modular separation – Public API vs. Conversion Engine vs. Model classes
- Non-intrusive categories – no base class requirement
- Reflection-driven mapping – runtime introspection via YYClassInfo
- Hook points – custom mapping, transform, whitelist/blacklist
- Layered approach – parse JSON, map to model, apply transforms, serialize back

##### Essential architectural elements
- Separation of concerns: parsing vs. mapping vs. custom logic
- Extension points where users plug in custom behavior

– Clearly reflect YYModel’s modular architecture
– Illustrate the flow from JSON input through conversion engine to model objects and back
– Demonstrate external integration points (apps, tests, package managers)
– Highlight the runtime-reflection backbone and customization hooks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients & Integrators
    subgraph "Clients & Integrators"
        CocoaPods[(CocoaPods)]:::client
        Carthage[(Carthage)]:::client
        ManualImport[(Manual Import)]:::client
        BenchmarkApp["Benchmark App"]:::client
    end

    CocoaPods -->|"integrates via"| PublicAPI
    Carthage -->|"integrates via"| PublicAPI
    ManualImport -->|"integrates via"| PublicAPI
    BenchmarkApp -->|"calls"| PublicAPI

    %% Public API Layer
    PublicAPI["Public API\n(NSObject+YYModel)"]:::core

    click PublicAPI "https://github.com/ibireme/yymodel/blob/master/YYModel/NSObject+YYModel.h"
    click PublicAPI "https://github.com/ibireme/yymodel/blob/master/YYModel/NSObject+YYModel.m"

    %% Core Conversion Engine
    subgraph "Core Conversion Engine"
        CoreModel["Engine Entry\n(YYModel)"]:::core
        JSONParser[(NSJSONSerialization)]:::data
        Reflection["Reflection Engine\n(YYClassInfo)"]:::core
        Mapper["Property Mapper"]:::core
        Container["Container Class Resolver"]:::core
        Hooks{{"Custom Transform Hooks"}}:::core
    end

    PublicAPI -->|"orchestrates"| CoreModel
    CoreModel -->|"parses"| JSONParser
    JSONParser -->|"reflects via"| Reflection
    Reflection -->|"maps properties"| Mapper
    Mapper -->|"resolves generics"| Container
    Container -->|"applies custom hooks"| Hooks

    click CoreModel "https://github.com/ibireme/yymodel/blob/master/YYModel/YYModel.h"
    click Reflection "https://github.com/ibireme/yymodel/blob/master/YYModel/YYClassInfo.h"
    click Reflection "https://github.com/ibireme/yymodel/blob/master/YYModel/YYClassInfo.m"

    %% Model Classes
    subgraph "Model Classes"
        Model1["GitHubUser"]:::model
        Model2["FEWeiboModel"]:::model
        SwiftModel["SwiftGithubUser"]:::model
    end

    Mapper -->|"populates"| Model1
    Mapper -->|"populates"| Model2
    Mapper -->|"populates"| SwiftModel

    click Model1 "https://github.com/ibireme/yymodel/blob/master/Benchmark/ModelBenchmark/GithubUserModel/GitHubUser.h"
    click Model1 "https://github.com/ibireme/yymodel/blob/master/Benchmark/ModelBenchmark/GithubUserModel/GitHubUser.m"
    click SwiftModel "https://github.com/ibireme/yymodel/blob/master/Benchmark/ModelBenchmark/GithubUserModel/SwiftGithubUser.swift"
    click Model2 "https://github.com/ibireme/yymodel/blob/master/Benchmark/ModelBenchmark/WeiboModel/FEWeiboModel.h"
    click Model2 "https://github.com/ibireme/yymodel/blob/master/Benchmark/ModelBenchmark/WeiboModel/FEWeiboModel.m"

    %% Data Inputs/Outputs
    JSONInput[(JSON Input)]:::data
    NSDictionaryOutput[(NSDictionary / JSON Output)]:::data

    JSONInput -->|"feeds"| PublicAPI
    Hooks -->|"returns"| NSDictionaryOutput

    click JSONInput "https://github.com/ibireme/yymodel/blob/master/Benchmark/ModelBenchmark/GithubUserModel/user.json"
    click NSDictionaryOutput "https://github.com/ibireme/yymodel/blob/master/Benchmark/ModelBenchmark/WeiboModel/weibo.json"

    %% Quality & Packaging
    subgraph "Quality & Packaging"
        TestSuite["Test Suite"]:::client
        Podspec["Podspec"]:::pkg
        FrameworkProj["Framework Project"]:::pkg
        CI["CI Config"]:::pkg
    end

    PublicAPI -->|"validated by"| TestSuite
    PublicAPI -->|"measured by"| BenchmarkApp
    Podspec -->|"packages"| PublicAPI
    FrameworkProj -->|"builds"| PublicAPI

    click TestSuite "https://github.com/ibireme/yymodel/tree/master/YYModelTests/"
    click Podspec "https://github.com/ibireme/yymodel/blob/master/YYModel.podspec"
    click FrameworkProj "https://github.com/ibireme/yymodel/blob/master/Framework/YYModel.xcodeproj"
    click CI "https://github.com/ibireme/yymodel/blob/master/.travis.yml"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef model fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef client fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef pkg fill:#e2e3e5,stroke:#333,stroke-width:1px;
    classDef data fill:#f8d7da,stroke:#333,stroke-width:1px;
```
