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)
├── login.php                   # Analyst login
├── api/                        # ~140 REST endpoints, one folder per module
├── assets/
│   ├── css/                    # Shared stylesheets
│   ├── js/                     # Shared scripts + TinyMCE library
│   └── images/
├── 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)
│   └── module-colors.php       # Module colour definitions
├── database/
│   └── freeitsm.sql            # Schema bootstrap
├── docs/                       # Design docs (e.g. cmdb.md)
└── <module-folders>/           # tickets/, contracts/, cmdb/, ...

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
• analysts.totp_secret

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

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)
• 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.

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.