# tongchengopensource/smart-doc-maven-plugin architecture

> Architecture diagram of the GitHub repository tongchengopensource/smart-doc-maven-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tongchengopensource/smart-doc-maven-plugin
- Repository: https://github.com/tongchengopensource/smart-doc-maven-plugin

## Overview

##### Project Type and Purpose
- This is an open-source Maven plugin (“smart-doc-maven-plugin”) that hooks into the Maven build lifecycle to automatically generate API documentation from Java source code.
- It does not provide a UI; instead, it acts as a bridge between your Java project and the Smart-Doc core engine (and optionally external services such as Torna).

##### High-Level File-Structure Analysis
- pom.xml – declares this module as a Maven plugin and its dependencies.
- src/main/java/com/ly/doc/plugin
- chain – a Chain of Responsibility implementation for filtering artifacts on the classpath (e.g., by groupId, artifactId, prefixes, etc.).
- constant – global and Mojo-specific configuration keys.
- mojo – one Mojo class per goal (html, markdown, adoc, openapi, torna-rest, etc.), all extending BaseDocsGeneratorMojo.
- util – helper classes for class loading, file operations, reading plugin configurations, etc.
- src/main/resources – default.json (fallback defaults) and smart-doc.json (user-supplied configuration).

##### README Insights
- The plugin reads smart-doc.json (or defaults), analyzes the Maven project’s dependency tree, applies include/exclude filters, then invokes Smart-Doc’s code-analysis engine.
- It supports multiple “goals” (Mojo classes): html, markdown, adoc, postman, openapi, word, jmeter, RPC variants, and Torna push.
- Emphasizes zero-intrusion: no test harness needed, runs as part of “mvn compile” (or via IDE).

##### Main Components
a. Maven Core
- Lifecycle Phases & Plugin API
b. Smart-Doc Maven Plugin
- Mojo Layer – one class per goal (e.g., HtmlMojo, MarkdownMojo, OpenApiMojo, TornaRestMojo, etc.)
- Config Reader – reads smart-doc.json or default.json
- Dependency Analyzer – traverses the project’s dependency graph via Maven Project API
- FilterChain – applies chain-of-responsibility filters (CommonArtifactFilterChain, GroupIdFilterChain, etc.)
- Smart-Doc Engine Invocation – hands off filtered classes/sources to the Smart-Doc core library
- Format Renderers – built‐in Smart-Doc format modules (HTML, Markdown, ADOC, OpenAPI JSON, Postman, Word, JMeter)
- TornaClient – when the Torna goal runs, pushes generated docs to the external Torna REST API
c. Resources
- smart-doc.json (user config)
- default.json (plugin defaults)
d. Inputs & Outputs
- Input: Java source code + annotations + smart-doc.json
- Output: documentation artifacts (files on disk) and/or HTTP calls to Torna

##### Relationships & Data Flow
1. Maven invokes the selected Mojo during the build phase (e.g., compile)
2. Mojo loads configuration (smart-doc.json or default.json)
3. Mojo uses the Maven Project API to collect project classes and dependencies
4. Dependency Analyzer feeds artifacts through the FilterChain
5. FilterChain outputs a set of source‐code locations to process
6. Mojo calls the Smart-Doc core engine, passing in source locations and config
7. Smart-Doc core analyzes code, builds an API model
8. Format Renderer module generates files (HTML/MD/ADOC/OpenAPI/Word, etc.) into outPath
9. If Torna goal: TornaClient issues REST calls to push JSON payloads to the Torna server

##### Architectural Patterns & Principles
- Plugin/Mojo extension point pattern (Maven Plugin API)
- Chain of Responsibility for flexible artifact filtering
- Separation of concerns: config reading, filtering, engine invocation, rendering, external integration
- Convention-over-configuration: default.json vs. optional smart-doc.json

##### Technologies & Frameworks
- Java 1.8+
- Maven Plugin API
- Smart-Doc Core Library (embedded as a dependency)
- Jackson/Gson (for parsing smart-doc.json)
- HTTP client (for Torna REST)
- Standard I/O and ClassLoader utilities

