# sxyang-super/exception-unifier architecture

> Architecture diagram of the GitHub repository sxyang-super/exception-unifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sxyang-super/exception-unifier
- Repository: https://github.com/sxyang-super/exception-unifier

## Overview

##### Project type and purpose
- This is a multi-module, open-source tooling project (not a typical frontend-backend web app). It ships:
- A base Java library (exception-unifier-base) defining your exception pattern and runtime APIs
- A Java annotation processor (exception-unifier-processor) to validate exception usage at compile time
- A Maven plugin (exception-unifier-maven-plugin) with three Mojos (check, sync, push) that:
– Inspects/rewrites exception enums via ASM
– Reads module prefix (BASE or REMOTE)
– Pushes exception metadata to a remote server
- A lightweight Node.js “exms” microservice that acts as the central exception-code management server

##### File-structure highlights
- Top-level pom.xml aggregates four submodules
- exception-unifier-base (src/main/java/.../base) contains BaseException, assertion interfaces, exception enum patterns
- exception-unifier-processor (src/main/java/.../processor) implements a javax.annotation.processing.Processor
- exception-unifier-maven-plugin (src/main/java/.../mavenplugin) implements three Mojos (CheckMojo, SyncMojo, PushMojo), plus handler and ASM visitor packages
- exms (JavaScript/Node.js) implements an HTTP server with two routes: prefix-route.js and exception-enum.js, backed by a JSON data store

##### Key README insights
- Pattern: exceptions unified behind BaseException + IExceptionEnum / IExceptionEnumAsserts
- Compile-time: annotation processor enforces enum implementation and generates code
- Build-time: Maven plugin “check” validates no duplicates; “sync” prepends module prefix; “push” POSTs metadata to exms server
- Two source modes: BASE (prefix in POM) vs. REMOTE (prefix fetched from exms via REST)

##### Components
A. Java Toolchain (left side)
- Developer code: user’s exception classes & enums
- exception-unifier-base: runtime library
- exception-unifier-processor: annotation processor plugged into javac
- exception-unifier-maven-plugin: three Mojos orchestrated by Maven lifecycle
– CheckHandler / SyncHandler / PushHandler
– ASM visitors (ModifyExceptionEnumClassVisitor, ReadExceptionEnumClassVisitor)
B. Build System
- Maven core calls compiler (invokes annotation processor)
- Maven core invokes plugin goals (check, sync bound to compile; push bound to install)
C. Central server (right side)
- exms (Node.js Express service)
- Endpoints:
– GET /prefix/{moduleId} → returns module prefix
– POST /exception-enum/bulk → receives exception metadata JSON
- Data store: source.json (or environment-configured)

##### Relationships & data flows
1. Developer invokes mvn compile
– Javac + exception-unifier-processor validate enums → error on misuse
– exception-unifier-maven-plugin “check” inspects bytecode with ASM → enforces constraints
– exception-unifier-maven-plugin “sync” either:
- Reads prefix from POM (BASE) or
- Calls exms GET /prefix (REMOTE)
then rewrites enum bytecode to inject full codes (prefix_source_code)
2. Developer invokes mvn install (or package)
– exception-unifier-maven-plugin “push” collects synced metadata and POSTs to exms server
3. exms persists or returns data to clients (remote management UI could be layered on top in future)

##### Architectural patterns & principles
- Multi-module Maven parent POM pattern
- Annotation-processing plug-in mechanism (javax.annotation.processing)
- Maven Mojo pattern (Command objects per goal)
- Bytecode manipulation with ASM visitors (visitor pattern)
- Microservice (REST API) for central prefix & metadata management
- Clear separation: compile-time validation, build-time code rewriting, runtime base library, external service

