Storage & File Management

Relevant source files

The following files were used as context for generating this wiki page:

• modules/explorer/AGENT_NOTES.md
• modules/floor_plans/AGENT_NOTES.md
• README.md
• scripts/api.php
• wiki/Home.md
• modules/floor_designer/AGENT_NOTES.md
• wiki/Modules.md

The Storage & File Management system in the IT Management platform provides a multi-tenant, web-based infrastructure for handling assets, documents, and system-generated files. It is characterized by strict multi-tenant isolation, department-level scoping, and specialized galleries for technical drawings like floor plans.

Sources: modules/explorer/AGENT_NOTES.md:4, README.md:143, wiki/Home.md:12

1. System Architecture & Isolation

The system implements physical and logical isolation to ensure data security in a multi-company environment. Files are stored in specific root directories, further partitioned by company_id.

Physical Storage Structure

Files are organized into three primary top-level directories within the project root:

• files/{company_id}/: General purpose storage managed by the Explorer module.
• floor_plans/{company_id}/: Dedicated storage for building layouts and AutoCAD files.
• images/: Specifically for equipment and employee photo uploads.

Sources: modules/explorer/AGENT_NOTES.md:15, modules/floor_plans/AGENT_NOTES.md:14, README.md:95-98

Logical Scoping

The Explorer module provides three visibility tiers for files within a company:

• Common: Accessible to all users within the company.
• Department: Restricted to users belonging to a specific department.
• Private: Restricted solely to the file owner.

Sources: modules/explorer/AGENT_NOTES.md:8-11

The diagram shows the hierarchical structure of the file system and how multi-tenancy is applied at the directory level.
Sources: modules/explorer/AGENT_NOTES.md:15, modules/floor_plans/AGENT_NOTES.md:14

2. Explorer Module

The Explorer module acts as the primary file manager, providing metadata tracking in the database while maintaining physical files on disk.

Key Components

• Metadata Tracking: The explorer table tracks file ownership, paths, and metadata.
• Path Safety: Filenames and paths are sanitized to prevent directory traversal attacks.
• Async Operations: Handled via modules/explorer/api.php for actions like renaming and moving.

Sources: modules/explorer/AGENT_NOTES.md:6-26, scripts/api.php:143

API Operations

Action	Endpoint	Purpose
File Management	modules/explorer/api.php	Rename, delete, move, and upload files.
File Delivery	modules/explorer/file.php	Securely serves files for download.
Setup	modules/explorer/setup.php	Initializes company-specific storage directories.

Sources: modules/explorer/AGENT_NOTES.md:20-23, scripts/api.php:143

3. Floor Plans & Technical Documents

Floor Plans is a specialized module for managing building drawings. It supports high-density file types and hierarchical organization.

Supported File Types

The system handles specific formats required for IT infrastructure planning:

• Images: JPEG, PNG, GIF, WebP.
• Documents: PDF.
• CAD: AutoCAD formats including DWG, DXF, DWF, and DWS.
• Size Limit: Standardized at 20MB per file.

Sources: README.md:145, modules/floor_plans/AGENT_NOTES.md:16

Data Relationships

Floor plans can be optionally linked to it_locations to provide spatial context for IT assets. They also serve as the background layer for the interactive Floor Designer tool.

Sources: modules/floor_plans/AGENT_NOTES.md:12, modules/floor_designer/AGENT_NOTES.md:11

The ER diagram illustrates the relationships between floor plan metadata, folders, and organizational entities.
Sources: modules/floor_plans/AGENT_NOTES.md:7-12

4. Security and Path Validation

Security is enforced through mandatory company_id scoping in all SQL queries and physical path construction.

Code Pattern for Safe Retrieval

The system uses prepared statements to ensure that file metadata is never accessed outside of the current user's company context.

// Example of scoped file retrieval
$stmt = $conn->prepare("SELECT * FROM explorer WHERE company_id = ? AND folder_path = ?");
$stmt->bind_param("is", $companyId, $folderPath);
$stmt->execute();

Sources: modules/explorer/AGENT_NOTES.md:32-36

Security Constraints

• Path Traversal Prevention: Every folder_path and file_name is validated against the defined storage_root.
• MIME Validation: File types are checked upon upload to prevent execution of malicious scripts.
• CSRF Protection: All file mutation requests (POST) require a valid CSRF token.

Sources: modules/explorer/AGENT_NOTES.md:28-30, README.md:214

5. Implementation Summary

Module	Storage Path	Primary Table	Key Feature
Explorer	files/{company_id}/	explorer	Department-level isolation
Floor Plans	floor_plans/{company_id}/	floor_plans	AutoCAD and PDF support
Equipment	images/	equipment	Photo attachments for assets
Tickets	tickets_photos/	tickets	Evidence uploads for support

Sources: README.md:95-98, modules/explorer/AGENT_NOTES.md:15, modules/floor_plans/AGENT_NOTES.md:14

The Storage & File Management system provides a robust backbone for the IT Management platform, combining traditional file management with specialized workflows for technical drawings and asset documentation, all while maintaining rigorous multi-tenant security standards.