# raynorue/snich architecture

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

- Interactive diagram: https://gitdiagram.com/raynorue/snich
- Repository: https://github.com/raynorue/snich

## Overview

##### Project type and purpose
- This is a Visual Studio Code extension written in TypeScript.
- It integrates with ServiceNow via its REST API, letting users sync and edit ServiceNow application files in VSCode, run background scripts, compare with server, and provide IntelliSense for ServiceNow APIs.

##### File structure
- Top-level directories/files
- .github / ISSUE_TEMPLATE – issue templates and CI hooks
- docs / images – documentation, screenshots, GIFs
- SNCodeDefinitions – JSON files defining ServiceNow classes for IntelliSense
- src – core extension code
- webpack.config.js, tsconfig.json, package.json – build and dependency configs
- Inside src
- extension.ts – entry point, registers commands (Setup, Sync, Compare, OAuth, Background Script)
- classes/ – modules encapsulating each responsibility
– OAuth/OAuth.ts & URIHandlerCore.ts – handle OAuth “code” flow and callback listener
– RESTClient.ts – HTTP client adapter for ServiceNow REST endpoints
– SNRecordPuller.ts & SNRecordPusher.ts – fetch and push records to ServiceNow
– TSDefinitionGenerator.ts – generate TypeScript definitions from JSON
– InstanceConfigManager.ts & SNPreferencesManager.ts – manage local config and sync to sys_user_preference
– WebBrowser.ts – launch default browser for OAuth or opening ServiceNow records
– WorkspaceManager.ts & ExceptionFileOpener.ts – handle local file creation and errors
– ExtensionMgmt.ts & ConfigMigrator.ts – high-level orchestration, migrate old configs

##### Extract architecture insights from the README
- Command-driven flow via VSCode Command Palette
- Dual auth modes: Basic (username/password) and OAuth code flow (local HTTPS listener)
- Local persistence of instance and table configurations in workspace folders
- Use of webview panels for showing background script results
- TS IntelliSense powered by static JSON definitions

##### Main components
a. VSCode Extension Host
– extension.ts (registry of commands)
– Command modules (SetupInstance, ConfigureTable, SyncRecord, Compare, RunBackgroundScript)
b. Core Services (classes/)
– Authentication Service (OAuth, BasicAuth)
– RESTClient (HTTP adapter)
– Business Logic (SNRecordPuller/Pusher, TSDefinitionGenerator, ConfigManagers)
– Local FS & Workspace Manager
– WebBrowser Launcher & URIHandler (local HTTP server)
– Error Handling (ExceptionFileOpener, LogHelper)
c. External Systems
– ServiceNow REST API (cloud)
– Default Web Browser (for OAuth and “Open in Browser”)
– Local File System (workspace folder storing configs and synced files)
d. Static Assets
– SNCodeDefinitions JSON (IntelliSense schemas)

##### Relationships and data flows
- User issues a command in VSCode → extension.ts routes to appropriate class
- Classes delegate to RESTClient (with OAuth or Basic credentials) → ServiceNow API
- Data returned → Business Logic parses and writes files via WorkspaceManager → local FS
- OAuth flow spins up URIHandlerCore listener, WebBrowser opens SN auth page, callback returns token
- TSDefinitionGenerator reads SNCodeDefinitions → writes .d.ts files for IntelliSense

