# mattplant/suitetools architecture

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

- Interactive diagram: https://gitdiagram.com/mattplant/suitetools
- Repository: https://github.com/mattplant/suitetools

## Overview

##### Project type and purpose
- This is a full-stack monorepo called *SuiteTools*—a set of missing NetSuite tools.
- The **frontend** is a React/TypeScript/Vite Single-Page App that you host in NetSuite’s File Cabinet.
- The **backend** is a set of SuiteScript 2.x modules (Suitelet, REST API script, Map/Reduce scripts) deployed via the SuiteCloud Development Framework (SDF) into your NetSuite account.

##### File structure
- Top-level directories:
- **backend/** contains SDF configuration (suitecloud.config.js, deploy.xml, manifest.xml), XML definitions for custom records & scripts, TypeScript sources under `src/TypeScripts/SuiteTools`, File Cabinet templates under `src/FileCabinet`, and Jest tests.
- **frontend/** contains a Vite + React + Tailwind CSS app with routes, API wrappers, components, pages, and build configs (vite.config.ts, tsconfig.json).

##### README for additional insights
- Built from the [NetSuite-TypeScript-SDF](https://github.com/mattplant/NetSuite-TypeScript-SDF) template.
- Deployment uses the SDF CLI to push both frontend assets (to File Cabinet) and backend SuiteScripts into your NetSuite account.
- The primary entry point is a Suitelet script (“SuiteTools App”) that either serves the SPA or functions as an API gateway.

- **Labels**: e.g., “Suitelet App Script,” “REST API Script,” “Map/Reduce Jobs,” “File Cabinet (SPA Assets),” “NetSuite Records.”
- Code → SDF CLI → NetSuite
- Browser → Suitelet → SuiteScripts → NetSuite Records → response → Browser
- Green rectangles for frontend (SPA assets, React components)
- Blue rectangles for backend SuiteScripts (Suitelet, API, Map/Reduce)

##### Capturing essential architectural elements
- Frontend components by feature (Concurrency, Files, Jobs, etc.) rather than listing each file.
- Clearly separate static hosting (File Cabinet) from compute (SuiteScript).
- SDF config files (suitecloud.config.js, deploy.xml, manifest.xml) to indicate “Infrastructure as Code.”
- Call out that the Suitelet doubles as both the UI server and API gateway.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer/CI Layer
    subgraph "Developer/CI"
        direction TB
        GitRepo["Git Repository"]:::ci
        Build["npm run build\n(tsc + vite build)"]:::ci
        SDFCLI["SDF CLI"]:::ci
        SDFConfig[suitecloud.config.js\ndeploy.xml\nmanifest.xml]:::ci
        GitRepo -->|push code| Build
        Build -->|compile & bundle| SDFCLI
        SDFConfig --> SDFCLI
    end

    %% NetSuite Platform Layer
    subgraph "NetSuite Platform"
        direction TB
        subgraph "File Cabinet (Static Hosting)"
            direction TB
            FC_Live["Live Hosting Files"]:::datastore
            FC_Staging["Staging Hosting Files"]:::datastore
        end
        subgraph "SuiteScripts (Compute)"
            direction TB
            SuiteletApp["Suitelet App Script"]:::backend
            SuiteletXML["Suitelet Definition XML"]:::backend
            RESTAPI["REST API Script"]:::backend
            RESTAPIXML["REST API Definition XML"]:::backend
            subgraph "Map/Reduce Scripts"
                direction TB
                MR_JobsRun["Jobs Run MR Script"]:::backend
                MR_JobsRunXML["Jobs Run MR Definition XML"]:::backend
                MR_Logins["Logins MR Script"]:::backend
                MR_LoginsXML["Logins MR Definition XML"]:::backend
            end
            Helpers["Common Helpers Module"]:::backend
        end
        subgraph "Data Storage"
            direction TB
            NetSuiteRecords["NetSuite Records"]:::datastore
        end
        SDFCLI -->|deploy static assets| FC_Live
        SDFCLI -->|deploy SuiteScripts| SuiteletApp
        SDFCLI --> SuiteletXML
        SDFCLI --> RESTAPI
        SDFCLI --> RESTAPIXML
        SDFCLI --> MR_JobsRun
        SDFCLI --> MR_JobsRunXML
        SDFCLI --> MR_Logins
        SDFCLI --> MR_LoginsXML
        SDFCLI --> Helpers
        SuiteletApp -->|serve SPA| FC_Live
        SuiteletApp -->|route API calls| RESTAPI
        SuiteletApp -->|invoke| MR_JobsRun
        SuiteletApp -->|invoke| MR_Logins
        SuiteletApp -->|use| Helpers
        RESTAPI -->|read/write| NetSuiteRecords
        MR_JobsRun -->|batch operations| NetSuiteRecords
        MR_Logins -->|batch operations| NetSuiteRecords
    end

    %% Browser Layer
    subgraph "End User Browser"
        direction TB
        Browser["Browser (SPA)"]:::frontend
    end
    Browser -->|load index.html| FC_Live
    Browser -->|XHR/fetch| SuiteletApp
    RESTAPI -->|JSON response| Browser
    SuiteletApp -->|JSON response| Browser

    %% Frontend Layer (within Browser context)
    subgraph "Frontend SPA"
        direction TB
        EntryPoint["index.html\n(main entry)"]:::frontend
        AppRoot["main.tsx\nindex.css"]:::frontend
        Routes["Routes.tsx"]:::frontend
        Pages["Pages Directory"]:::frontend
        Components["Components Directory"]:::frontend
        APIWrapper["API Wrapper\n(api.ts, types.ts)"]:::frontend
        BuildConfig["vite.config.ts\ntsconfig.json\npackage.json"]:::frontend
        EntryPoint --> AppRoot
        AppRoot --> Routes
        Routes --> Pages
        Pages --> Components
        Components --> APIWrapper
        BuildConfig --> EntryPoint
    end

    %% Click Events
    click SuiteletApp "https://github.com/mattplant/suitetools/blob/main/backend/src/TypeScripts/SuiteTools/idev-suitetools-app.ts"
    click SuiteletXML "https://github.com/mattplant/suitetools/blob/main/backend/src/Objects/customscript_idev_suitetools_app.xml"
    click RESTAPI "https://github.com/mattplant/suitetools/blob/main/backend/src/TypeScripts/SuiteTools/idev-suitetools-api.ts"
    click RESTAPIXML "https://github.com/mattplant/suitetools/blob/main/backend/src/Objects/customscript_idev_suitetools_api.xml"
    click MR_JobsRun "https://github.com/mattplant/suitetools/blob/main/backend/src/TypeScripts/SuiteTools/helpers/idev-suitetools-mr-jobs-run.ts"
    click MR_JobsRunXML "https://github.com/mattplant/suitetools/blob/main/backend/src/Objects/customscript_idev_suitetools_mr_jobs_run.xml"
    click MR_Logins "https://github.com/mattplant/suitetools/blob/main/backend/src/TypeScripts/SuiteTools/helpers/idev-suitetools-mr-logins.ts"
    click MR_LoginsXML "https://github.com/mattplant/suitetools/blob/main/backend/src/Objects/customscript_idev_suitetools_mr_logins.xml"
    click Helpers "https://github.com/mattplant/suitetools/blob/main/backend/src/TypeScripts/SuiteTools/idev-suitetools-common.ts"
    click SDFConfig "https://github.com/mattplant/suitetools/blob/main/backend/suitecloud.config.js"
    click SDFConfig "https://github.com/mattplant/suitetools/blob/main/backend/src/deploy.xml"
    click SDFConfig "https://github.com/mattplant/suitetools/blob/main/backend/src/manifest.xml"
    click FC_Live "https://github.com/mattplant/suitetools/tree/main/backend/src/FileCabinet/Web Site Hosting Files/Live Hosting Files"
    click FC_Staging "https://github.com/mattplant/suitetools/tree/main/backend/src/FileCabinet/Web Site Hosting Files/Staging Hosting Files"
    click EntryPoint "https://github.com/mattplant/suitetools/blob/main/frontend/index.html"
    click BuildConfig "https://github.com/mattplant/suitetools/blob/main/frontend/vite.config.ts"
    click BuildConfig "https://github.com/mattplant/suitetools/blob/main/frontend/tsconfig.json"
    click BuildConfig "https://github.com/mattplant/suitetools/blob/main/frontend/package.json"
    click AppRoot "https://github.com/mattplant/suitetools/blob/main/frontend/src/main.tsx"
    click AppRoot "https://github.com/mattplant/suitetools/blob/main/frontend/src/index.css"
    click Routes "https://github.com/mattplant/suitetools/blob/main/frontend/src/Routes.tsx"
    click Pages "https://github.com/mattplant/suitetools/tree/main/frontend/src/pages"
    click Components "https://github.com/mattplant/suitetools/tree/main/frontend/src/components"
    click APIWrapper "https://github.com/mattplant/suitetools/blob/main/frontend/src/api/api.ts"
    click APIWrapper "https://github.com/mattplant/suitetools/blob/main/frontend/src/api/types.ts"
    click Test1 "https://github.com/mattplant/suitetools/blob/main/backend/__tests__/sample-test.js"
    click Test2 "https://github.com/mattplant/suitetools/blob/main/backend/jest.config.js"

    %% Styles
    classDef ci fill:#f2f2f2,stroke:#ccc
    classDef frontend fill:#ccffcc,stroke:#2d662d
    classDef backend fill:#cce5ff,stroke:#0054a6
    classDef datastore fill:#ffddcc,stroke:#cc5200
```
