FactHarbor Admin GUI Guide

Overview

The FactHarbor Admin GUI provides web-based interfaces for administrators to:

• Manage unified configuration (pipeline, search, calculation, prompts, SR)
• View and manage source reliability cache
• Test and validate API keys and service configurations

Admin Pages

Unified Configuration Management

Navigate to: http:~/~/localhost:3000/admin/config

The Unified Configuration Management system provides a single interface for managing all FactHarbor configurations with version history, validation, and export capabilities.

Configuration Types

Tabs

• Active: View currently active configuration with version info
• Edit: Modify configuration using form-based editors (JSON) or text editor (prompts)
• History: Browse all saved versions with activation status
• Effective (non-prompt): See resolved config (UCM is the source of truth; env overrides are disabled for analysis settings)

Features

Version Control

• Every saved configuration is immutable and content-addressed (SHA-256 hash)
• Full version history with timestamps and activation tracking
• One-click rollback to any previous version

Validation

• Real-time JSON schema validation for search/calculation configs
• Syntax highlighting and error markers for prompt editing
• Pre-save validation prevents invalid configurations

Export/Import

• Export any configuration as JSON or .prompt.md file
• Import configurations from files with schema validation

Environment Variables

Analysis settings (pipeline/search/calculation/SR) are managed in UCM. Environment variables are used
only for infrastructure and secrets (API keys, endpoints, cache paths). The Effective tab shows
the resolved config from UCM (no env overrides for analysis behavior).

Configuration Test Dashboard

Navigate to: http:~/~/localhost:3000/admin/test-config

Security (POC note)

The admin test UI calls GET /api/admin/test-config, which (currently) does not require authentication and can trigger paid LLM/search API calls if keys are configured.

• Keep this endpoint local-only during POC development.
• Before any public exposure, protect it with FH_ADMIN_KEY (and add rate limiting/cost quotas).

Configuration Test Dashboard

The Configuration Test Dashboard allows you to verify that all required API keys and services are working correctly.

Running Tests

1. Click the "Run All Tests" button
2. Wait for all tests to complete
3. Review the results

Test Results Summary

After running tests, you'll see a summary showing:

Test Statuses

Each service test returns one of the following statuses:

• Success - The service is properly configured and responding
• Error - The API key is invalid, expired, or the service is unreachable
• Not Configured - Required environment variables are missing
• Skipped - The service is not selected as the active provider

Services Tested

FactHarbor Core Services

LLM Providers

Only the currently selected LLM provider (via the pipeline config llmProvider) is actively tested. Others are marked as "Skipped".

Setting the LLM Provider:
Use Admin → Config → Pipeline and set llmProvider (anthropic/openai/google/mistral).

Search Providers

Search providers are tested when search is enabled in UCM and the provider is selected or auto-detection is enabled.

Setting the Search Provider:
Use Admin → Config → Web Search and set enabled + provider.

Troubleshooting

Common Issues

API Key contains placeholder text

Problem: The test shows "contains placeholder text" error.

Solution: Replace placeholder values like PASTE_YOUR_KEY_HERE, sk-..., or AIza... with actual API keys from the provider.

Service not configured

Problem: Required environment variables are missing.

Solution:

1. Add the required environment variables to apps/web/.env.local
2. Restart the development server (npm run dev)

Service skipped

Problem: The service shows as "Skipped".

Solution: This is normal if you're using a different provider. Update pipeline llmProvider or the UCM search provider if you want to use this service instead.

Connection errors

Problem: The service shows connection timeout or network errors.

Solution:

1. Check your internet connection
2. Verify the API key is valid by visiting the provider's configuration URL
3. Ensure no firewall or proxy is blocking the connection

Environment Variables Reference

Create or edit apps/web/.env.local with the following variables:

API Endpoint

The admin test functionality is also available via API:

Response:

Security Notes

• The admin pages should be protected in production environments
• API keys are never displayed in the UI, only validation status
• Test responses are minimal to avoid exposing sensitive data