Axyom UI Starter Kit

A standalone server for Axyom customers that provides ready-to-use search interfaces powered by the Axyom Search API. Includes OIDC authentication, token management, and customizable UI views.

Features

Search Interfaces

• AI Search - Complete and component-based AI-powered search interfaces
• Classic Search - Traditional search with full functionality
• AI Chat - Interactive conversational search interface
• Unified Search - Tabbed interface combining AI and classic search
• Customizable Views - Bring your own HTML/CSS/JS to match your brand

Configuration & Management

• Web-based Configuration UI - Manage all settings through an intuitive web interface
• Persistent Configuration - Three-file reconciliation system for robust config management
• OIDC Authentication - Automatic token generation and caching
• Real-time Updates - See changes immediately when customizing views
• Configuration Reconciliation - Seamlessly merge infrastructure changes with UI customizations

Developer Experience

• Multiple Configuration Methods - JSON, .env, environment variables, or CLI
• CLI Interface - Easy server management from the command line
• RESTful API - Token and configuration endpoints
• Structured Logging - Configurable log levels with Pino
• Health Check Endpoints - Monitor server status
• Security Best Practices - Helmet.js, CSP, and secure defaults

Installation

npm init -y
npm install @axyom/ui-starter-kit

Quick Start

1. Create a configuration file axyom-credentials.json:

{
  "clientName": "your-client-name",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "issuerUrl": "https://keycloak.axyom.co/realms/REALM_NAME"
}

2. Start the server:

npx axyom-ui-starter-kit start

3. Open your browser to http://localhost:3000

You'll see the Axyom Search home page with links to:

• AI Search interfaces
• Classic Search interfaces
• Unified Search
• Configuration management

4. Customize your views (optional):
   • HTML view files for the demo views are placed in the folder in the current path
     • A custom views path may be set in server settings, on the settings page
   • Edit HTML, CSS, and JavaScript with your branding and styles
   • Changes are persisted across server restarts
   • To revert changes, delete the HTML file and restart the server. The default html file will be replaced in the views folder.

API Usage

Getting a Token

Once your server is running, you can retrieve an OAuth 2.0 access token for use with the Axyom Search API:

Endpoint: GET /auth/token

Example:

curl http://localhost:3000/auth/token

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "cached": true
}

The server automatically caches tokens and returns cached tokens when they're still valid. The cached flag is set to true when a cached token is returned.

Force Token Refresh

To bypass the cache and generate a fresh token:

Endpoint: POST /auth/token/refresh

Example:

curl -X POST http://localhost:3000/auth/token/refresh

Configuration

Getting Your Configuration File

When you become an Axyom customer, you'll receive an axyom-credentials.json file with your authentication credentials pre-configured. This file contains everything you need to get started with the Axyom UI Starter Kit.

Simply place this file in your project directory and start the server and it will automatically detect and use your credentials.

You can customize additional settings through the web UI at http://localhost:3000/config after starting the server. Any changes you make through the web UI will be saved and persist across server restarts.

Required Configuration