##### Architectural patterns and design principles
- Modular separation: one class per concern (authentication, HTTP, file I/O, config)
- Adapter/Facade over ServiceNow REST (RESTClient hides raw HTTP)
- Command pattern for VSCode commands
- Single source of truth for instance/table config, with sync to ServiceNow user preferences

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% VSCode API & UI Layer
    subgraph "VSCode API & UI"
        direction TB
        EXT["VSCode Extension Host / Command Registry"]:::internal
    end

    %% Business Logic Layer
    subgraph "Extension Business Logic"
        direction TB
        EM["High-Level Extension Orchestrator"]:::internal
        AUTH["Authentication Service (OAuth)"]:::internal
        URI["Local OAuth Callback Listener"]:::internal
        REST["HTTP Adapter (ServiceNow RESTClient)"]:::internal
        PULLER["Record Fetcher (SNRecordPuller)"]:::internal
        PUSHER["Record Pusher (SNRecordPusher)"]:::internal
        DEFGEN["TypeScript Definition Generator"]:::internal
        CONF["Instance Configuration Manager"]:::internal
        PREF["User Preferences Manager"]:::internal
        WS["Workspace File Manager"]:::internal
        ERR["Error File Opener / Handler"]:::internal
        MIG["Configuration Migrator"]:::internal
        BROW["External Browser Launcher"]:::internal
        LOG["Logging Helper"]:::internal
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        SNAPI["ServiceNow REST API"]:::external
        BROWSER["Default Web Browser"]:::external
        FS["Local File System"]:::storage
        SCHEMA["IntelliSense Schema Definitions"]:::storage
    end

    %% Relationships
    EXT -->|"triggers commands"| EM
    EM -->|"uses"| AUTH
    EM -->|"uses"| REST
    EM -->|"orchestrates"| PULLER
    EM -->|"orchestrates"| PUSHER
    EM -->|"runs"| DEFGEN
    EM -->|"manages"| CONF
    EM -->|"manages"| PREF
    EM -->|"handles files"| WS
    EM -->|"handles errors"| ERR
    EM -->|"migrates config"| MIG
    EM -->|"logs with"| LOG

    %% OAuth Flow
    AUTH -->|"opens auth page"| BROW
    BROW -->|"redirect to SN OAuth"| SNAPI
    SNAPI -->|"callback with code"| URI
    URI -->|"provides token to"| AUTH

    %% REST calls
    AUTH -->|"provides creds to"| REST
    REST -->|"GET/POST requests"| SNAPI
    SNAPI -->|"returns data"| REST

    %% Data flows
    PULLER -->|"fetch records via"| REST
    PUSHER -->|"push records via"| REST
    PREF -->|"sync prefs via"| REST
    REST -->|"data"| EM
    EM -->|"write files via"| WS
    WS -->|"store artifacts"| FS
    ERR -->|"open error files"| FS

    %% Definition Generation
    DEFGEN -->|"reads definitions"| SCHEMA
    DEFGEN -->|"writes .d.ts via"| WS

    %% Click Events
    click EXT "https://github.com/raynorue/snich/blob/master/src/extension.ts"
    click AUTH "https://github.com/raynorue/snich/blob/master/src/classes/OAuth/OAuth.ts"
    click URI "https://github.com/raynorue/snich/blob/master/src/classes/URIHandler/URIHandlerCore.ts"
    click REST "https://github.com/raynorue/snich/blob/master/src/classes/RESTClient.ts"
    click PULLER "https://github.com/raynorue/snich/blob/master/src/classes/SNRecordPuller.ts"
    click PUSHER "https://github.com/raynorue/snich/blob/master/src/classes/SNRecordPusher.ts"
    click DEFGEN "https://github.com/raynorue/snich/blob/master/src/classes/TSDefinitionGeneator.ts"
    click CONF "https://github.com/raynorue/snich/blob/master/src/classes/InstanceConfigManager.ts"
    click PREF "https://github.com/raynorue/snich/blob/master/src/classes/preferences/SNPreferencesManager.ts"
    click WS "https://github.com/raynorue/snich/blob/master/src/classes/WorkspaceManager.ts"
    click ERR "https://github.com/raynorue/snich/blob/master/src/classes/ExceptionFileOpener.ts"
    click EM "https://github.com/raynorue/snich/blob/master/src/classes/ExtensionMgmt.ts"
    click MIG "https://github.com/raynorue/snich/blob/master/src/classes/ConfigMigrator.ts"
    click BROW "https://github.com/raynorue/snich/blob/master/src/classes/WebBrowser.ts"
    click LOG "https://github.com/raynorue/snich/blob/master/src/classes/LogHelper.ts"
    click SCHEMA "https://github.com/raynorue/snich/tree/master/SNCodeDefinitions"
    
    %% Styles
    classDef internal fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef external fill:#ccffcc,stroke:#000,stroke-width:1px
    classDef storage fill:#ffe0b3,stroke:#000,stroke-width:1px
```
