ServiceNow Helper

AI-Powered ServiceNow Assistance Tool

Built with Next.js 16.1.1 • Multi-Provider AI Architecture • Security-First Design

---

An intelligent ServiceNow assistance tool featuring multi-agent AI architecture with multiple AI provider support that provides real-time streaming AI responses through an intuitive web interface and n8n workflow automation. Configure specialized agents with individual AI models from multiple providers (OpenRouter, Hugging Face) for optimized performance and cost flexibility.

Features

• Multi-Agent AI Architecture - 9 specialized AI agents (Orchestration, Planner, Coder, Architect, Process SME) with Large/Small variants and individual model configuration
• Multi-Provider Support - OpenRouter, Hugging Face, and extensible provider system for cost optimization
• Real-time Streaming - ChatGPT-like live response generation with Server-Sent Events (SSE)
• Voice Input - WhatsApp-style press-and-hold voice recording with automatic transcription and submission (iOS/Android/Desktop support)
• Custom AI Skills - Create tailored AI solutions for unique organizational challenges like intelligent triage and automated categorization
• Robust Security - JWT authentication, httpOnly cookies, comprehensive security headers
• Conversation Management - Full history tracking, search/filtering, session continuity
• Knowledge Store - Curated Q&A management with bulk operations and quality metrics
• Mermaid Diagrams - AI-generated flowcharts and diagrams with streaming support
• Answer Export - Export as Markdown or PDF with rendered diagrams
• Script Deployment - Send generated scripts directly to ServiceNow
• Modern UI - TailwindCSS 4.1, dark/light theme, PWA support, full accessibility
• Comprehensive Testing - 347 passing tests with Jest and Playwright

Quick Start

Prerequisites

 Node.js 22+
 Docker & Docker Compose
 Git

One-Click Setup with Docker

Step 1: Clone and configure

git clone https://github.com/your-username/servicenow-helper.git
cd servicenow-helper
cp .env.example .env
# Edit .env with your API keys

Step 2: Launch everything

# First time setup (includes configuration)
docker compose --profile setup up -d

# Subsequent runs
docker compose up -d

Access Points

Service	URL	Credentials
ServiceNow Helper	http://localhost:3000	admin / password123
n8n Workflow Manager	http://localhost:5678	admin@servicenow-helper.local / Admin123

New: Real-time streaming responses enabled by default, providing ChatGPT-like live response generation!

Voice Input: Press and hold the microphone button to record voice questions with automatic transcription. Configure voice settings in Settings → Voice Input. Note: iOS users should use Safari browser mode for voice features (PWA standalone mode not supported due to Apple restrictions).

Architecture

System Overview

graph TB
    subgraph "Frontend Layer"
        A[Next.js 15 App] --> B[React Components]
        B --> C[TailwindCSS]
        B --> D[TypeScript]
    end

    subgraph "Authentication Layer"
        E[JWT Middleware] --> F[Session Management]
    end

    subgraph "Backend Services"
        H[API Routes] --> I[n8n Workflows]
        H --> G[Streaming SSE]
        I --> J[AI Processing]
        G --> I
        H --> K[PostgreSQL]
    end

    subgraph "Multi-Provider AI Layer"
        L[Provider Manager] --> OR[OpenRouter]
        L --> HF[Hugging Face]
        L --> EX[Extensible Providers]
        OR --> M[Orchestration Agent]
        HF --> N[Planner Agent L/S]
        OR --> O[Coder Agent L/S]
        HF --> AR[Architect Agent L/S]
        OR --> SI[Process SME L/S]
    end

    subgraph "ServiceNow Integration"
        SN[ServiceNow Helper Companion App] --> T[Staging Tables]
        T --> U[ServiceNow Instance]
        I --> SN
    end

    A --> E
    H --> L
    J --> K

Loading

Core Components:

• Next.js 16.1.1 Frontend - User interface, authentication, streaming responses
• n8n Workflow Engine 1.118.2 - AI processing, multi-agent orchestration, ServiceNow integration
• PostgreSQL 15.x + pgvector 0.8.1 - Data persistence, vector search, user settings
• ServiceNow Companion App - Secure integration with ServiceNow instance
• AI Agent Version 3.1 - Latest AI agent architecture with enhanced capabilities

View Detailed Architecture Documentation

Usage

Getting Started

1. Login with your credentials
2. Configure settings via hamburger menu (agent models, providers, preferences, voice input)
3. Ask questions with real-time streaming responses (text or voice input)
4. Export answers as Markdown or PDF
5. Deploy scripts directly to ServiceNow
6. Manage knowledge store for curated Q&A pairs

