# linpeilie/mapstruct-plus architecture

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

- Interactive diagram: https://gitdiagram.com/linpeilie/mapstruct-plus
- Repository: https://github.com/linpeilie/mapstruct-plus

## Overview

##### Project Type and Purpose
- This is a multi‑module Java library and toolset (Maven-based) that enhances MapStruct, providing annotation-driven automatic object mapping.
- Core modules:
- mapstruct‑plus (runtime library containing Converter, ConverterFactory, utilities, base classes)
- mapstruct‑plus‑processor (compile‑time annotation processor that scans @AutoMapper, generates mapper code)
- mapstruct‑plus‑spring‑boot‑starter (Spring Boot auto‑configuration, registers Converter bean)
- mapstruct‑plus‑object‑convert (convenience wrapper for direct object conversion)
- Supporting modules: docs (VuePress site), example projects demonstrating usage, CI/CD workflows under .github.

##### File‑Structure Analysis
- Top level: parent pom.xml, module directories, .github workflows, docs folder for site generation, example folder for sample apps.
- Each module contains its own pom.xml and src tree.
- build logic: Maven multi‑module aggregator; annotationProcessorPaths defined in examples to include mapstruct‑plus‑processor.
- Configuration files for docs (VuePress) and GitHub Actions for issue management, docs deployment, release.

##### Key README Insights
- Describes MapStruct Plus goal: minimal, powerful type conversion via @AutoMapper annotations.
- Quick‑start shows adding mapstruct‑plus‑spring‑boot‑starter and mapstruct‑plus‑processor to Maven compiler plugin.
- Developer workflow: annotate classes, compile (processor generates mapping code), at runtime inject Converter and call convert().

