Architecture

Architecture

FreeITSM is a classic LAMP-style web application: PHP server-side with vanilla JS/HTML/CSS on the client. No frameworks, no build step. All 18 modules share a common chrome (waffle menu, header, user account dropdown) but each module is self-contained under its own folder.

Technology Stack

Component	Technology
Backend	PHP 7.4–8.4
Database	MySQL 8.0+ via PDO MySQL
Frontend	Vanilla JavaScript, HTML5, CSS3
Rich text editing	TinyMCE 6+
Email integration	Microsoft Graph API + Gmail API (OAuth 2.0)
Encryption at rest	AES-256-GCM for sensitive values
AI features	Pluggable providers — Anthropic Claude / OpenAI / OpenRouter, per-feature keys (AI Providers) + OpenAI embeddings (Knowledge)
Web server	Apache (WAMP/XAMPP/LAMP) or any PHP server

Directory Layout

freeitsm/
├── config.php                        # References external db_config.php
├── index.php                         # Module selection grid (landing page)
├── .htaccess                         # URL routing: /login canonical, legacy redirects, MultiViews off — see Root-Folder-Tidy
│
├── auth/                             # Auth pages (served via root .htaccess rewrites — see Root-Folder-Tidy)
│   ├── login.php                     # Analyst login — canonical URL /login
│   ├── analyst_logout.php            # Logout handler (also aliased as /logout)
│   ├── force_password_change.php     # Forced password change (expired passwords)
│   ├── forgot-password.php           # Password reset request — /forgot-password
│   ├── reset-password.php            # Password reset (token from email) — /reset-password
│   ├── oauth_callback.php            # Microsoft OAuth 2.0 callback (URL unchanged: /oauth_callback.php)
│   └── google_oauth_callback.php     # Google OAuth 2.0 callback (URL unchanged: /google_oauth_callback.php)
│
├── api/                              # ~140 REST endpoints, one folder per module
│   └── v1/                           # Public REST API v1 (API-key auth) — see the REST API pages
│
├── assets/
│   ├── css/                          # Shared stylesheets — inbox.css (core layout), theme.css (palette tokens), per-module css
│   ├── js/                           # Shared scripts — inbox.js, i18n.js, tz.js, toast.js, safe-html.js, qrcode.min.js (MFA QR codes), … + TinyMCE library
│   └── images/                       # CompanyLogo.png (replace with your own)
│
├── includes/                         # Shared PHP components
│   ├── functions.php                 # connectToDatabase() + analyst module helpers
│   ├── waffle-menu.php               # Cross-module nav + user account menu
│   ├── encryption.php                # AES-256-GCM helpers
│   ├── totp.php                      # Pure-PHP TOTP / HOTP (RFC 6238 / 4226)
│   ├── i18n.php                      # Translation helper — see the Internationalisation page
│   ├── timezone.php                  # Per-analyst display timezone — see Timezones & Time Handling
│   ├── theme.php                     # Palette registry — see Theming & Dark Mode
│   ├── rbac.php                      # Capability guards — see Roles & Permissions
│   ├── tenancy.php                   # Company scoping — see Multi-Tenancy
│   ├── gmail.php / mailbox_graph.php / mailbox_imap.php   # Mailbox providers (Gmail API / MS Graph / basic IMAP-SMTP)
│   ├── template_email.php            # Automated email templates for ticket events
│   ├── module-colors.php             # Module colour definitions
│   └── services/                     # Shared service layer — see Service Layer Architecture
│
├── lang/                             # Translations, one folder per locale
│
├── tickets/                          # Ticket Management module
│   ├── index.php                     # Three-panel inbox interface
│   ├── users.php                     # User directory & their tickets
│   ├── calendar.php                  # Ticket scheduling calendar
│   ├── rota.php                      # Staff rota weekly grid
│   ├── csat/                         # CSAT analytics (index.php) + the public survey page (survey.php — canonical URL /csat)
│   ├── settings/                     # Departments, types, origins, statuses, priorities, SLA, mailboxes, rota shifts
│   └── attachments/                  # Email attachment storage (gitignored)
│
├── asset-management/                 # Asset Management module
│   ├── dashboard/                    # Per-analyst widget dashboard (Chart.js)
│   ├── servers/                      # vCenter VM inventory with detail modal
│   └── settings/                     # vCenter connection settings
│
├── knowledge/                        # Knowledge Base — index.php (article list & editor), review/ (review workflow), settings/
├── change-management/                # Changes — index.php, calendar.php (scheduled changes), approvals.php, settings/
├── calendar/                         # Calendar — index.php (full calendar view), settings/ (event categories)
├── morning-checks/                   # Morning Checks — daily check interface with PDF export
├── reporting/                        # Reporting — logs/ (logins, email imports), tickets/ (ticket dashboards)
├── software/                         # Software — inventory, dashboard/ (widgets + library.php), licences/, settings/ (API keys)
├── forms/                            # Forms — edit/ (form editor), fill.php (A4-style filler), submissions.php, settings/
├── lms/                              # LMS — index.php (dashboard), player.php (SCORM player), content/ (uploaded packages)
├── process-mapper/                   # Process Mapper — visual flowchart editor
├── network-mapper/                   # Network Mapper — index.php (diagrams landing), diagram.php (per-diagram editor)
├── tasks/ · contracts/ · cmdb/ · problem-management/ · workflow/     # Further modules, same shape
├── service-status/ · system-wiki/ · watchtower/ · self-service/     # (index.php + settings/ + includes/)
│
├── system/                           # System module (administrators only)
│   ├── analysts/                     # Analyst accounts (passwords, SSO, teams, per-company access, admin role)
│   ├── teams/                        # Team management (used across tickets, tasks, contracts, workflows)
│   ├── modules/                      # Analyst module access control
│   └── encryption/                   # Encryption key management
│
├── browser-extension/                # Chrome/Edge Watchtower extension (Manifest V3) — see Browser Extension
├── cron/                             # Scheduled jobs (SLA breach checks, webhook deliveries, scheduled workflows)
├── scripts/                          # CLI utilities + background workers (Intune sync workers, asset inventory agent)
├── database/
│   └── freeitsm.sql                  # Schema bootstrap
├── docs/                             # Design docs (e.g. cmdb.md)
└── setup/                            # Setup verification / diagnostic page (delete after going live)