##### Essential Elements to Capture
- Plugin API → Mojo invocation
- Config loading (default.json vs. smart-doc.json)
- DependencyAnalyzer + FilterChain (chain‐of‐responsibility)
- Engine invocation and format renderers
- Torna integration path (HTTP client)
- Inputs (source + annotations) and outputs (files + REST calls)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers and Components
    Pom["pom.xml"]:::buildTime
    MavenCore["Maven Core<br/>(Lifecycle & Plugin API)"]:::buildTime

    subgraph "Plugin Layer"
        direction TB
        Mojo["Mojo Layer<br/>(one class per goal)"]:::plugin
        Base["BaseDocsGeneratorMojo"]:::plugin
    end

    subgraph "Configuration" 
        direction TB
        GlobalConst["GlobalConstants.java"]:::plugin
        MojoConst["MojoConstants.java"]:::plugin
        DefaultRes["default.json"]:::resource
        UserRes["smart-doc.json"]:::resource
    end

    subgraph "Analysis & Filtering"
        direction TB
        DepAnalyzer["Dependency Analyzer"]:::plugin
        Chain["FilterChain<br/>(chain-of-responsibility)"]:::plugin
    end

    Util["Utility Helpers"]:::plugin

    subgraph "Smart-Doc Core" 
        direction TB
        Engine["Smart-Doc Core Engine"]:::engine
        Renderers["Format Renderers<br/>(HTML, MD, ADOC, OpenAPI, etc.)"]:::engine
    end

    subgraph "External Integration"
        direction TB
        Torna["TornaClient<br/>(REST API)"]:::external
    end

    FilesOutput["Documentation Files on Disk"]:::engine

    %% Connections
    Pom --> MavenCore
    MavenCore --> Mojo
    Mojo --> Base
    Mojo --> GlobalConst
    Mojo --> MojoConst
    Mojo --> DefaultRes
    Mojo --> UserRes
    Base --> DepAnalyzer
    DepAnalyzer --> Chain
    Chain --> Engine
    Engine --> Renderers
    Renderers --> FilesOutput
    Base --> Util
    Base --> Torna

    %% Click Events
    click Pom "https://github.com/tongchengopensource/smart-doc-maven-plugin/blob/master/pom.xml"
    click Mojo "https://github.com/tongchengopensource/smart-doc-maven-plugin/tree/master/src/main/java/com/ly/doc/plugin/mojo/"
    click Base "https://github.com/tongchengopensource/smart-doc-maven-plugin/blob/master/src/main/java/com/ly/doc/plugin/mojo/BaseDocsGeneratorMojo.java"
    click GlobalConst "https://github.com/tongchengopensource/smart-doc-maven-plugin/blob/master/src/main/java/com/ly/doc/plugin/constant/GlobalConstants.java"
    click MojoConst "https://github.com/tongchengopensource/smart-doc-maven-plugin/blob/master/src/main/java/com/ly/doc/plugin/constant/MojoConstants.java"
    click DefaultRes "https://github.com/tongchengopensource/smart-doc-maven-plugin/blob/master/src/main/resources/default.json"
    click UserRes "https://github.com/tongchengopensource/smart-doc-maven-plugin/blob/master/src/main/resources/smart-doc.json"
    click Chain "https://github.com/tongchengopensource/smart-doc-maven-plugin/blob/master/src/main/java/com/ly/doc/plugin/chain/FilterChain.java"
    click DepAnalyzer "https://github.com/tongchengopensource/smart-doc-maven-plugin/tree/master/src/main/java/com/ly/doc/plugin/chain/"
    click Util "https://github.com/tongchengopensource/smart-doc-maven-plugin/tree/master/src/main/java/com/ly/doc/plugin/util/"
    click Torna "https://github.com/tongchengopensource/smart-doc-maven-plugin/blob/master/src/main/java/com/ly/doc/plugin/mojo/TornaRestMojo.java"

    %% Styles
    classDef buildTime fill:#D0E6FF,stroke:#007ACC,color:#000
    classDef plugin fill:#E6F4EA,stroke:#34A853,color:#000
    classDef engine fill:#FFE6CC,stroke:#FB8C00,color:#000
    classDef external fill:#F3E5F5,stroke:#9C27B0,color:#000
    classDef resource fill:#E0F7FA,stroke:#006064,color:#000
```
