# upstart-commerce/sbt-openapi-generator architecture

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

- Interactive diagram: https://gitdiagram.com/upstart-commerce/sbt-openapi-generator
- Repository: https://github.com/upstart-commerce/sbt-openapi-generator

## Overview

##### Project type and purpose
- This is an SBT plugin (“sbt-openapi-generator”) written in Scala.
- Purpose: to integrate OpenAPI Generator into an SBT build, allowing users to point at an OpenAPI spec and invoke an `openapiGenerate` task that emits client/server code according to configured templates.

##### File structure
- Top‐level files:
- build.sbt, version.sbt – the plugin’s build definition
- project/ – the SBT meta-build (plugins.sbt, build.properties)
- LICENSE, .gitignore, .travis.yml, .scalafmt.conf – CI and formatting configs
- Source layout under src/main/scala/org/upstartcommerce/openapi:
- OpenAPIGeneratorPlugin.scala – the plugin entry point (registers tasks, settings)
- OpenAPIGeneratorKeys.scala – defines all setting/task keys
- Test harness under src/sbt-test:
- Two sample test projects (“remote” and “simple”) with their own build.sbt, spec files, and plugin settings – used by SBT’s scripted test runner.

##### README for additional insights
- Usage instructions: how to include the plugin in project/plugins.sbt, enable it in build.sbt, and configure two mandatory settings (`openapiInputSpec`, `openapiGeneratorName`).
- Dozens of optional settings for fine-tuning generator behavior, templating, output paths, import mappings, etc.

a. Main components
- SBT Build Environment
- OpenAPIGeneratorPlugin (entry point)
- OpenAPIGeneratorKeys (settings & tasks registry)
- Task Graph / Trigger (`openapiGenerate` task)
- OpenAPI Generator CLI/Engine (third‐party library invoked by the plugin)
- File I/O (reading spec, writing generated sources)
- Template Engine (Mustache or Handlebars)
- Optional Post-Processing Module (driven by `openapiEnablePostProcessFile`)
- Test Harness (scripted tests under sbt-test)
b. Relationships & interactions
1. User’s build.sbt → enables plugin and sets keys
2. SBT loads OpenAPIGeneratorPlugin → registers keys & tasks
3. On `openapiGenerate`:
– Plugin reads settings (spec URI, generatorName, outputDir, additionalProperties, etc.)
– Fetches spec (local file or HTTP if remote authentication is set)
– Invokes OpenAPI Generator engine with chosen templates & settings
– Receives generated code artifacts
– (Optional) Post-process files via environment/script hooks
– Writes output to target directory
4. Scripted Test Harness:
– SBT’s scripted runner spins up sample projects
– Verifies that code generation completes and output matches expected structure
c. Architectural patterns & design principles
- SBT Plugin API pattern: define SettingsKey, TaskKey, AutoPlugin to hook into build lifecycle
- Separation of concerns:
– Keys/Settings definition (OpenAPIGeneratorKeys)
– Plugin wiring (OpenAPIGeneratorPlugin)
– External engine invocation (wrapping OpenAPI Generator CLI)
– File and template management
- Extensibility: almost all aspects of generation are exposed via SBT settings, enabling end users to customize behavior or override templates.
d. Key technologies & libraries
- Scala & sbt `AutoPlugin` API
- openapi-generator (Java CLI / library)
- Mustache / Handlebars templating
- sbt‐scripted test runner

##### Final reminders
- Every key setting as an input to the plugin.
- Both local file and remote HTTP spec paths.
- Detail the optional post‐processing step.
- Sbt-test directory as a validation sub-system that verifies end-to-end behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "SBT Build Environment"
        buildSbt["build.sbt"]:::build
        versionSbt["version.sbt"]:::build
        buildProperties["project/build.properties"]:::build
        projectPlugins["project/plugins.sbt"]:::build
        travis[".travis.yml"]:::build
        scalafmt[".scalafmt.conf"]:::build
        license["LICENSE"]:::build
        readme["README.md"]:::build
    end

    subgraph "Plugin Layer"
        keys["OpenAPIGeneratorKeys"]:::build
        plugin["OpenAPIGeneratorPlugin"]:::build
        task["openapiGenerate Task"]:::build
    end

    subgraph "Engine Layer"
        engine["OpenAPI Generator Engine"]:::engine
        template["Template Engine (Mustache/Handlebars)"]:::engine
    end

    subgraph "I/O Layer"
        specFetch["Spec Fetch\n(local file / HTTP)"]:::io
        fileWrite["Write Generated Sources"]:::io
        postProcess["Post-Processing Module"]:::io
    end

    subgraph "Test Harness"
        remote["Remote Sample Project"]:::test
        simple["Simple Sample Project"]:::test
    end

    %% Connections
    buildSbt -->|"enables plugin"| plugin
    projectPlugins --> plugin
    versionSbt --> plugin

    plugin -->|"defines keys"| keys
    plugin -->|"registers task"| task

    task -->|"reads openapiInputSpec"| specFetch
    specFetch -->|"provides spec"| engine
    engine -->|"uses templates"| template
    template -->|"generates code"| engine
    engine --> postProcess
    postProcess --> fileWrite
    engine --> fileWrite

    remote -->|"runs scripted tests"| task
    simple --> task

    %% Click Events
    click buildSbt "https://github.com/upstart-commerce/sbt-openapi-generator/blob/master/build.sbt"
    click versionSbt "https://github.com/upstart-commerce/sbt-openapi-generator/blob/master/version.sbt"
    click buildProperties "https://github.com/upstart-commerce/sbt-openapi-generator/blob/master/project/build.properties"
    click projectPlugins "https://github.com/upstart-commerce/sbt-openapi-generator/blob/master/project/plugins.sbt"
    click travis "https://github.com/upstart-commerce/sbt-openapi-generator/blob/master/.travis.yml"
    click scalafmt "https://github.com/upstart-commerce/sbt-openapi-generator/blob/master/.scalafmt.conf"
    click license "https://github.com/upstart-commerce/sbt-openapi-generator/tree/master/LICENSE"
    click readme "https://github.com/upstart-commerce/sbt-openapi-generator/blob/master/README.md"
    click keys "https://github.com/upstart-commerce/sbt-openapi-generator/blob/master/src/main/scala/org/upstartcommerce/openapi/OpenAPIGeneratorKeys.scala"
    click plugin "https://github.com/upstart-commerce/sbt-openapi-generator/blob/master/src/main/scala/org/upstartcommerce/openapi/OpenAPIGeneratorPlugin.scala"
    click remote "https://github.com/upstart-commerce/sbt-openapi-generator/tree/master/src/sbt-test/sbt-openapi-generator/remote"
    click simple "https://github.com/upstart-commerce/sbt-openapi-generator/tree/master/src/sbt-test/sbt-openapi-generator/simple"

    %% Styles
    classDef build fill:#1f77b4,stroke:#333,stroke-width:1px,color:#fff
    classDef engine fill:#2ca02c,stroke:#333,stroke-width:1px,color:#fff
    classDef io fill:#ff7f0e,stroke:#333,stroke-width:1px,color:#000
    classDef test fill:#7f7f7f,stroke:#333,stroke-width:1px,color:#fff
```