Each module folder typically contains:

• index.php — landing page
• settings/index.php — module config
• help.php — in-app guided help page (scroll-spy sidebar, sectioned content)
• includes/header.php — module's header bar with its colour gradient and nav tabs

Shared Components

Waffle Menu (includes/waffle-menu.php)

A Microsoft 365-style app launcher in the header of every module page. Each module is registered with a name, path, icon SVG, and colour gradient. Respects $_SESSION['allowed_modules'] to filter visible modules per analyst.

Also contains the user account menu — an initials avatar circle in the top-right of every page. Clicking opens a dropdown with:

• Change Password (validates current, min 8 chars)
• Multi-Factor Authentication (TOTP setup/disable with QR code)
• Logout (with confirmation)

To add a new module, add an entry to the $modules array and matching CSS.

TOTP (includes/totp.php)

Pure-PHP implementation of RFC 6238 (TOTP) and RFC 4226 (HOTP). No external dependencies — uses PHP's built-in hash_hmac() and random_bytes().

• Secret generation: 20 random bytes → Base32 (32-char string)
• Code generation: HMAC-SHA1, 30-second time step, dynamic truncation → 6-digit code
• Verification: ±1 time window (90-second tolerance), hash_equals() for timing-safe compare
• URI format: otpauth://totp/FreeITSM:{username}?secret={base32}&issuer=FreeITSM

Secrets are encrypted at rest with AES-256-GCM before being stored in analysts.totp_secret.

Encryption (includes/encryption.php)

AES-256-GCM authenticated encryption for sensitive database values.

• Key file: C:\wamp64\encryption_keys\sdtickets.key (outside web root)
• Format: ENC: + base64(IV + auth tag + ciphertext)
• Migration-safe: Values without ENC: prefix pass through unchanged

