# flexbase-eng/openapi-generator architecture

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

- Interactive diagram: https://gitdiagram.com/flexbase-eng/openapi-generator
- Repository: https://github.com/flexbase-eng/openapi-generator

## Overview

This project is an OpenAPI code generator—designed to take an OpenAPI specification (written in YAML format) and produce typescript server code (or similar) using Handlebars templates. Its purpose is to automate the generation of API server components such as routers, models, routes, and validations, with considerable support for customization via configuration files and external templates.

##### Main Components
- CLI / Entry Point: The project begins with entry modules like src/index.ts, src/main.ts, and src/build.ts that initialize the process.
- Configuration Component: This loads and interprets the configuration settings (via .openapigenerator.json, package.json scripts, and command-line options).
- Parser Layer: Responsible for reading and converting OpenAPI specifications. It consists of a factory (openapi.parser.factory.ts) and various specific parsers (openapi.parser.ts, openapi.v3.parser.ts, openapi.v3_1.parser.ts) along with related modules to produce a “parsed document” representation.
- Optimizer Layer: After parsing, the data flows into the optimizer (src/optimizer) which contains several node types (e.g., array.ts, object.ts, operation.ts, etc.) to build an “optimized document”. This optimizes and perhaps organizes the parsed data for easier template consumption.
- Template Engine (Generation Layer): Uses Handlebars templates (located in the templates directory) to transform the optimized representation into output code. The “build” process uses the supplied templates for generating routers, models, routes, validations, etc.
- Utilities and Helpers: Contains various utility functions (e.g., chalk.logger, openapi.utilities.ts, records.ts) that are used throughout the parsing, optimizing, and generation steps.
- Testing and CI: The tests directory (and .github workflows) indicate automated testing and continuous integration pipelines validating the functionality and quality of the generator.

##### Relationships and Interactions
- Data Flow: The process starts from reading an OpenAPI YAML file (input) which is fed into the Parser. The Parser produces a parsed representation that is sent to the Optimizer for structural improvements. The Optimized Document is then passed to the Template Engine to generate code.
- CLI triggers the pipeline: The main entry point coordinates the pipeline using given configuration options (e.g., include globs, sharedTemplates, debugPath).
- Templates are treated as contracts: They define how the optimized content is rendered, with partials (included under templates/server) being reused to create composite code files.
- Utility modules: These are referenced across various layers to handle tasks like logging, hashing, and formatting.
- External Services: Although they aren’t explicitly integrated with external web services, the project relies on external dependencies (Handlebars, Prettier, etc.) and build/CI services (GitHub Actions defined in the .github/workflows folder).

##### Architectural Patterns and Design Principles
- Layered Architecture: The separation between parsing, optimization, and generation ensures modularity.
- Template-Based Code Generation: Utilizes Handlebars for flexible and customizable output generation.
- Configuration-Driven Behavior: The behavior of file generation and formatting is driven by a JSON configuration file that dictates which templates to use and how to format output locations.
- Testing and CI Integration: Automated tests and workflows suggest an emphasis on continuous quality and integration.

##### Specific Technologies & Frameworks
- Node.js (implied by the package.json and .ts file extensions)
- Handlebars for templating.
- Prettier (config options in the configuration) for formatting generated code.
- GitHub Actions for CI/CD (with workflows present in .github/workflows).
- OpenAPI standards (v3 and v3.1 parsers, references to OpenAPI spec in usage).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Overall Pipeline
    Input["OpenAPI Spec (YAML)"]:::input
    Output["Generated Code"]:::output

    %% CLI / Entry Point Subgraph
    subgraph "CLI / Entry Point"
        a1["src/index.ts"]:::cli
        a2["src/main.ts"]:::cli
        a3["src/build.ts"]:::cli
    end

    %% Configuration Component Subgraph
    subgraph "Configuration Component"
        conf1[".openapigenerator.json"]:::config
        conf2["src/runtime.config.ts"]:::config
    end

    %% Parser Layer Subgraph
    subgraph "Parser Layer"
        p1["src/parser/openapi.parser.factory.ts"]:::parser
        p2["src/parser/openapi.parser.ts"]:::parser
        p3["src/parser/openapi.v3.parser.ts"]:::parser
        p4["src/parser/openapi.v3_1.parser.ts"]:::parser
    end

    %% Optimizer Layer Subgraph
    subgraph "Optimizer Layer"
        o1["src/optimizer/openapi.optimizer.ts"]:::optimizer
        o2["src/optimizer/nodes"]:::optimizer
    end

    %% Template Engine (Generation Layer) Subgraph
    subgraph "Template Engine"
        t1["templates/server"]:::generation
    end

    %% Utilities & Helpers Subgraph
    subgraph "Utilities & Helpers"
        u1["src/utilities"]:::utilities
        u2["src/chalk.logger.ts"]:::utilities
        u3["src/handlerbars.ts"]:::utilities
    end

    %% Testing and CI Subgraph
    subgraph "Testing & CI"
        test1["tests"]:::testing
        test2[".github/workflows"]:::testing
    end

    %% Data Flow Connections
    Input -->|"reads"| a1
    a1 -->|"triggers"| conf1
    conf1 -->|"configures"| p1
    p1 -->|"produces parsedDoc"| o1
    o1 -->|"creates optimizedDoc"| t1
    t1 -->|"generates"| Output

    %% Support Connections (dotted lines)
    u1 --- p1
    u1 --- o1
    u1 --- t1
    u2 --- p1
    u2 --- o1
    u2 --- t1
    u3 --- p1
    u3 --- o1
    u3 --- t1

    test1 --- a1
    test2 --- a1

    %% Click Events for CLI / Entry Point
    click a1 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/index.ts"
    click a2 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/main.ts"
    click a3 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/build.ts"

    %% Click Events for Configuration Component
    click conf1 "https://github.com/flexbase-eng/openapi-generator/blob/main/.openapigenerator.json"
    click conf2 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/runtime.config.ts"

    %% Click Events for Parser Layer
    click p1 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/parser/openapi.parser.factory.ts"
    click p2 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/parser/openapi.parser.ts"
    click p3 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/parser/openapi.v3.parser.ts"
    click p4 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/parser/openapi.v3_1.parser.ts"

    %% Click Events for Optimizer Layer
    click o1 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/optimizer/openapi.optimizer.ts"
    click o2 "https://github.com/flexbase-eng/openapi-generator/tree/main/src/optimizer/nodes"

    %% Click Events for Template Engine
    click t1 "https://github.com/flexbase-eng/openapi-generator/tree/main/templates/server"

    %% Click Events for Utilities & Helpers
    click u1 "https://github.com/flexbase-eng/openapi-generator/tree/main/src/utilities"
    click u2 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/chalk.logger.ts"
    click u3 "https://github.com/flexbase-eng/openapi-generator/blob/main/src/handlerbars.ts"

    %% Click Events for Testing & CI
    click test1 "https://github.com/flexbase-eng/openapi-generator/tree/main/tests"
    click test2 "https://github.com/flexbase-eng/openapi-generator/tree/main/.github/workflows"

    %% Styles
    classDef input fill:#EFEFEF,stroke:#333,stroke-width:2px;
    classDef output fill:#EFEFEF,stroke:#333,stroke-width:2px;
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef config fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef parser fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef optimizer fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef generation fill:#B0E0E6,stroke:#333,stroke-width:2px;
    classDef utilities fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef testing fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
