Update Checking

Introduction

This document describes the update checking mechanism implemented in the Citadel dashboard to notify users when new versions are available. Keeping your software up to date is essential for security, performance, and access to new features.

Overview

The update checking mechanism consists of three main components:

• Backend Version Endpoint - A new API endpoint that returns the current version information
• Frontend Update Checker Service - A service that periodically checks for updates
• Update Notification Component - A UI component that displays update notifications to users

Implementation Details

Backend Version Endpoint

A new endpoint has been added to the backend server at /api/version that returns version information:

{
  "version": "1.0.0",
  "name": "@citadel/core",
  "timestamp": "2025-11-27T19:11:52.181Z"
}

This endpoint reads version information directly from the package.json file.

Frontend Update Checker Service

The UpdateChecker service in frontend/src/services/update-checker.ts provides the following functionality:

• Periodically checks for updates by calling the backend version endpoint
• Compares the current version with the latest version
• Notifies subscribers when updates are available
• Provides methods to start/stop periodic checking

Update Notification Component

The UpdateNotification component in frontend/src/shared/components/UpdateNotification.tsx displays a notification to users when updates are available. It includes:

• A bell icon to indicate an update is available
• Information about the new version
• Buttons to update now or dismiss the notification

How It Works

1. When the dashboard loads, the UpdateNotification component initializes
2. The component sets up the UpdateChecker service to check for updates
3. The service immediately checks for updates and then continues checking periodically
4. When an update is found, the notification is displayed
5. Users can click "Update Now" to go to the releases page or "Dismiss" to hide the notification

Configuration

The update checking mechanism can be configured through environment variables:

• VITE_API_BASE_URL - The base URL for API calls (defaults to http://localhost:3000)
• Check interval - How often to check for updates (defaults to 1 hour)

Security Considerations

• The version endpoint only returns non-sensitive information
• All communication between frontend and backend is secured through HTTPS in production
• The update checker does not automatically download or install updates

Testing

To test the update checking mechanism:

1. Ensure the backend server is running
2. Start the frontend development server
3. The update checker will automatically check for updates when the dashboard loads
4. To simulate an update, modify the version in backend/package.json to a higher version number

Future Enhancements

Possible future enhancements to the update checking mechanism:

• Automatic update downloads and installation
• Changelog display in the notification
• Different notification levels (critical security updates, feature updates, etc.)
• Integration with package managers for automatic updates