Key Features

Multi-Agent Configuration:

• Navigate to Settings → Configure individual agents
• Select AI models per agent from multiple providers
• Filter by cost (Free/Paid) and capabilities (Multimodal)
• Optimize performance and cost

Question Types:

• Documentation - Comprehensive guides and reference materials
• Recommendation - Best practice advice and optimization suggestions
• Script - Code generation for Business Rules, Client Scripts, and Script Includes
• Troubleshoot - Debug and resolve issues with detailed analysis
• AI Agent - Build intelligent automation agents for workflow orchestration
• AI Skill - Create custom AI solutions tailored to unique organizational needs, such as intelligent triage, automated categorization, and process optimization

Multimodal Support:

• Attach images, PDFs, audio files
• AI analyzes screenshots, diagrams, error messages
• Configure multimodal capabilities in settings

Voice Input:

• WhatsApp-style press-and-hold recording interface
• Automatic speech-to-text transcription
• Configurable auto-submit behavior
• Cross-platform support (Desktop, Android, iOS Safari)
• iOS PWA limitation handling with clear user guidance

Script Deployment:

• One-click deployment to ServiceNow
• Business Rules, Script Includes, Client Scripts
• Real-time feedback with sys_id confirmation

Mermaid Diagrams:

• AI-generated flowcharts, sequence diagrams, ER diagrams
• Automatic rendering with theme support
• Export as code (Markdown) or images (PDF)

View Complete Usage Guide

Database Configuration

ServiceNow Helper uses PostgreSQL with comprehensive multi-provider and multi-agent support.

Key Tables:

• providers - AI provider configurations (OpenRouter, Hugging Face)
• agent_models - Agent-to-model mappings per user
• user_settings - User preferences and configuration
• ServiceNowSupportTool - Conversation history
• ai_models - Model definitions with capabilities

Automatic Setup:

docker compose --profile setup up -d

This automatically:

• Creates all database tables
• Seeds default providers (OpenRouter, Hugging Face)
• Runs agent model migration
• Configures multimodal capabilities

View Database Documentation

UI Design System

The application follows a modern, cohesive design system with glassmorphism, smooth animations, and full accessibility.

Key Design Principles:

• Chip-Style Buttons - Rounded-full with gradients, shadows, scale animations
• Pill-Style Badges - Consistent rounded badges for status indicators
• Modern Cards - Glassmorphism with backdrop-blur and colored shadows
• Interactive Elements - Smooth scale animations on all clickable elements
• Dark Mode Support - Complete theme support with semantic colors
• Accessibility - WCAG AA compliance, keyboard navigation, ARIA labels

View UI Design System Documentation

Testing

# Unit Tests
npm test                    # Watch mode
npm run test:ci             # CI/CD mode
npm run test:coverage       # With coverage

# Integration Tests
npm run test:e2e            # Headless
npm run test:e2e:ui         # Interactive UI
npm run test:e2e:debug      # Debug mode

Test Coverage:

• Authentication flows
• UI component interactions
• Cross-browser compatibility
• Performance validation

View Testing Documentation

Tech Stack

Frontend

Backend

Performance & Quality

AI & Security

Available Commands

Command	Description
npm run dev	Development server with hot reload
npm run build	Production build with PWA optimization
npm run build:analyze	Build with webpack bundle analyzer
npm run start	Production server
npm run lint	ESLint checks with auto-fix
npm run type-check	TypeScript validation
npm test	Jest unit tests (watch mode)
npm run test:coverage	Jest with coverage reports
npm run test:ci	Jest for CI/CD
npm run test:e2e	Playwright integration tests
npm run test:e2e:ui	Playwright with UI mode
docker compose up -d	Start all services
docker compose down	Stop all services

Documentation

Documentation	Description
Architecture Guide	System architecture, components, and data flow
Usage Guide	Complete feature documentation and workflows
Voice Mode Guide	Voice input features, platform support, and troubleshooting
UI Design System	Design principles and component patterns
Database Configuration	Database schema, setup, and management
Setup Guide	Installation and configuration
Environment Variables	Configuration reference
Development Guide	Development workflows and best practices
Testing Guide	Testing strategies and execution
PWA Guide	Progressive Web App features
Mermaid Diagrams	Diagram generation and export
Contributing	Contribution guidelines

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Bug reports and feature requests
• Code contributions and pull requests
• Documentation improvements
• Testing and quality assurance

License

MIT License

This project is licensed under the MIT License. See the LICENSE file for details.