a. Main Components
- User Application Code
- Annotation Processor (mapstruct‑plus‑processor)
- Generated Mapper Classes
- Core Runtime Library (mapstruct‑plus)
- Spring Boot Starter (mapstruct‑plus‑spring‑boot‑starter)
- Converter Facade (mapstruct‑plus‑object‑convert)
- External: MapStruct core, Spring Context, Maven Compiler Plugin
b. Relationships and Data Flows
1. User code annotated with @AutoMapper → during “mvn compile”
→ mapstruct‑plus‑processor reads annotations → generates mapper source files.
2. Generated mappers depend on core library APIs (ConverterFactory, BaseMapper).
3. At runtime, Spring Boot Starter auto‑configures Converter bean → wires in generated mappers via ConverterFactory.
4. Application invokes converter.convert(source, Target.class) → core library uses generated mapper methods → returns target instance.
5. mapstruct‑plus‑object‑convert provides static helper MapObjectConvert for non‑Spring environments.
c. Architectural Patterns & Principles
- Compile‑time code generation (annotation processing)
- Inversion of Control / Dependency Injection (Spring Starter)
- Separation of concerns:
– Processor module handles generation
– Core module handles runtime conversion logic
– Starter module handles framework integration
- Maven multi‑module structure for clear modular boundaries
d. Technologies & Frameworks
- Java Annotation Processing API (javax.annotation.processing)
- Maven Compiler Plugin
- Spring Boot Auto‑Configuration
- VuePress for documentation
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Code and Build
    subgraph "User Application"
        direction TB
        UserCode["User Code<br/>(annotated @AutoMapper)"]:::user
        MavenPlugin["Maven Compiler Plugin"]:::external
    end

    %% Compile-time Modules
    subgraph "Compile-time Generation" 
        direction TB
        Processor["AutoMapperProcessor"]:::compile
        Metadata["Processor Metadata"]:::compile
        Generator["Mapper Generators"]:::compile
        SpringEnhance["SpringComponentProcessor"]:::compile
        SolonEnhance["SolonComponentProcessor"]:::compile
    end

    %% Generated Code
    GeneratedMapper["Generated Mapper Classes"]:::generated

    %% Runtime Modules
    subgraph "Runtime Modules"
        direction TB
        Core["Core Runtime Library<br/>(mapstruct-plus)"]:::runtime
        Starter["Spring Boot Starter"]:::runtime
        ConverterFacade["MapObjectConvert<br/>(object-convert)"]:::runtime
    end

    %% Core internals
    subgraph "Core Runtime Library Internals"
        direction TB
        Converter["Converter"]:::runtime
        ConverterFactory["ConverterFactory"]:::runtime
        BaseMapper["BaseMapper"]:::runtime
        BaseMapMapper["BaseMapMapper"]:::runtime
        BaseCycleAvoidingMapper["BaseCycleAvoidingMapper"]:::runtime
        AnnotationsPkg["Annotations Package"]:::runtime
        UtilsPkg["Utilities Package"]:::runtime
    end

    %% Spring Starter internals
    subgraph "Spring Boot Starter Internals"
        direction TB
        AutoConfig["MapstructAutoConfiguration"]:::runtime
        SpringCF["SpringConverterFactory"]:::runtime
        SpringUtils["SpringContextUtils4Msp"]:::runtime
        Factories["spring.factories"]:::runtime
        AutoImports["AutoConfiguration.imports"]:::runtime
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        MapStructCore["MapStruct Core"]:::external
        SpringContext["Spring Context"]:::external
        AnnotationAPI["Java Annotation Processing API"]:::external
    end

    %% Examples and Docs
    subgraph "Supporting Modules"
        direction TB
        Examples["Example Projects"]:::support
        Docs["Documentation Site"]:::support
        CI["CI/CD Workflows"]:::support
    end

    %% Build and Generation Flow
    UserCode -->|"compile with annotations"| MavenPlugin
    MavenPlugin -->|"scans @AutoMapper"| Processor
    Processor -->|"uses metadata"| Metadata
    Processor -->|"uses generators"| Generator
    Processor -->|"enhances Spring"| SpringEnhance
    Processor -->|"enhances Solon"| SolonEnhance
    Processor -->|"generates .java files"| GeneratedMapper

    %% Generated to Runtime
    GeneratedMapper -->|"depends on core APIs"| Core

    %% Runtime wiring
    SpringContext -->|"auto-configures bean"| AutoConfig
    AutoConfig -->|"registers Converter bean"| SpringCF
    SpringCF --> ConverterFactory
    ConverterFactory --> Converter
    GeneratedMapper -->|"used by convert()"| Converter
    UserCode -->|"invokes convert()"| ConverterFacade
    ConverterFacade --> GeneratedMapper
    ConverterFacade --> Core

    %% Dependencies
    Core --> AnnotationAPI
    Metadata --> MapStructCore

    %% Supporting modules usage
    Examples --> MavenPlugin
    CI --> Examples
    CI --> Docs

    %% Click events Core Runtime
    click Converter "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus/src/main/java/io/github/linpeilie/Converter.java"
    click ConverterFactory "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus/src/main/java/io/github/linpeilie/ConverterFactory.java"
    click BaseMapper "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus/src/main/java/io/github/linpeilie/BaseMapper.java"
    click BaseMapMapper "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus/src/main/java/io/github/linpeilie/BaseMapMapper.java"
    click BaseCycleAvoidingMapper "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus/src/main/java/io/github/linpeilie/BaseCycleAvoidingMapper.java"
    click AnnotationsPkg "https://github.com/linpeilie/mapstruct-plus/tree/main/mapstruct-plus/src/main/java/io/github/linpeilie/annotations"
    click UtilsPkg "https://github.com/linpeilie/mapstruct-plus/tree/main/mapstruct-plus/src/main/java/io/github/linpeilie/utils"

    %% Click events Processor
    click Processor "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus-processor/src/main/java/io/github/linpeilie/processor/AutoMapperProcessor.java"
    click Metadata "https://github.com/linpeilie/mapstruct-plus/tree/main/mapstruct-plus-processor/src/main/java/io/github/linpeilie/processor/metadata"
    click Generator "https://github.com/linpeilie/mapstruct-plus/tree/main/mapstruct-plus-processor/src/main/java/io/github/linpeilie/processor/generator"
    click SpringEnhance "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus-processor/src/main/java/io/github/linpeilie/processor/enhance/processor/SpringComponentProcessor.java"
    click SolonEnhance "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus-processor/src/main/java/io/github/linpeilie/processor/enhance/processor/SolonComponentProcessor.java"

    %% Click events Starter
    click AutoConfig "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus-spring-boot-starter/src/main/java/io/github/linpeilie/mapstruct/MapstructAutoConfiguration.java"
    click SpringCF "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus-spring-boot-starter/src/main/java/io/github/linpeilie/mapstruct/SpringConverterFactory.java"
    click SpringUtils "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus-spring-boot-starter/src/main/java/io/github/linpeilie/mapstruct/SpringContextUtils4Msp.java"
    click Factories "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus-spring-boot-starter/src/main/resources/META-INF/spring.factories"
    click AutoImports "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports"

    %% Click events Converter Facade
    click ConverterFacade "https://github.com/linpeilie/mapstruct-plus/blob/main/mapstruct-plus-object-convert/src/main/java/io/github/linpeilie/map/MapObjectConvert.java"

    %% Click events Supporting
    click Docs "https://github.com/linpeilie/mapstruct-plus/blob/main/docs/.vuepress/config.ts"
    click Examples "https://github.com/linpeilie/mapstruct-plus/tree/main/example/quick-start"
    click Examples "https://github.com/linpeilie/mapstruct-plus/tree/main/example/spring-boot-3"
    click Examples "https://github.com/linpeilie/mapstruct-plus/tree/main/example/spring-boot-with-lombok"
    click Examples "https://github.com/linpeilie/mapstruct-plus/tree/main/example/spring-boot"
    click CI "https://github.com/linpeilie/mapstruct-plus/blob/main/ .github/workflows/close-inactive-issues.yml"
    click CI "https://github.com/linpeilie/mapstruct-plus/blob/main/ .github/workflows/deploy-docs.yml"
    click CI "https://github.com/linpeilie/mapstruct-plus/blob/main/ .github/workflows/deploy-release.yml"

    %% Styles
    classDef compile fill:#D0E4FF,stroke:#009,stroke-width:1px
    classDef runtime fill:#FFD8B0,stroke:#F60,stroke-width:1px
    classDef user fill:#D0FFD8,stroke:#080,stroke-width:1px
    classDef generated fill:#E0FFE0,stroke:#080,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#666,stroke-width:1px
    classDef support fill:#F0F0F0,stroke:#999,stroke-width:1px
```
