Last updated: Sep 1, 2025, 01:10 PM UTC

Admin Settings & Disk Usage Implementation Plan

Overview

This document outlines the implementation plan for adding disk usage monitoring to system health and creating a comprehensive Admin Settings tab with configurable general settings.

Current State Analysis

Existing Infrastructure

  • System Health: Currently monitors CPU, memory, database, websocket, and Claude CLI status
  • Admin Features: AI provider configuration (Bedrock/Claude) exists in "AI Admin" tab
  • Upload Limit: Hardcoded at 50MB in server/index.js line 192
  • Settings Storage: system_config table exists for configuration persistence

Missing Features

  • No disk usage monitoring in system health
  • No general configuration settings for admins
  • Upload size limit not configurable
  • No session management settings
  • No maintenance mode or debug controls

Implementation Tasks

1. Disk Usage Monitoring

Backend Changes (server/index.js)

  • Add disk usage calculation to /api/health endpoint (around line 405-437)
  • Use Node.js child_process.exec to run df -h command
  • Parse output to get disk statistics
  • Monitor key directories:
    • /tmp (temporary uploads)
    • /app/workspaces (user workspaces)
    • /app/uploads (file uploads)
    • / (root filesystem)

Frontend Display (src/components/ToolsSettings.jsx)

  • Add disk usage section to System Health tab
  • Display with progress bars and color coding:
    • Green: < 70% used
    • Yellow: 70-85% used
    • Red: > 85% used
  • Show total, used, and available space

2. Admin Settings Tab Structure

New Tab in ToolsSettings.jsx

  • Add "General" tab between "System Health" and "AI Admin"
  • Admin-only visibility check
  • Include expandable information section

Settings Categories

File Management
  • Max Upload Size: Default 100MB, range 1MB-5GB
  • Max Workspace Size: Per-user quota, default 1GB
  • File Retention Period: Auto-cleanup for temp files, default 7 days
Session Management
  • Session Timeout: Auto-logout duration, default 24 hours
  • Max Concurrent Sessions: Per user limit, default 5
  • Auto-save Interval: Chat history save frequency, default 30 seconds
Performance & Limits
  • Rate Limiting: API calls per minute, default 60
  • Max Request Size: Overall request size limit
  • Connection Timeout: WebSocket timeout duration
System Controls
  • Debug Mode: Enable verbose logging
  • Maintenance Mode: System maintenance toggle
  • Analytics: Enable/disable usage analytics
  • Error Reporting: Detailed error logging

3. Database Schema Updates

Extend system_config table

-- Already exists, but ensure it can store JSON values
CREATE TABLE IF NOT EXISTS system_config (
  config_key TEXT PRIMARY KEY,
  config_value TEXT NOT NULL,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_by INTEGER REFERENCES users(id)
);

-- Add general_settings key with JSON value structure

Default Settings Structure

{
  "file": {
    "maxUploadSize": 104857600,  // 100MB in bytes
    "maxWorkspaceSize": 1073741824,  // 1GB in bytes
    "retentionDays": 7
  },
  "session": {
    "timeoutHours": 24,
    "maxConcurrent": 5,
    "autoSaveSeconds": 30
  },
  "performance": {
    "rateLimitPerMinute": 60,
    "maxRequestSize": 52428800,  // 50MB
    "connectionTimeout": 300000  // 5 minutes
  },
  "system": {
    "debugMode": false,
    "maintenanceMode": false,
    "analytics": true,
    "errorReporting": true
  }
}

4. Backend API Implementation

New Endpoints (server/routes/admin.js)

// GET /api/admin/general-settings
// Returns current general settings

// POST /api/admin/general-settings  
// Updates general settings

// POST /api/admin/general-settings/reset
// Reset to defaults

Settings Manager (server/config/generalSettings.js)

  • Create new module for general settings management
  • Functions: getSettings, updateSettings, resetSettings, validateSettings
  • Cache settings in memory with TTL
  • Apply settings on server startup

Dynamic Multer Configuration (server/index.js)

// Replace hardcoded limit with dynamic value
const getUploadLimit = () => {
  const settings = getGeneralSettings();
  return settings?.file?.maxUploadSize || 104857600; // 100MB default
};

const upload = multer({
  dest: '/tmp/uploads',
  limits: {
    fileSize: getUploadLimit()
  }
});

5. Frontend Components

GeneralSettingsTab Component

  • Form with sections for each category
  • Input validation and error handling
  • Save/Reset buttons
  • Success/error notifications
  • Loading states

UI Elements

  • Number inputs with min/max validation
  • Toggle switches for boolean settings
  • Tooltips explaining each setting
  • Unit converters (MB to bytes)
  • Visual feedback on changes

