High-Level Architecture

Relevant source files

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

• README.md
• wiki/Home.md
• wiki/Modules.md
• scripts/api.php
• scripts/scripts.php
• AGENT_NOTES.md
• config/AGENT_NOTES.md

The IT Management System is a multi-tenant legacy PHP application designed to manage IT infrastructure, assets, employees, and financial data. It is built on a "zero external dependencies" philosophy, meaning it does not use Composer for PHP packages or NPM for JavaScript libraries, relying instead on vanilla JavaScript and core PHP features.

The architecture follows a modular approach where each business function (e.g., Equipment, IDFs, IPAM) is contained within a self-contained directory under the modules/ path. Request flow typically moves from web entry points through a shared core configuration into company-scoped MySQL data, supported by extensive audit logging for compliance.

Sources: README.md:144-150, AGENT_NOTES.md:4-7, wiki/Home.md:103-107

Core Tech Stack

The system is optimized for a specific runtime environment and avoids modern package managers to maintain a simplified, portable installation (e.g., Laragon-style).

Component	Technology / Version
Server Language	PHP 7.4.33
Database	MySQL 8.0+ (MySQLi implementation)
Web Server	Apache 2.4+
Frontend	Vanilla JavaScript + CSS
Architecture Pattern	Flat CRUD / Modular

Sources: README.md:162-171, wiki/Home.md:32-37

Request Flow and Multi-Tenancy

The application enforces strict multi-tenancy at the data layer. Every request is filtered by a company_id stored in the authenticated session. Data isolation is maintained because the client does not send the company_id in API payloads; the server resolves the tenant context automatically from the session.

High-Level Request Diagram

The following diagram illustrates how user requests interact with the shared core and database while maintaining tenant isolation.

Modular Structure

The system is divided into standard CRUD modules and specialized "bespoke" modules. Standard modules typically consist of an index.php (list view), create.php, edit.php, view.php, and delete.php.

Module Categorization

Category	Modules	Characteristics
Standard CRUD	Departments, Employees, Printers, Inventory	Follows a flat file structure; standard list/search/export.
Visual / Bespoke	Floor Designer, IDFs, Org Chart, Rack Planner	High interactivity; uses SVG/Canvas or custom JS for visual representations.
Data / Utils	Audit Logs, Settings, Scripts, Explorer	Handles system-wide utilities and file management.

Sources: wiki/Modules.md:10-30, scripts/api.php:107-133

Specialized "Protection Zones"

Certain modules, such as IDFs (Intermediate Distribution Frames), are designated as protection zones. They maintain high consistency across multiple tables (e.g., idf_positions, idf_ports, switch_ports, equipment) and must not be refactored into generic CRUD patterns without explicit requirements.

Sources: wiki/Modules.md:85-91, wiki/IDF-Synchronization.md:1-12

Data Persistence and Synchronization

The database schema uses core table relationships to maintain a multi-tenant model. Most tables include an active flag for soft deletion and a company_id for scoping.

IDF Synchronization Flow

The system manages complex relationships between physical rack positions and digital equipment records. When a port is updated or a link is created, the system synchronizes state across multiple entities.

Security Architecture

Security is integrated through several mandatory layers:

1. Session-based Authentication: Users must have a valid PHP session.
2. CSRF Protection: Mandatory csrf_token in the body or X-CSRF-Token header for all POST requests.
3. SQL Injection Prevention: Exclusive use of mysqli prepared statements for all database queries.
4. Static Audits: Scripts like check_csrf_coverage.php and check_sql_injection_coverage.php are used to maintain baseline security.

Sources: README.md:173-182, scripts/api.php:173-180, AGENT_NOTES.md:10-14

Administrative and Maintenance Infrastructure

The scripts/ directory serves as the administrative backbone of the application. It contains tools for database health, security audits, and automated testing.

• API Documentation: scripts/api.php provides an auto-generated reference of all JSON endpoints.
• Database Health: scripts/analyze_database_health.php runs ANALYZE TABLE across the schema.
• QA Runner: scripts/module_browser_qa_runner.php executes full-module regression tests across multiple companies.

Sources: scripts/scripts.php:38-45, scripts/api.php:10-25, scripts/AGENT_NOTES.md:4-10

Conclusion

The High-Level Architecture of the IT Management System emphasizes stability and simplicity through a zero-dependency, modular PHP design. By enforcing tenant isolation at the session level and utilizing a robust suite of maintenance scripts, the system provides a secure and scalable environment for multi-company IT asset management.

Sources: README.md:144-150, AGENT_NOTES.md:4-8