# tongchengopensource/smart-doc architecture

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

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

## Overview

##### Project Type and Purpose
- Smart‑doc is an open-source Java tool for generating API documentation. It processes Java source code (using only Javadoc comments) and supports various interfaces (REST API, WebSocket, Apache Dubbo RPC, gRPC, etc.) without requiring annotations. The README emphasizes “zero annotation” and “source code analysis,” while the file structure shows multiple “builder” classes to handle diverse documentation formats (Markdown, HTML5, Word, Asciidoctor, Postman, OpenAPI, etc.).

##### File Structure Insights
- The project follows a Maven structure (with a pom.xml, sources in src/main/java, and tests in src/test/java).
- Within src/main/java/com/ly/doc, there is a rich modular separation:
– Builder Modules: Directories such as builder, builder/grpc, builder/javadoc, builder/openapi, builder/rpc, builder/websocket indicate that for each supported API protocol, there are specialized builder classes (like ApiDocBuilder, HtmlApiDocBuilder, GrpcHtmlBuilder, etc.).
– Constants & Models: The “constants” and “model” packages abstract the definitions and configurations that govern how API elements are interpreted.
– Factories & Templates: There’s a “factory” package (e.g., BuildTemplateFactory) and a “template” package that govern the selection and application of documentation templates.
– Helpers & Utilities: Numerous “helper” and “util” packages, including classes for JSON, Curl, and Doc URL handling.
- Resources include a templates directory with various file formats (adoc, md, html, xml) and a configuration for the Beetl template engine – indicating the importance of a robust templating system in the documentation generation flow.

##### Key Components
a. Source Code Analyzer:
– The entry point which reads source code and extracts API definitions using Javadoc comments.
– Involves “helper” and “filter” modules (e.g., DocBuildHelper, DocClassUtil) that parse and process the Java source.
b. API Data Model Layer:
– Represents the various POJO classes under “model” (like ApiDoc, ApiGroup, ApiMethodDoc, etc.) that capture the metadata and structure of the APIs.
c. Builder Modules (Factory and Template Selection):
– Each builder module (such as ApiDocBuilder, GrpcHtmlBuilder, JavadocMarkdownBuilder, etc.) is responsible for producing documentation in a supported format.
d. Template Engine:
– A distinct component that integrates with the Beetl template engine (supported by files like beetl.properties and BeetlTemplateUtil) to merge data with pre-defined templates stored under the resources/template directory.
e. Output Generators:
– Show different outputs produced (Markdown, HTML, Word, Asciidoctor, Postman JSON, etc.) based on chosen templates.
f. Integration Points / External Services:
– Optionally, include an external integration element that connects Smart‑doc with enterprise tools like Torna, as highlighted in the README and best practices section.

##### Relationships and Data Flow
- “Builder Factory” taking the data model and selecting a specialized builder.
- Each builder picks an appropriate “Template” and passes data to the “Template Engine.”
- The merged result is then output as the final generated API documentation.
- Incorporate supporting utilities like filters and helper classes that operate at various stages (data cleaning, formatting, example generation, etc.).

##### Architectural Patterns/Design Principles
- Modularity: Separate builders, models, templates, and utilities into distinct components.
- Strategy/Factory Pattern: Use the builder factory to dynamically select which documentation generation strategy to apply.
- Template Method Pattern: Builders follow a standard interface while differing in template application (e.g., HTML vs. Markdown vs. Word).
- Loose Coupling: The system decouples source code parsing from document formatting, enhancing extensibility.

##### Relevant Technologies and Frameworks
- Java (with a minimum version of 1.8)
- Maven (for build and dependency management)
- Beetl Template Engine (for template processing)
- Test frameworks (JUnit or similar, as indicated by the tests directory)
- Integration and deployment workflows (GitHub/Gitee workflows, Travis CI scripts, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Code Analysis Subgraph
    subgraph "Source Code Analysis"
        DBH["DocBuildHelper"]:::source
        DCU["DocClassUtil"]:::source
    end

    ADM["API Data Model Layer"]:::model

    %% Builder Modules Subgraph
    subgraph "Builder Modules"
        BF["Builder Factory"]:::builder
        IB["Individual Builders"]:::builder
    end

    %% Template Engine Subgraph
    subgraph "Template Engine"
        TE["Engine Core"]:::template
        TC["Beetl Configuration"]:::template
        BTU["Beetl Template Util"]:::template
        T["Templates"]:::template
    end

    DG["Documentation Output"]:::output

    %% External Integration Subgraph
    subgraph "External Integration"
        EI["Torna Integration"]:::external
        TDM["Torna Data Model"]:::external
    end

    %% Connections - Data Flow
    DBH --> ADM
    DCU --> ADM
    ADM -->|"passes_model"| BF
    BF -->|"selects_builder"| IB
    IB -->|"uses_engine"| TE
    TE -->|"merges_template"| DG
    IB -->|"integrates_with"| EI
    EI -->|"relies_on"| TDM
    EI -->|"outputs_to"| DG

    %% Click Events
    click DBH "https://github.com/tongchengopensource/smart-doc/blob/master/src/main/java/com/ly/doc/helper/DocBuildHelper.java"
    click DCU "https://github.com/tongchengopensource/smart-doc/blob/master/src/main/java/com/ly/doc/utils/DocClassUtil.java"
    click ADM "https://github.com/tongchengopensource/smart-doc/tree/master/src/main/java/com/ly/doc/model"
    click BF "https://github.com/tongchengopensource/smart-doc/blob/master/src/main/java/com/ly/doc/factory/BuildTemplateFactory.java"
    click IB "https://github.com/tongchengopensource/smart-doc/tree/master/src/main/java/com/ly/doc/builder"
    click TC "https://github.com/tongchengopensource/smart-doc/blob/master/src/main/resources/beetl.properties"
    click BTU "https://github.com/tongchengopensource/smart-doc/blob/master/src/main/java/com/ly/doc/utils/BeetlTemplateUtil.java"
    click T "https://github.com/tongchengopensource/smart-doc/tree/master/src/main/resources/template"
    click EI "https://github.com/tongchengopensource/smart-doc/blob/master/src/main/java/com/ly/doc/builder/TornaBuilder.java"
    click TDM "https://github.com/tongchengopensource/smart-doc/tree/master/src/main/java/com/ly/doc/model/torna"

    %% Styles
    classDef source fill:#FFCC80,stroke:#333,stroke-width:2px;
    classDef model fill:#90CAF9,stroke:#333,stroke-width:2px;
    classDef builder fill:#A5D6A7,stroke:#333,stroke-width:2px;
    classDef template fill:#FFF176,stroke:#333,stroke-width:2px;
    classDef output fill:#CE93D8,stroke:#333,stroke-width:2px;
    classDef external fill:#EF9A9A,stroke:#333,stroke-width:2px;
```
