# enricodeleo/aquasdk architecture

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

- Interactive diagram: https://gitdiagram.com/enricodeleo/aquasdk
- Repository: https://github.com/enricodeleo/aquasdk

## Overview

##### Main Components
- CLI/Entry Point: The tool is intended to be run as a command-line utility. The entry point is exposed via commands like “generate-sdk” (invoked from the command line) that trigger the processing workflow.
- OpenAPI Specification Input: This is the input file (e.g., swagger.json) provided by the user. It is the starting point for the SDK generation process.
- Preprocessor (src/preprocessor.js): This component is responsible for reading and resolving any complexities in the OpenAPI spec (such as circular references or nested data structures) to prepare it for code generation.
- Generator (src/generator.js): After preprocessing, this component coordinates the code generation. It reads the preprocessed API definition and directs the generation process.
- Template Engine (src/templates folder): This includes the Handlebars templates (e.g., client.hbs, model.hbs, index.hbs, resource.hbs, readme.hbs, and additional utility templates) that define the structure of the generated SDK files.
- Utilities (src/templates/utils): Contains helper functions (like queryUtils.js) that support the template rendering or the generated SDK's functionality.
- Output SDK: The final output is a directory structure (for example, “./sdk”) containing the generated JavaScript files which realize the API methods, models, and chainable query methods for interacting with the API.

##### Mapping Relationships and Interactions
- The user supplies an OpenAPI JSON file as input.
- The CLI/Entry Point passes the specification to the Preprocessor.
- The Preprocessor cleans and augments the spec, passing the resulting data to the Generator.
- The Generator coordinates with the Template Engine to render the corresponding files (using the .hbs templates) for each model, method, and utility.
- The rendered output (JavaScript SDK components) is then written to the user-specified output directory.

##### Important Architectural Patterns and Design Principles
- Separation of Concerns: Different files (or modules) handle distinct responsibilities (e.g., input processing, pre-processing of spec data, code generation, and template rendering).
- Pipeline Architecture: The process flows in stages—from receiving the OpenAPI spec to transforming it into a fully-functional SDK—allowing easier modifications or expansions at each stage.
- Template-Driven Code Generation: Use of Handlebars as a templating engine ensures a clean separation between the “logic” (data handling) and the “presentation” (generated code structure).

##### Relevant Technologies and Frameworks
- Node.js and JavaScript: The tool itself is built in JavaScript, utilizing Node.js.
- Handlebars: Employed for creating dynamic templates that generate the SDK source code.
- NPM and related configuration files (e.g., package.json, eslint.config.js): These facilitate package management, linting, and consistent coding standards.
- Git & GPL License: Indicating open-source collaboration and licensing terms.

##### What
- CLI/Command-Line Interface (Invokes generate-sdk command)
- Input Handler (Reads OpenAPI spec file)
- Preprocessor (src/preprocessor.js)
- Generator (src/generator.js)
- Template Engine (src/templates: list out client.hbs, model.hbs, etc.)
- Utility Helpers (src/templates/utils)
- Output (Generated SDK structure with chainable API method classes and configurations)
- Input → Preprocessor → Generator → Template Engine → Output.
- Processing modules (Preprocessor, Generator).
- Template files (grouped under one component).
- External elements (the original OpenAPI spec and the final generated SDK).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "SDK Generation Pipeline"
        CLI["CLI/Command-Line Interface"]:::processing
        Spec["OpenAPI Specification (swagger.json)"]:::external
        Preprocessor["Preprocessor"]:::processing
        Generator["Generator"]:::processing
        TemplateEngine["Template Engine"]:::template
        UtilityHelpers["Utility Helpers"]:::template
        Output["Generated SDK"]:::external

        CLI -->|"providesSpec"| Spec
        Spec -->|"parsedBy"| Preprocessor
        Preprocessor -->|"processedData"| Generator
        Generator -->|"rendersWith"| TemplateEngine
        UtilityHelpers -->|"supports"| TemplateEngine
        TemplateEngine -->|"writesTo"| Output
    end

    click CLI "https://github.com/enricodeleo/aquasdk/blob/main/src/index.js"
    click Preprocessor "https://github.com/enricodeleo/aquasdk/blob/main/src/preprocessor.js"
    click Generator "https://github.com/enricodeleo/aquasdk/blob/main/src/generator.js"
    click TemplateEngine "https://github.com/enricodeleo/aquasdk/tree/main/src/templates"
    click UtilityHelpers "https://github.com/enricodeleo/aquasdk/tree/main/src/templates/utils"

    classDef processing fill:#f9c,stroke:#333,stroke-width:2px;
    classDef template fill:#ccf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
```
