Settings & System Maintenance
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Settings & System Maintenance system serves as the central administrative hub for the IT Management platform. It encompasses system-wide configuration, UI customization, sidebar management, and critical database maintenance operations. This system is designed to provide administrators with the tools necessary to tailor the user experience, ensure data integrity, and manage lifecycle backups for multi-tenant environments.
The scope of this module includes managing UI persistence through the ui_configuration table, handling user-specific sidebar preferences, and executing server-side maintenance tasks such as schema verification and SQL-based backup/recovery. Access to these features is strictly controlled via role-based permissions, typically requiring Admin, IT Manager, or IT Assistant privileges to perform destructive or high-impact actions.
Sources: modules/settings/index.php:12-20, modules/settings/AGENT_NOTES.md:4-7, wiki/Modules.md:65-74
UI Configuration and Customization
The system allows for extensive customization of the application's interface. Administrators can define the positioning of key UI elements, such as action buttons and navigation links, and set global defaults for pagination and application naming.
Component Logic and Data Flow
UI configuration changes are persisted to the ui_configuration table, which is scoped by company_id to ensure tenant isolation. When a user updates these settings, the frontend utilizes JavaScript to collect state from interactive elements (like the sidebar reorder list) and populates hidden form fields before submission.
The diagram above shows the flow from administrative input to the persistence and eventual rendering of UI settings.
Sources: modules/settings/index.php:382-446, modules/settings/AGENT_NOTES.md:14-16
Configuration Parameters
| Parameter | Type | Description | Default/Options |
|---|---|---|---|
table_actions_position | String | Position of CRUD actions in tables | Left, Right, Left & Right |
new_button_position | String | Position of the "+ New" button | Left, Right, Left & Right |
export_buttons_position | String | Alignment of export toolbars | Top/Bottom, Left/Right |
records_per_page | Mixed | Default pagination limit | 25, 50, 100, ALL |
app_name | String | Custom title for the application | IT Management |
favicon_path | String | Path to the tenant-specific .ico file | images/favicons/company_X.ico |
Sources: modules/settings/index.php:31-72, modules/settings/index.php:115-119
Sidebar and Navigation Management
The sidebar is dynamically generated based on a combination of default structure and user-defined preferences stored in user_sidebar_preferences. Administrators can toggle the visibility of specific modules and reorder both main sections and submenu items.
Sidebar Reordering Logic
The interface provides up/down (↑/↓) buttons for each item. The logic handles:
- Moving main sections globally.
- Moving submenu items within a section.
- Moving submenu items between different main sections.
Sources: modules/settings/index.php:418-446, wiki/Modules.md:76-78
Equipment Type Emojis
A unique feature within settings is the ability to map specific emojis to equipment types for sidebar display. This is managed via the equipment_types table and can be customized per tenant.
Sources: modules/settings/index.php:82-101, modules/settings/AGENT_NOTES.md:11-12
Database Maintenance and Backups
The maintenance system provides essential tools for database health and disaster recovery. These operations are categorized into schema verification, sample data seeding, and SQL dump management.
Backup and Restore Workflow
The backup system generates standard SQL files that include CREATE TABLE and INSERT statements, while temporarily disabling foreign key checks to ensure smooth restoration.
The sequence diagram illustrates the process of generating a scoped SQL backup for a specific tenant.
Sources: modules/settings/index.php:143-228, modules/settings/AGENT_NOTES.md:17-18
Maintenance Tools Summary
| Tool Action | Description | Risk Level |
|---|---|---|
create_system_tables | Verifies and creates missing ui_configuration or system-specific tables. | Low (Idempotent) |
add_sample_data_all_tables | Seeds all empty tables using literals from database.sql. | Medium (Data Addition) |
import_backup | Executes raw SQL from an uploaded file to restore database state. | High (Destructive) |
delete_backup | Removes existing .sql files from the backups/ directory. | Low (Cleanup) |
Sources: modules/settings/index.php:449-484, scripts/scripts.php:305-320
Security and Access Control
Maintenance tools are heavily guarded due to their potential impact on system stability and data security.
- Role Restrictions: Only users with
adminor specificit managerroles can access backup/restore functionality. - CSRF Protection: Every POST action in the settings module requires a valid
csrf_token. - File Validation: Favicon uploads are limited to
.icofiles under 512KB. SQL imports are restricted to.sqlextensions. - CLI Guard: Certain destructive scripts in the
scripts/directory, likerepair_table_from_schema.php, are guarded withPHP_SAPI !== 'cli'to prevent unauthorized web execution.
Sources: modules/settings/index.php:127-141, modules/settings/index.php:383, scripts/scripts.php:322-325
Script-Based Administration
Beyond the web UI, the scripts/ directory contains standalone utilities for advanced maintenance and troubleshooting.
| Script | Purpose |
|---|---|
analyze_database_health.php | Runs ANALYZE TABLE on all tables to identify "doesn't exist in engine" errors. |
verify_database_schema.php | Compares the live information_schema against database.sql. |
force_delete_company.php | Completely removes a company and all associated data, bypassing FK checks. |
api.php | Serves as the HTML reference for JSON API endpoints and module import routes. |
Sources: scripts/scripts.php:285-300, scripts/api.php:15-25, README.md:155-165
Conclusion
The Settings & System Maintenance module is a critical infrastructure component of the IT Management System. By providing a unified interface for UI configuration, sidebar personalization, and database operations, it empowers administrators to maintain a robust and customized environment. The integration of maintenance scripts ensures that technical debt such as schema drift or data corruption can be addressed proactively, while the backup system provides a necessary safety net for multi-tenant data management.