• clientName - Your Axyom client name
• clientId - Your OIDC client ID
• clientSecret - Your OIDC client secret
• issuerUrl - The OIDC issuer URL (e.g., https://keycloak.axyom.co/realms/REALM_NAME)

Optional Configuration

• classicSearchIndex - Search index name for classic search (required for classic search features)
• searchMode - Search mode: 'ai', 'classic', or 'both' (default: 'both')
• port - Server port (default: 3000)
• host - Host to bind to (default: 127.0.0.1)
• viewsPath - Custom views directory path (default: './views')
• logsPath - Logs directory path (default: './logs')
• tokenCacheTtl - Token cache TTL in seconds (default: auto-calculated from token expiry)
• logLevel - Logging level: debug, info, warn, error (default: info)

Configuration Methods

Method 1: Axyom Credentials File (axyom-credentials.json)

{
  "clientName": "your-client-name",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "issuerUrl": "https://keycloak.axyom.co/realms/REALM_NAME"
}

Method 2: Web UI (Recommended for Runtime Changes)

1. Start the server with initial configuration
2. Navigate to http://localhost:3000/config
3. Edit settings through the intuitive web interface
4. Changes are saved automatically and will be retained between sessions.
5. Click "Reset to Defaults" to revert to your original infrastructure config

Method 3: Environment Variables

export AXYOM_CLIENT_NAME=your-client-name
export AXYOM_CLIENT_ID=your-client-id
export AXYOM_CLIENT_SECRET=your-client-secret
export AXYOM_ISSUER_URL=https://keycloak.axyom.co/realms/SMUD
export AXYOM_CLASSIC_SEARCH_INDEX=your-search-index
axyom-ui-starter-kit start

Method 4: Environment File (.env)

AXYOM_CLIENT_NAME=your-client-name
AXYOM_CLIENT_ID=your-client-id
AXYOM_CLIENT_SECRET=your-client-secret
AXYOM_ISSUER_URL=https://keycloak.axyom.co/realms/SMUD
AXYOM_CLASSIC_SEARCH_INDEX=your-search-index
AXYOM_SEARCH_MODE=both
PORT=3000
HOST=127.0.0.1
AXYOM_VIEWS_PATH=./custom-views
AXYOM_LOGS_PATH=./logs
LOG_LEVEL=info
TOKEN_CACHE_TTL=6900

CLI Commands

start (default command)

Start the server.

axyom-ui-starter-kit start [options]

Options:
  -c, --config <path>      Path to configuration file (.json or .env)
  -p, --port <number>      Server port (overrides config)
  -h, --host <address>     Host to bind to (127.0.0.1 or 0.0.0.0)
  -l, --log-level <level>  Log level (debug|info|warn|error)

Examples:

# Start with default configuration
axyom-ui-starter-kit start

# Start with custom config file
axyom-ui-starter-kit start --config ./prod-config.json

# Start on custom port
axyom-ui-starter-kit start --port 8080

# Start with debug logging
axyom-ui-starter-kit start --log-level debug

config

Display current configuration with secrets masked.

axyom-ui-starter-kit config [options]

Options:
  -c, --config <path>  Path to configuration file (.json or .env)

Example:

axyom-ui-starter-kit config

health

Check if the server is running and healthy.

axyom-ui-starter-kit health [options]

Options:
  -u, --url <url>  Server URL (default: http://localhost:3000)

Example:

axyom-ui-starter-kit health --url http://localhost:8080

Web Interfaces

Once your server is running, navigate to http://localhost:3000 to access the web interface.

Home Page (/)

The landing page provides quick navigation to all available features:

• AI Search - Complete and component-based AI search interfaces
• Classic Search - Traditional search interfaces
• AI Chat - Interactive conversational search
• Unified Search - Tabbed interface combining AI and classic search
• Configuration - Web-based settings management

Search Views

AI Search - Complete (/app/ai-search-complete)

Full-featured AI-powered search interface with built-in styling and components.

AI Search - Components (/app/ai-search-components)

Modular AI search components for custom integration into your own layouts.

AI Chat (/app/ai-chat)

Interactive chat interface for conversational search experiences.

Classic Search - Complete (/app/classic-search-complete)

Traditional search interface with comprehensive functionality.

Classic Search - Components (/app/classic-search-components)

Component-based classic search for custom implementations.

Unified Search - Tabs (/app/unified-search-tabs)

Tabbed interface that combines both AI and classic search in one view.

Configuration Management (/config)

Web-based interface for managing all server settings:

• OIDC authentication credentials
• Search configuration (client name, index, mode)
• Server settings (port, host, log level)
• Custom paths (views, logs)
• Token cache configuration

All changes made through the web UI are automatically persisted and reconciled with your infrastructure configuration.

Health Check (/health)

JSON endpoint for monitoring server status, uptime, and token cache statistics.

Customizing Views

The Axyom UI Server allows you to customize the search interfaces to match your brand and requirements.

Setting a Custom Views Path

1. Navigate to the home page (http://localhost:3000)
2. Enter your desired views path in the "Customize Your Views" section
3. The server will copy default view files to your custom location
4. Edit the HTML, CSS, and JavaScript files to match your brand
5. Changes are automatically persisted across server restarts
6. To revert changes, simply delete the HTML file. It will be replaced by the default file.

View Files

All search interfaces are standard HTML files that you can customize:

• AiSearchComplete.html - Full AI search interface
• AiSearchComponents.html - Modular AI search components
• AiChat.html - Chat interface
• ClassicSearchComplete.html - Complete classic search
• ClassicSearchComponents.html - Classic search components
• UnifiedSearch-Tabs.html - Unified tabbed interface

Each file includes the Axyom Search SDK and can be modified to fit your design requirements.

Security Best Practices

Configuration Security

• Never commit axyom-credentials.json or .env files to version control
• Use the provided .gitignore to prevent accidental commits
• Store secrets in secure locations (e.g., environment variables, secret managers)
• Restrict file permissions on configuration files

Network Security

• Default: Server listens on 127.0.0.1 (localhost only)
• Production: Deploy behind a firewall, VPN, or reverse proxy
• Warning: Only bind to 0.0.0.0 if you understand the security implications
• No authentication is required for API endpoints (intended for internal network use)

Deployment Recommendations

1. Run behind a reverse proxy (nginx, Apache)
2. Use network-level security (VPN, private network)
3. Implement rate limiting at the proxy level
4. Monitor access logs
5. Rotate client credentials regularly

Logging

The server outputs structured logs to help you monitor and troubleshoot issues.

Log Levels

You can control logging verbosity by setting logLevel in your configuration:

• error - Only critical failures and startup errors
• warn - Warnings plus errors (e.g., token refresh issues, configuration problems)
• info - General information plus warnings and errors (default - server start, token generation)
• debug - Detailed information for troubleshooting (includes request details, cache operations)

Changing Log Level

Via Configuration File:

{
  "logLevel": "debug"
}

Via Web UI: Navigate to /config and update the "Log Level" field.

Via CLI:

axyom-ui-starter-kit start --log-level debug

Troubleshooting

Server won't start

1. Check configuration: axyom-ui-starter-kit config
2. Verify credentials are correct
3. Ensure OIDC issuer URL is accessible
4. Check port is not already in use

Token generation fails

1. Verify client credentials are valid
2. Check OIDC provider is accessible
3. Review logs with --log-level debug
4. Ensure correct issuer URL format

Cannot connect to server

1. Verify server is running: axyom-ui-starter-kit health
2. Check firewall settings
3. Ensure correct host/port configuration
4. Review network security settings

License

MIT

Author

SymSoft Solutions, LLC

Support

For issues and questions, please contact Axyom support or file an issue in the project repository.