##### Detail checklist
- Component names & versions (2.0.0)
- Module roles (runtime vs. compile vs. build vs. service)
- Package-level interactions (e.g., processor → Base library)
- Source-type branching (BASE vs. REMOTE)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Developer code
    DevCode["Developer Exception Classes & Enums"]:::build

    %% Java Modules
    subgraph "Java Toolchain"
        BaseLib["exception-unifier-base\n(BaseException, IExceptionEnum, IExceptionEnumAsserts)"]:::javaModule
        Processor["exception-unifier-processor\n(ExceptionUnifierProcessor)"]:::javaModule
        subgraph "Processor Utilities"
            ProcUtil["ProcessorUtil"]:::javaModule
            UncheckedUtil["UncheckedUtil"]:::javaModule
            Consts["Consts"]:::javaModule
            AnnotationReg["META-INF/services/javax.annotation.processing.Processor"]:::javaModule
        end
        subgraph "Maven Plugin"
            Plugin["exception-unifier-maven-plugin\n(CheckMojo, SyncMojo, PushMojo)"]:::javaModule
            subgraph "Handlers & ASM Visitors & Sources"
                CheckHandler["CheckHandler"]:::javaModule
                SyncHandler["SyncHandler"]:::javaModule
                PushHandler["PushHandler"]:::javaModule
                ModifyVisitor["ModifyExceptionEnumClassVisitor"]:::javaModule
                ReadVisitor["ReadExceptionEnumClassVisitor"]:::javaModule
                BaseSource["BaseExceptionCodeSource"]:::javaModule
                RemoteSource["RemoteExceptionCodeSource"]:::javaModule
                Factory["ExceptionCodeSourceFactory"]:::javaModule
            end
        end
    end

    %% Build System
    subgraph "Build System"
        Maven["Maven Core"]:::build
        Javac["javac"]:::build
    end

    %% exms Service
    subgraph "exms Service"
        Exms["exms\n(Node.js Express)"]:::service
        PrefixRoute["GET /prefix/{moduleId}"]:::service
        EnumRoute["POST /exception-enum/bulk"]:::service
        DataStore["source.json"]:::service
    end

    %% Data Flows
    DevCode -->|invokes mvn compile| Maven
    Maven -->|calls| Javac
    Javac -->|annotation processing| Processor
    Processor -->|uses| BaseLib
    Processor -->|utilizes| ProcUtil
    Processor -->|utilizes| UncheckedUtil
    Processor -->|utilizes| Consts
    Processor -->|registered via| AnnotationReg
    Maven -->|executes compile-bound goals| Plugin
    Plugin -->|runs| CheckHandler
    CheckHandler -->|inspects bytecode with ASM| ReadVisitor
    CheckHandler -->|modifies bytecode with ASM| ModifyVisitor
    Plugin -->|runs| SyncHandler
    SyncHandler -->|reads prefix BASE| BaseSource
    SyncHandler -->|HTTP GET prefix| PrefixRoute
    PrefixRoute -->|returns prefix| SyncHandler
    Plugin -->|executes install-bound goal| PushHandler
    PushHandler -->|HTTP POST metadata| EnumRoute
    EnumRoute -->|stores/retrieves| DataStore

    %% Service internals
    Exms --> PrefixRoute
    Exms --> EnumRoute

    %% Click Events
    click BaseLib "https://github.com/sxyang-super/exception-unifier/tree/master/exception-unifier-base/src/main/java/io/github/sxyangsuper/exceptionunifier/base"
    click BaseException "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-base/src/main/java/io/github/sxyangsuper/exceptionunifier/base/BaseException.java"
    click IExceptionEnum "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-base/src/main/java/io/github/sxyangsuper/exceptionunifier/base/IExceptionEnum.java"
    click IExceptionEnumAsserts "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-base/src/main/java/io/github/sxyangsuper/exceptionunifier/base/IExceptionEnumAsserts.java"
    click Processor "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-processor/src/main/java/io/github/sxyangsuper/exceptionunifier/processor/ExceptionUnifierProcessor.java"
    click ProcUtil "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-processor/src/main/java/io/github/sxyangsuper/exceptionunifier/processor/ProcessorUtil.java"
    click UncheckedUtil "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-processor/src/main/java/io/github/sxyangsuper/exceptionunifier/processor/UncheckedUtil.java"
    click Consts "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-processor/src/main/java/io/github/sxyangsuper/exceptionunifier/processor/Consts.java"
    click AnnotationReg "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-processor/src/main/resources/META-INF/services/javax.annotation.processing.Processor"
    click Plugin "https://github.com/sxyang-super/exception-unifier/tree/master/exception-unifier-maven-plugin/src/main/java/io/github/sxyangsuper/exceptionunifier/mavenplugin"
    click SyncHandler "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-maven-plugin/src/main/java/io/github/sxyangsuper/exceptionunifier/mavenplugin/handler/SyncHandler.java"
    click CheckHandler "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-maven-plugin/src/main/java/io/github/sxyangsuper/exceptionunifier/mavenplugin/handler/CheckHandler.java"
    click PushHandler "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-maven-plugin/src/main/java/io/github/sxyangsuper/exceptionunifier/mavenplugin/handler/PushHandler.java"
    click ModifyVisitor "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-maven-plugin/src/main/java/io/github/sxyangsuper/exceptionunifier/mavenplugin/handler/asm/ModifyExceptionEnumClassVisitor.java"
    click ReadVisitor "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-maven-plugin/src/main/java/io/github/sxyangsuper/exceptionunifier/mavenplugin/handler/asm/ReadExceptionEnumClassVisitor.java"
    click BaseSource "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-maven-plugin/src/main/java/io/github/sxyangsuper/exceptionunifier/mavenplugin/source/BaseExceptionCodeSource.java"
    click RemoteSource "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-maven-plugin/src/main/java/io/github/sxyangsuper/exceptionunifier/mavenplugin/source/RemoteExceptionCodeSource.java"
    click Factory "https://github.com/sxyang-super/exception-unifier/blob/master/exception-unifier-maven-plugin/src/main/java/io/github/sxyangsuper/exceptionunifier/mavenplugin/source/ExceptionCodeSourceFactory.java"
    click Exms "https://github.com/sxyang-super/exception-unifier/blob/master/exms/index.js"
    click PrefixRoute "https://github.com/sxyang-super/exception-unifier/blob/master/exms/routes/prefix-route.js"
    click EnumRoute "https://github.com/sxyang-super/exception-unifier/blob/master/exms/routes/exception-enum.js"
    click DataStore "https://github.com/sxyang-super/exception-unifier/blob/master/exms/source/data/source.json"

    %% Styles
    classDef javaModule fill:#cce5ff,stroke:#036,stroke-width:1px
    classDef build fill:#d4edda,stroke:#036,stroke-width:1px
    classDef service fill:#ffe5b4,stroke:#036,stroke-width:1px
```
