# pingfangushi/screw architecture

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

- Interactive diagram: https://gitdiagram.com/pingfangushi/screw
- Repository: https://github.com/pingfangushi/screw

## Overview

##### Project type and purpose
- This is a multi-module Java open-source tool (not a web or full-stack app).
- Modules:
- screw-core: the engine that introspects JDBC data sources, builds metadata models, processes them, and renders documentation via templates (HTML/Markdown/Word).
- screw-extension: an optional POJO-generation extension built on top of screw-core to create Java entity classes from database tables.
- screw-maven-plugin: a Maven Mojo wrapper that allows running the documentation generator directly during a Maven build.
- Purpose: generate database schema documentation (and optionally POJOs) automatically from live databases.

##### File structure
- Top-level pom.xml with three child modules.
- lib/: JDBC driver JARs for CacheDB, DM.
- screw-core:
- src/main/java/cn/smallbun/screw/core: core packages: configuration, version, constants.
- core/query/*: DatabaseQueryFactory → dialect-specific DatabaseQuery implementations → metadata models.
- core/process: transforms metadata models into DataModel.
- core/execute: DocumentationExecute orchestrates query → process → template engine.
- core/engine: AbstractTemplateEngine + Freemarker/Velocity implementations.
- core/util & core/mapping: shared helpers and mapping abstractions.
- src/main/resources/template: FTL/VM templates for html/md/word.
- src/main/resources/properties: per-dialect SQL properties.
- screw-extension: parallels core but for PojoExecute, PojoEngine, TypeDialect, HumpNameStrategy.
- screw-maven-plugin: Mojo class (RunDocMojo) that builds a Configuration and invokes DocumentationExecute (and could be extended to Pojo).

##### README insights
- Core library is intended to be embedded or invoked by user code or via the Maven plugin.
- EngineConfig, ProcessConfig, Configuration (cn.smallbun.screw.core.Configuration) form the user API.
- Data flow: DataSource → Configuration → DocumentationExecute → Query → Process → TemplateEngine → filesystem output.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        direction TB
        JDBCDrivers["JDBC Drivers"]:::external
        DataSource["JDBC DataSource"]:::external
        Database["Database"]:::external
        FileSystem["Filesystem Output"]:::external
    end

    %% User Layer
    subgraph "User Layer"
        direction TB
        UserApp["Application Code"]:::external
        MavenBuild["Maven Build"]:::external
    end

    %% Maven Plugin
    subgraph "screw-maven-plugin"
        direction TB
        RunDocMojo["RunDocMojo"]:::plugin
    end

    %% Core Module
    subgraph "screw-core" 
        direction TB
        Configuration["Configuration (Builder)"]:::core
        EngineConfig["EngineConfig"]:::core
        ProcessConfig["ProcessConfig"]:::core
        DocumentationExecute["DocumentationExecute"]:::core
        AbstractExecute["AbstractExecute"]:::core

        subgraph "Query Subsystem"
            direction TB
            DatabaseQueryFactory["DatabaseQueryFactory"]:::core
            DatabaseQuery["DatabaseQuery implementations"]:::core
            MetadataModels["Metadata Models\n(DatabaseModel, TableModel, ColumnModel)"]:::core
        end

        subgraph "Process Subsystem"
            direction TB
            DataModelProcess["DataModelProcess"]:::core
        end

        subgraph "Templating Subsystem"
            direction TB
            AbstractTemplateEngine["AbstractTemplateEngine"]:::core
            FreemarkerTemplateEngine["FreemarkerTemplateEngine"]:::core
            VelocityTemplateEngine["VelocityTemplateEngine"]:::core
            Templates["Template Files\n(FTL/VM)"]:::core
        end

        MappingHelpers["Mapping Helpers"]:::core
        Util["Utility Classes"]:::core
    end

    %% Extension Module
    subgraph "screw-extension"
        direction TB
        PojoConfiguration["PojoConfiguration"]:::extension
        PojoExecute["PojoExecute"]:::extension
        PojoEngine["PojoEngine"]:::extension
        FreeMarkerPojoEngine["FreeMarkerPojoEngine"]:::extension
        TypeDialectFactory["TypeDialectFactory"]:::extension
        MysqlTypeDialect["MysqlTypeDialect"]:::extension
        PojoModelProcess["PojoModelProcess"]:::extension
        NamingStrategy["NamingStrategy"]:::extension
        PojoTemplates["Pojo Templates\n(freemarker/pojo_java.ftl)"]:::extension
    end

    %% Relationships
    UserApp -->|"invoke"| Configuration
    MavenBuild -->|"exec plugin"| RunDocMojo
    RunDocMojo -->|"invoke"| DocumentationExecute

    UserApp -->|"invoke"| DocumentationExecute
    Configuration -->|"build config"| DocumentationExecute
    Configuration -->|"build config"| PojoExecute

    DocumentationExecute -->|"extends"| AbstractExecute
    DocumentationExecute -->|"execute()"| DatabaseQueryFactory
    DocumentationExecute -->|"execute()"| DataModelProcess
    DocumentationExecute -->|"execute()"| AbstractTemplateEngine

    AbstractExecute -->|"uses"| DatabaseQueryFactory
    DatabaseQueryFactory -->|"create()"| DatabaseQuery
    DatabaseQuery -->|"queryMetadata()"| MetadataModels
    MetadataModels -->|"provide data"| DataModelProcess
    DataModelProcess -->|"process()"| MetadataModels
    DataModelProcess -->|"produce DataModel"| AbstractTemplateEngine

    AbstractTemplateEngine -->|"render()"/NONE| FreemarkerTemplateEngine
    AbstractTemplateEngine -->|"render()"/NONE| VelocityTemplateEngine
    FreemarkerTemplateEngine -->|"use templates"| Templates
    VelocityTemplateEngine -->|"use templates"| Templates
    AbstractTemplateEngine -->|"write()"| FileSystem

    DataSource -->|"getConnection()"| DatabaseQuery
    JDBCDrivers --> DataSource
    DataSource -->|"connect"| Database

    %% Extension Flows
    PojoConfiguration -->|"build config"| PojoExecute
    PojoExecute -->|"exec()"| TypeDialectFactory
    TypeDialectFactory -->|"getDialect()"| MysqlTypeDialect
    PojoExecute -->|"exec()"| PojoModelProcess
    PojoModelProcess -->|"process()"| MetadataModels
    PojoExecute -->|"exec()"| PojoEngine
    PojoEngine -->|"use templates"| PojoTemplates
    PojoEngine -->|"use strategy"| NamingStrategy
    PojoExecute -->|"write()"| FileSystem

    %% Click Events
    click Configuration "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/Configuration.java"
    click EngineConfig "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/engine/EngineConfig.java"
    click ProcessConfig "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/process/ProcessConfig.java"
    click DocumentationExecute "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/execute/DocumentationExecute.java"
    click AbstractExecute "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/execute/AbstractExecute.java"
    click DatabaseQueryFactory "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/query/DatabaseQueryFactory.java"
    click DatabaseQuery "https://github.com/pingfangushi/screw/tree/master/screw-core/src/main/java/cn/smallbun/screw/core/query/"
    click MetadataModels "https://github.com/pingfangushi/screw/tree/master/screw-core/src/main/java/cn/smallbun/screw/core/metadata/model"
    click DataModelProcess "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/process/DataModelProcess.java"
    click AbstractTemplateEngine "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/engine/AbstractTemplateEngine.java"
    click FreemarkerTemplateEngine "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/engine/freemark/FreemarkerTemplateEngine.java"
    click VelocityTemplateEngine "https://github.com/pingfangushi/screw/blob/master/screw-core/src/main/java/cn/smallbun/screw/core/engine/velocity/VelocityTemplateEngine.java"
    click Templates "https://github.com/pingfangushi/screw/tree/master/screw-core/src/main/resources/template/"
    click MappingHelpers "https://github.com/pingfangushi/screw/tree/master/screw-core/src/main/java/cn/smallbun/screw/core/mapping"
    click Util "https://github.com/pingfangushi/screw/tree/master/screw-core/src/main/java/cn/smallbun/screw/core/util"
    click PojoConfiguration "https://github.com/pingfangushi/screw/blob/master/screw-extension/src/main/java/cn/smallbun/screw/extension/pojo/PojoConfiguration.java"
    click PojoExecute "https://github.com/pingfangushi/screw/blob/master/screw-extension/src/main/java/cn/smallbun/screw/extension/pojo/execute/PojoExecute.java"
    click PojoEngine "https://github.com/pingfangushi/screw/blob/master/screw-extension/src/main/java/cn/smallbun/screw/extension/pojo/engine/PojoEngine.java"
    click FreeMarkerPojoEngine "https://github.com/pingfangushi/screw/blob/master/screw-extension/src/main/java/cn/smallbun/screw/extension/pojo/engine/freemark/FreeMarkerPojoEngine.java"
    click TypeDialectFactory "https://github.com/pingfangushi/screw/blob/master/screw-extension/src/main/java/cn/smallbun/screw/extension/pojo/dialect/TypeDialectFactory.java"
    click MysqlTypeDialect "https://github.com/pingfangushi/screw/blob/master/screw-extension/src/main/java/cn/smallbun/screw/extension/pojo/dialect/mysql/MysqlTypeDialect.java"
    click PojoModelProcess "https://github.com/pingfangushi/screw/blob/master/screw-extension/src/main/java/cn/smallbun/screw/extension/pojo/process/PojoModelProcess.java"
    click NamingStrategy "https://github.com/pingfangushi/screw/blob/master/screw-extension/src/main/java/cn/smallbun/screw/extension/pojo/strategy/NameStrategy.java"
    click PojoTemplates "https://github.com/pingfangushi/screw/blob/master/screw-extension/src/main/resources/template/freemarker/pojo_java.ftl"
    click RunDocMojo "https://github.com/pingfangushi/screw/blob/master/screw-maven-plugin/src/main/java/cn/smallbun/screw/maven/plugin/mojo/RunDocMojo.java"
    click JDBCDrivers "https://github.com/pingfangushi/screw/blob/master/lib/cachejdbc.jar"
    click JDBCDrivers "https://github.com/pingfangushi/screw/blob/master/lib/Dm7JdbcDriver-16.jar"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#1976D2,color:#0D47A1
    classDef extension fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef plugin fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef external fill:#E0E0E0,stroke:#9E9E9E,color:#424242
```