$encrypted = encryptValue($plaintext);
$plaintext = decryptValue($encrypted);
$mailbox = decryptMailboxRow($mailbox);

Encrypted columns include:

• system_settings: vcenter_*, knowledge_ai_api_key, knowledge_openai_api_key, intune_*
• target_mailboxes: azure_tenant_id, azure_client_id, azure_client_secret, oauth_redirect_uri, imap_server, target_mailbox, plus imap_username, imap_password and smtp_server for basic IMAP/SMTP mailboxes
• analysts.totp_secret

The canonical lists live in the ENCRYPTED_SETTING_KEYS and ENCRYPTED_MAILBOX_COLUMNS constants in includes/encryption.php — a system_settings key or mailbox column is only encrypted/decrypted if it appears there.

A subset of "true secrets" listed in MASKED_SETTING_KEYS are also masked to ****<last4> in API responses, with a save-time convention that blank or asterisk-prefixed submissions mean "leave unchanged" so the user can save the form without re-typing.

Module Header Pattern

Each module's includes/header.php:

1. Checks session auth (redirects to login if missing)
2. Sets $current_module for waffle-menu highlighting
3. Renders the header bar with the module's colour gradient
4. Includes the waffle button, module nav tabs, and user account avatar

Module Page Pattern

Every module page follows the same skeleton — set $current_page and $path_prefix before the markup, pull in the shared stylesheet and the module header, and define an API_BASE constant for the page's JavaScript:

<?php
session_start();
require_once '../config.php';
$current_page = 'module_name';
$path_prefix = '../';
?>
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="../assets/css/inbox.css">
    <!-- Module-specific styles in a <style> block -->
</head>
<body>
    <?php include 'includes/header.php'; ?>
    <div class="main-container module-container">
        <!-- Module content -->
    </div>
    <script>
        const API_BASE = '../api/module_name/';
        // Module JavaScript
    </script>
</body>
</html>

Adding a New Module

1. Create the module folder with index.php and includes/header.php
2. Create an API folder under api/
3. Register it in includes/waffle-menu.php (add to the $modules array + CSS colours)
4. Add a card to the index.php landing page (icon, colour, link)
5. Add any new tables to database/freeitsm.sql and the Database Verification schema

Toast Notifications (assets/js/toast.js)

Global notification system. Four types: success (green), error (red), warning (amber), info (blue). 9 configurable screen positions via visual grid picker in System Settings → General. Position persisted per-browser in localStorage. Slide-in animations, auto-dismiss after 4s, manual close button.

i18n (includes/i18n.php, assets/js/i18n.js, lang/)

Native multi-language support with a t('namespace.path.to.key') call pattern in both PHP and JavaScript. The first dot-separated segment of the key maps to a file (lang/<locale>/<namespace>.php); everything after walks a nested PHP array inside that file.

return [
    'toolbar' => [
        'process'  => 'Prozess',
        'decision' => 'Entscheidung',
    ],
];

Fallback is per key, not per file. If lang/de/tickets.php has 80% of keys translated, you get 80% in German and the missing 20% in English. Last-resort behaviour returns the key itself so unfilled strings are visible during development.

Locale resolution chain: logged-in analyst's interface_language user preference → browser Accept-Language header (with primary-subtag matching — pt resolves to pt-BR) → 'en' default. Selectable in System → Preferences; on change, persists to user_preferences and reloads the page.

JS bridge: each page declares the namespaces it needs ($translationNamespaces = ['common', 'process-mapper']) and PHP renders window.translations with English fallback already merged into the active locale per key. The JS t() helper does a flat dotted walk — no fallback logic on the client.

Supported locales (20 as of May 2026): en, af, fr, de, es, pt-BR, nl, it, pl, ru, id, hi, bn, ta, te, mr, kn, ml, gu, pa. BCP 47 codes match the HTML lang attribute. Spans Europe (en/fr/de/es/pt-BR/nl/it/pl/ru), South Africa (af — Afrikaans), South Asia (the nine Indian languages), and Indonesia (id — Bahasa Indonesia). Adding a new language is a 2-step code change: add to I18n::SUPPORTED_LOCALES (with native-script display name), and drop .php translation files into lang/<code>/. The System → Preferences dropdown picks the new locale up automatically.