6. Implementation Order

  1. Phase 1: Disk Usage (Priority: High)

    • Add disk usage to health endpoint
    • Display in System Health tab
    • Test in Docker environment

  2. Phase 2: Settings Infrastructure (Priority: High)

    • Create general settings database structure
    • Implement backend API endpoints
    • Add settings management functions

  3. Phase 3: Upload Size Configuration (Priority: High)

    • Make multer limit dynamic
    • Add UI for upload size setting
    • Test with various file sizes

  4. Phase 4: Additional Settings (Priority: Medium)

    • Implement remaining settings
    • Add validation and defaults
    • Create reset functionality

  5. Phase 5: Polish & Testing (Priority: Low)

    • Add tooltips and help text
    • Improve error messages
    • Comprehensive testing

Testing Checklist

  • Disk usage displays correctly in Docker
  • Disk usage updates every 5 minutes
  • Upload size limit is enforced
  • Settings persist after server restart
  • Only admins can access settings
  • Invalid settings are rejected
  • Reset to defaults works
  • Settings apply without restart (where possible)
  • Error handling for disk command failures
  • Performance impact is minimal

Security Considerations

  • Admin-only access enforcement
  • Input validation for all settings
  • Sanitization of numeric inputs
  • Rate limiting on settings API
  • Audit logging of setting changes
  • Safe defaults for all settings

Migration Notes

  • Existing installations will use defaults
  • No breaking changes to existing functionality
  • Settings can be migrated via database backup

Future Enhancements

  • Export/import settings configuration
  • Per-organization settings (multi-tenant)
  • Setting profiles/templates
  • Scheduled maintenance windows
  • Automatic disk cleanup triggers
  • Setting change notifications
  • API for external configuration management

Files to Modify

  1. server/index.js - Disk usage calculation, dynamic multer config
  2. server/config/generalSettings.js - New file for settings management
  3. server/routes/admin.js - New endpoints for general settings
  4. src/components/ToolsSettings.jsx - Add General tab and disk usage
  5. src/components/admin/GeneralSettingsTab.jsx - New component
  6. server/database/init.sql - Ensure schema supports settings

Implementation Status: COMPLETED

Completion Criteria - All Met

  • Disk usage shows in System Health - Real filesystem usage with progress bars and color coding
  • Admin can modify upload size limit via UI - No restart required, immediate effect
  • Settings persist across Docker container restarts - Stored in database with JSON structure
  • All settings have reasonable defaults - 100MB upload, debug mode off, etc.
  • Documentation updated - Implementation guide and user documentation complete
  • No regression in existing functionality - All upload routes updated with backward compatibility

What Was Delivered

Phase 1: Core Features

  • Disk Usage Monitoring: Cross-platform disk space detection with df command, visual progress bars
  • Dynamic Upload Size: 1-5GB configurable range, applies immediately without restart
  • Settings Infrastructure: Complete backend API, frontend UI, database persistence

Files Modified

  1. server/config/systemConfig.js - Added general settings management functions
  2. server/index.js - Enhanced health endpoint, dynamic upload middleware
  3. server/routes/admin.js - New /api/admin/general-settings endpoints
  4. src/components/ToolsSettings.jsx - General Settings tab, disk usage display
  5. server/routes/files.js - Dynamic upload middleware
  6. server/routes/profile.js - Dynamic upload middleware (3 routes)

Testing Results

  • Server starts without errors
  • Settings UI accessible to admins only
  • Upload size changes apply immediately
  • Disk usage displays real percentages
  • All routes use dynamic middleware
  • Error handling works properly

Usage Instructions

For Administrators

  1. Access Settings: Login as admin → Settings → "General" tab
  2. Configure Upload Size:
    • Enter size in MB (1-5120 range)
    • Changes apply automatically to new uploads
    • Current size always displayed
  3. Monitor System Health:
    • View real disk usage with color-coded alerts
    • Green: <70%, Yellow: 70-85%, Red: >85%
    • Automatic refresh every 5 minutes

For Developers

  • Add New Settings: Extend DEFAULT_CONFIG in systemConfig.js
  • API Endpoints: Use /api/admin/general-settings for CRUD operations
  • Frontend: Settings automatically loaded in ToolsSettings.jsx
  • Validation: Server-side validation with clear error messages

Architecture Decisions Made

  1. Dynamic Upload Approach: Chose per-request multer creation over server restart requirement
  2. Cross-Platform Disk Usage: df command with Windows fallback and error handling
  3. Database Storage: JSON in system_config table for flexibility
  4. UI Integration: Added between System Health and AI Admin for logical flow
  5. Error Handling: Graceful degradation with default values when API calls fail

Future Enhancements Available

The infrastructure supports easy addition of:

  • Session timeout controls
  • Rate limiting configuration
  • Maintenance mode toggle
  • File retention policies
  • Workspace quotas
  • Analytics toggles

Implementation Date: August 23, 2025
Status: Production Ready