# oracle/netsuite-suitecloud-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/oracle/netsuite-suitecloud-sdk
- Repository: https://github.com/oracle/netsuite-suitecloud-sdk

## Overview

##### Project Type and Purpose
- This is a monorepo containing three related developer tools for the SuiteCloud ecosystem:
- SuiteCloud CLI (Node.js package)
- SuiteCloud VS Code Extension (TypeScript package)
- SuiteCloud Unit Testing Framework (Node.js package)
- All three packages live under “packages/” and share common metadata (e.g. uif-types, configuration files).
- Purpose: allow developers to create, manage, validate, deploy, and unit-test SuiteCloud customizations and SuiteApps against NetSuite accounts.

##### File Structure Analysis
- Top-level:
- .github, CI/CD configs (build_spec.yaml, sbom_generation.yaml)
- Root README, CONTRIBUTING, SECURITY, LICENSE
- packages/ (monorepo packages)
- packages/node-cli:
- src/commands (Command/Action/InputHandler/OutputHandler for account, file, object, project operations)
- core/ (CommandRegistrationService, CommandActionExecutor, SDK download/setup services)
- services/ (AccountFileCabinetService, FileSystemService, NpmInstallRunner, etc.)
- utils/, loggers/, metadata/, templates/, validation/
- postinstall.js, messages.json
- packages/vscode-extension:
- src/commands (VS Code command wrappers)
- src/core/sdksetup (SDK validation & installation)
- src/service (Translation, Messaging, Import/List services)
- startup (status bar, account warning)
- loggers, util, tests
- packages/unit-testing:
- jest-configuration, stubs (hundreds of SuiteScript stubs), services for running unit tests under Node, translation, file-system utils

##### README Insights
- Confirms three tools and links to npm and VS Code marketplace.