Translated modules: Process Mapper was the pilot; Tickets and Tasks are now fully translated end-to-end (PHP pages and JavaScript) across all 20 locales. Remaining modules follow in phased sweeps — the infrastructure is the hard part and it's done.

Database Conventions

• MySQL 8.0+ with AUTO_INCREMENT for primary keys
• $conn->lastInsertId() to retrieve new IDs after INSERT
• Foreign keys with cascading where ownership is real (e.g. cmdb_objects.parent_id cascade-deletes descendants) — but delete endpoints also remove children explicitly rather than trusting cascades, because installs grown via Database Verification may lack backfilled FKs. Full story, delete-rule conventions, orphan-hunting SQL and the schema-change checklist: Database Integrity
• Soft delete via is_active flags rather than physical deletion for user-facing records
• Datetime columns: created_datetime, last_modified_datetime, etc. (PHP-side defaults)

API Pattern

All endpoints live under api/<module>/ and return JSON. Every endpoint starts with:

session_start();
require_once '../../config.php';
require_once '../../includes/functions.php';

header('Content-Type: application/json');

if (!isset($_SESSION['analyst_id'])) {
    echo json_encode(['success' => false, 'error' => 'Not authenticated']);
    exit;
}

See API Reference for a per-module endpoint summary.

Business logic belongs in a shared service, not in the endpoint. These UI endpoints and their REST API v1 counterparts are thin adapters over a per-module service class, so a rule is written once and can't drift between the UI and the API. If you add a feature with both a UI action and an API endpoint, read Service Layer — one implementation, two interfaces first (rollout status: progress tracker).

AI Integration Pattern

AI features share a single provider-agnostic building block — drop renderAiSettingsPanel('<ns>') on a settings page and call aiProviderChat() in the backend. Each feature is configured independently with its own provider (Anthropic / OpenAI / OpenRouter), model and key, kept separate for granular billing visibility:

Feature	Namespace	Settings location
Knowledge AI chat	knowledge_ai	Knowledge → Settings → AI
Reply Cleanup	tickets_reply_cleanup	Tickets → Settings → Reply Cleanup
Form generation	forms_ai	Forms → Settings → AI
CMDB AI summary + Suggest Properties	cmdb_ai	CMDB → Settings → AI Integration
Workflow co-author	workflow_ai	Workflows → Settings → AI
RFP Builder	(deferred)	Contracts → Settings → RFP AI

All keys are encrypted at rest. Most AI features stream output via SSE (claude.ai-style live tokens) for long-running calls. OpenRouter adds a single key reaching hundreds of models across vendors. See AI Providers for the full reference.

File Locations Quick Reference

Need to...	Look in...
Add a new module	Module folder + api/ + includes/waffle-menu.php + index.php
Change the database connection	db_config.php (outside the web root, referenced from config.php), includes/functions.php
Add an encrypted setting	includes/encryption.php → ENCRYPTED_SETTING_KEYS or ENCRYPTED_MAILBOX_COLUMNS
Modify cross-module navigation	includes/waffle-menu.php
Change the landing page	index.php
Modify the ticket inbox	tickets/index.php, assets/js/inbox.js
Configure vCenter	asset-management/settings/, api/assets/get_vcenter.php
Manage knowledge AI	knowledge/settings/, api/knowledge/ai_chat.php
Design forms	forms/index.php, api/forms/save_form.php
View form submissions	forms/submissions.php, api/forms/get_submissions.php
Manage the encryption key	system/encryption/, api/system/check_encryption.php
Configure module access	system/modules/, api/system/save_analyst_modules.php
Account menu (avatar / password / MFA)	includes/waffle-menu.php → renderHeaderRight(), api/myaccount/
MFA login challenge	auth/login.php (canonical URL /login), api/myaccount/verify_login_otp.php
TOTP implementation	includes/totp.php