How raynorue/snich works
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