a. Main Components
1. CLI Subsystem
- Node.js process
- Core modules (command registration/execution)
- Commands/Actions/InputHandlers/OutputHandlers
- Services (Network, FileSystem, SDK Setup)
- Templates & Metadata
2. VS Code Extension Subsystem
- Runs in VS Code Extension Host
- Exposes UI commands & status bar items
- Delegates operations to CLI via embedded SuiteCloud Runner or direct module calls
- Translation & messaging service
3. Unit Testing Framework
- Jest-based runner
- SuiteScript stubs library
- Runner services (ProjectInfoService, UnitTestTranslationService)
4. Shared Artifacts
- uif-types package (TypeScript definitions)
- build/CI/CD pipelines
- Common configuration (ESLint, Prettier)
5. External Services
- Oracle SuiteCloud SDK downloads (SDK Download Service)
- NetSuite account endpoints (REST/SOAP)
- NPM registry (for CLI distribution)
b. Relationships & Data Flow
- Developer invokes CLI or VS Code command.
- CLI Core registers command → InputHandler gathers data → Action calls Services → Service makes HTTP calls or filesystem ops → ActionResult passed to OutputHandler → output displayed in console or IDE UI.
- VS Code Extension calls embedded SuiteCloud Runner which reuses CLI core modules or spawns CLI process; results streamed back to VS Code UI.
- Unit Testing runner loads stubs, reads project metadata, executes user tests via Jest, reports results.
- SDK Setup modules download SDK binaries from Oracle servers when needed.
c. Architectural Patterns & Principles
- Command Pattern: each CLI operation is encapsulated as Command, Action, InputHandler, OutputHandler.
- Inversion of Control / Dependency Injection: services are injected into actions.
- Modular, layered architecture: Core → Commands → Services → Utilities → Templates/Metadata.
- Extension Host integration: VS Code extension delegates to shared core logic to avoid duplication.
d. Key Technologies & Frameworks
- Node.js, npm
- TypeScript (VS Code Extension)
- Jest (Unit Testing)
- VS Code Extension API
- HTTP/HTTPS, ProxyAgent
- JSON metadata/configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Subsystem
    subgraph "CLI Subsystem"
        CLI_Commands["Commands"]:::cli
        CLI_Core["Core Modules"]:::cli
        CLI_Services["Services"]:::cli
        CLI_Utils["Utilities"]:::cli
        CLI_Loggers["Loggers"]:::cli
        CLI_Metadata["Metadata"]:::cli
        CLI_Templates["Templates"]:::cli
        CLI_Validation["Validation"]:::cli
        CLI_PostinstallScript["Post-install Script"]:::cli
        CLI_Messages["Messages"]:::cli
    end

    %% VS Code Extension Subsystem
    subgraph "VS Code Extension Subsystem"
        VS_Commands["Commands"]:::vs
        VS_CoreRunner["SuiteCloud Runner"]:::vs
        VS_SDKSetup["SDK Setup"]:::vs
        VS_Services["Services"]:::vs
        VS_Startup["Startup & Status Bar"]:::vs
        VS_Loggers["Loggers"]:::vs
        VS_Utils["Utilities"]:::vs
        VS_Types["Type Definitions"]:::vs
    end

    %% Unit Testing Framework
    subgraph "Unit Testing Framework"
        UT_JestConfiguration["Jest Configuration"]:::ut
        UT_JestTransformer["Jest Transformer"]:::ut
        UT_Services["Runner Services"]:::ut
        UT_Stubs["SuiteScript Stubs"]:::ut
        UT_FileUtils["File Utils"]:::ut
        UT_Constants["Application Constants"]:::ut
        UT_Exception["TestFrameworkException"]:::ut
        UT_Messages["Messages"]:::ut
    end

    %% Shared Artifacts
    subgraph "Shared Artifacts"
        Shared_Types["uif-types"]:::shared
        Shared_CICD["CI/CD & Config"]:::shared
    end

    %% External Systems
    subgraph "External Systems"
        API_SDK["Oracle SDK Server"]:::external
        API_Netsuite["NetSuite API"]:::external
        API_NPM["NPM Registry"]:::external
    end

    %% Developer Invocations
    Developer["Developer"]:::external
    Developer -->|uses| CLI_Commands
    Developer -->|uses| VS_Commands
    Developer -->|runs tests| UT_JestConfiguration

    %% CLI Flows
    CLI_Commands -->|registers calls| CLI_Core
    CLI_Core -->|invokes| CLI_Services
    CLI_Core -->|uses| CLI_Utils
    CLI_Core -->|logs via| CLI_Loggers
    CLI_Core -->|loads| CLI_Metadata
    CLI_Core -->|loads| CLI_Templates
    CLI_Core -->|checks| CLI_Validation
    CLI_PostinstallScript -->|writes| CLI_Messages

    CLI_Services -->|downloads via HTTP| API_SDK
    CLI_Services -->|calls| API_Netsuite
    CLI_Services -->|installs packages| API_NPM

    %% VS Code Extension Flows
    VS_Commands -->|delegates to| VS_CoreRunner
    VS_CoreRunner -->|calls| CLI_Core
    VS_CoreRunner -->|uses| VS_SDKSetup
    VS_Commands -->|uses| VS_Services
    VS_Commands -->|initializes| VS_Startup
    VS_Commands -->|logs via| VS_Loggers
    VS_Commands -->|uses| VS_Utils
    VS_Commands -->|references| VS_Types
    VS_Services -->|translates| VS_Commands

    %% Unit Testing Flows
    UT_JestConfiguration -->|transforms| UT_JestTransformer
    UT_JestTransformer -->|loads| UT_Services
    UT_Services -->|reads| UT_Stubs
    UT_Services -->|uses| UT_FileUtils
    UT_Services -->|uses| UT_Constants
    UT_Services -->|throws| UT_Exception
    UT_Services -->|reads| UT_Messages
    UT_Services -->|imports types| Shared_Types

    %% Shared Config
    CLI_Core -->|consumes| Shared_Types
    VS_CoreRunner -->|consumes| Shared_Types
    Shared_CICD -->|defines| CLI_Core
    Shared_CICD -->|defines| VS_CoreRunner
    Shared_CICD -->|defines| UT_JestConfiguration

    %% Click Events
    click CLI_Core "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/node-cli/src/core"
    click CLI_Commands "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/node-cli/src/commands"
    click CLI_Services "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/node-cli/src/services"
    click CLI_Utils "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/node-cli/src/utils"
    click CLI_Loggers "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/node-cli/src/loggers"
    click CLI_Metadata "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/node-cli/src/metadata"
    click CLI_Templates "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/node-cli/src/templates"
    click CLI_Validation "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/node-cli/src/validation"
    click CLI_PostinstallScript "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/packages/node-cli/postinstall.js"
    click CLI_Messages "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/packages/node-cli/messages.json"

    click VS_CoreRunner "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/packages/vscode-extension/src/core/SuiteCloudRunner.ts"
    click VS_SDKSetup "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/vscode-extension/src/core/sdksetup"
    click VS_Commands "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/vscode-extension/src/commands"
    click VS_Services "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/vscode-extension/src/service"
    click VS_Startup "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/vscode-extension/src/startup"
    click VS_Loggers "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/vscode-extension/src/loggers"
    click VS_Utils "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/vscode-extension/src/util"
    click VS_Types "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/vscode-extension/src/types"

    click UT_JestConfiguration "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/packages/unit-testing/jest-configuration/SuiteCloudJestConfiguration.js"
    click UT_JestTransformer "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/packages/unit-testing/jest-configuration/SuiteCloudJestTransformer.js"
    click UT_Services "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/unit-testing/services"
    click UT_Stubs "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/unit-testing/stubs"
    click UT_FileUtils "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/packages/unit-testing/utils/FileUtils.js"
    click UT_Constants "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/packages/unit-testing/ApplicationConstants.js"
    click UT_Exception "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/packages/unit-testing/TestFrameworkException.js"
    click UT_Messages "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/packages/unit-testing/messages.json"

    click Shared_Types "https://github.com/oracle/netsuite-suitecloud-sdk/tree/master/packages/uif-types"
    click Shared_CICD "https://github.com/oracle/netsuite-suitecloud-sdk/blob/master/build_spec.yaml"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085
    classDef vs fill:#d4edda,stroke:#155724
    classDef ut fill:#fff3cd,stroke:#856404
    classDef shared fill:#e2e3e5,stroke:#6c757d
    classDef external fill:#f5c6cb,stroke:#721c24
```
