Project Components and Architecture¶

This section describes the individual projects that make up the MultiFlexi ecosystem, their purposes, and how developers should work with them.

multiflexi-common	multiflexi-web	multiflexi-cli
multiflexi-tui	multiflexi-scheduler	multiflexi-executor
multiflexi-executor-docker	multiflexi-executor-podman	multiflexi-executor-k8s
multiflexi-executor-azure	multiflexi-event-processor	multiflexi-probe
multiflexi-housekeeper
multiflexi-abraflexi	multiflexi-csas	multiflexi-raiffeisenbank
multiflexi-mail	multiflexi-mserver	multiflexi-eu
multiflexi-mysql	multiflexi-pgsql	multiflexi-sqlite

Core Components¶

php-vitexsoftware-multiflexi-core¶

Location: https://github.com/VitexSoftware/php-vitexsoftware-multiflexi-core

Purpose: Core PHP library providing the fundamental business logic, data models, and shared utilities for the entire MultiFlexi ecosystem.

Key Features: - ORM base classes (Engine, DBEngine) - Domain models (Company, Application, Credential, Job, RunTemplate) - Execution & scheduling framework - Logging integration with multiple targets - Zabbix monitoring integration

Main Namespaces:

MultiFlexi\                    → src/MultiFlexi/
MultiFlexi\Env\               → src/MultiFlexi/Env/
MultiFlexi\Action\            → src/MultiFlexi/Action/
MultiFlexi\Zabbix\            → src/MultiFlexi/Zabbix/
MultiFlexi\Executor\          → src/MultiFlexi/Executor/
MultiFlexi\CredentialType\    → src/MultiFlexi/CredentialType/

Developer Usage:

# Development setup
git clone https://github.com/VitexSoftware/php-vitexsoftware-multiflexi-core
cd php-vitexsoftware-multiflexi-core
composer install

# Run tests
./vendor/bin/phpunit

# Code analysis
./vendor/bin/phpstan analyse

Key Classes: - MultiFlexi\Job - Central job execution orchestrator - MultiFlexi\Application - Application definition management - MultiFlexi\Company - Multi-tenant company handling - MultiFlexi\RunTemplate - Job template configuration - MultiFlexi\Executor\Native - Native command execution - MultiFlexi\Executor\Docker - Docker container execution

multiflexi-database¶

Location: https://github.com/VitexSoftware/multiflexi-database

Purpose: Database schema definitions, migration scripts, and database maintenance tools for MultiFlexi platform.

Key Features: - Phinx-based database migrations - Multi-database support (MySQL, PostgreSQL, SQLite) - Schema versioning and rollback capabilities - Seed data for development and testing

Structure:

db/
├── migrations/           # Database migration files
│   ├── 20160203130652_user.php
│   ├── 20200413063021_applications.php
│   └── ...
└── seeds/               # Test and development data

Developer Usage:

# Run migrations
./vendor/bin/phinx migrate

# Create new migration
./vendor/bin/phinx create MigrationName

# Rollback migration
./vendor/bin/phinx rollback

Database Tables (key entities): - user - User accounts and authentication - company - Multi-tenant company entities - applications - Application registry - job - Job execution records - run_template - Job execution templates - config_registry - Configuration storage

API and Server Components¶

multiflexi-api¶

Location: https://github.com/VitexSoftware/multiflexi-api

Purpose: API class generator and server components that generate API server classes and handle routing.

Key Features: - Generates API server classes from OpenAPI specifications - Handles API routing and middleware - Supports multiple output formats (JSON, XML, YAML, HTML)

Developer Usage:

# Generate API classes
php generate-api.php

# Validate OpenAPI schema
swagger-codegen validate -i openapi-schema.yaml

multiflexi-server (API Backend)¶

Location: https://github.com/VitexSoftware/multiflexi-server

Purpose: REST API server implementation built on PHP Slim 4 framework. It serves as the primary backend for both the web interface and CLI tools.

Key Features: - RESTful API endpoints - HTTP Basic and Token authentication - Request/response handling - API versioning support - Serving data for multiflexi-web and multiflexi-cli

API Endpoints: - /apps - Application management - /jobs - Job management and execution - /companies - Multi-tenant company management - /users - User management - /credentials - Credential management - /runtemplates - Job template management

Developer Usage:

# Start development server
php -S localhost:8080 -t public/

# Test API endpoints
curl -X GET "http://localhost:8080/api/apps.json" \
     -H "Authorization: Basic $(echo -n 'user:pass' | base64)"

CLI and Execution Components¶

multiflexi-cli¶

Location: https://github.com/VitexSoftware/multiflexi-cli

Purpose: Command-line interface for managing MultiFlexi resources and operations.

Key Features: - Application management (list, create, validate) - Company and user management - Job execution and monitoring - Configuration management

Common Commands:

# List applications
multiflexi-cli application:list

# Create new company
multiflexi-cli company:create --name "Test Company"

# Validate application JSON
multiflexi-cli application validate-json --json app.json

# Execute job
multiflexi-cli job run --template-id 123

multiflexi-executor¶

Location: https://github.com/VitexSoftware/multiflexi-executor

Purpose: Dedicated service for executing jobs and tasks in isolated environments.

Key Features: - Job execution coordination - Task scheduling - Environment isolation - Support for multiple execution backends

Executor Types: - Native - Direct command execution - Docker - Container-based execution - Kubernetes - Pod-based execution - Azure - Cloud-based execution

Developer Usage:

# Start executor daemon
php daemon.php

# Execute single job
php executor.php --job-id 123

multiflexi-housekeeper¶

Location: https://github.com/VitexSoftware/multiflexi-housekeeper

Purpose: Periodic maintenance daemon that keeps the MultiFlexi platform healthy by running eight housekeeping duties once per hour via a systemd timer.

Key Features: - Stale Task finalization (marks expired open/running Tasks as missed or failed) - Orphaned job and broken queue-entry cleanup - Schedule integrity repair (resets stuck next_schedule on RunTemplates) - GDPR data retention enforcement (delegates to RetentionService when multiflexi-web is installed) - Disk temp-file cleanup (removes orphaned result files after artifact storage) - Log table pruning (keeps the log table below a configurable row count) - RunTemplate job-counter recalculation (corrects drift after retention deletes) - Credential health checks (reports Misconfigured credentials before they block a job)

Deployment:

sudo apt install multiflexi-housekeeper
# Timer is enabled automatically on install
systemctl list-timers multiflexi-housekeeper

# Ad-hoc run
sudo systemctl start multiflexi-housekeeper.service

# Preview without changes
sudo -u multiflexi multiflexi-housekeeper --dry-run

Key Namespace: MultiFlexi\Duty\ → src/MultiFlexi/Duty/

Service: multiflexi-housekeeper.timer + multiflexi-housekeeper.service

See HouseKeeper — Periodic Maintenance for full configuration and troubleshooting.

Web Interface Components¶

MultiFlexi (main web UI)¶

Location: https://github.com/VitexSoftware/MultiFlexi

Purpose: Primary web interface — dashboard, company management, application assignment, RunTemplate and job management, credentials UI.

Key Features: - Bootstrap 5-based responsive UI - Dashboard with system status and recent jobs - Company, application, RunTemplate, and job management - Credential and CredentialType management - Live job output via WebSocket

Key Namespace: MultiFlexi\Ui\ → src/MultiFlexi/Ui/

multiflexi-web¶

Location: https://github.com/VitexSoftware/multiflexi-web/

Purpose: Web assets and frontend package (Bootstrap 5 styles, compiled JS/CSS).

multiflexi-ui¶

Location: https://github.com/VitexSoftware/multiflexi-ui

Purpose: React/TypeScript/Vite UI components for a modern frontend alternative.

Key Features: - Component library built with Vite + TypeScript - Communicates with MultiFlexi REST API - Hot-module replacement for development

Developer Usage:

cd multiflexi-ui/
npm install
npm run dev    # Development server with HMR
npm run build  # Production build

Monitoring & Observability¶

multiflexi-probe¶

Location: https://github.com/VitexSoftware/multiflexi-probe

Purpose: Testing and debugging tool for the MultiFlexi task launcher. Executes a simple health-check to verify the execution pipeline works end-to-end.

Install:

sudo apt install multiflexi-probe

multiflexi-zabbix¶

Location: https://github.com/VitexSoftware/multiflexi-zabbix

Purpose: Zabbix monitoring integration, including Low-Level Discovery (LLD) scripts and Zabbix templates.

Key Features: - Low-Level Discovery (LLD) for companies, apps, and run templates - Pre-configured Zabbix templates - Integration with MultiFlexi API for monitoring data - Automated alerting based on job status

See Zabbix Integration for configuration details.

multiflexi-zabbix-selenium¶

Location: https://github.com/VitexSoftware/multiflexi-zabbix-selenium

Purpose: Production-ready integration of Mocha/Selenium web test results into Zabbix monitoring.

Credential Plugins¶

Each of the following packages provides a CredentialPrototype — a JSON-defined template that describes how to connect to an external system.

multiflexi-abraflexi¶

AbraFlexi ERP credential prototype. Fields: ABRAFLEXI_URL, ABRAFLEXI_USER, ABRAFLEXI_PASSWORD, ABRAFLEXI_COMPANY.

multiflexi-csas¶

Česká Spořitelna / ČSAS / Erste API credential prototype.

multiflexi-raiffeisenbank¶

Raiffeisenbank Premium API credential prototype.

multiflexi-mail¶

SMTP/e-mail credential prototype (Symfony Mailer). Fields: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, MAIL_FROM.

multiflexi-database-connection¶

PDO database connection credential prototype. Useful for jobs that need direct database access.

multiflexi-vaultwarden¶

VaultWarden / Bitwarden credential prototype. Allows storing sensitive secrets externally in Bitwarden-compatible vault instead of in the MultiFlexi database.

multiflexi-mtr¶

MTR network diagnostics credential prototype for network monitoring jobs.

MCP Integration¶

multiflexi-mcp-server¶

Location: https://github.com/VitexSoftware/multiflexi-mcp-server

Purpose: Model Context Protocol (MCP) server that exposes the MultiFlexi REST API as MCP tools, enabling AI agents (Claude, etc.) to manage MultiFlexi directly.

Install:

pip install multiflexi-mcp-server

Configure (MULTIFLEXI_HOST environment variable):

export MULTIFLEXI_HOST=https://multiflexi.example.com

Features: Tools for apps, jobs, companies, users, run templates, GDPR data exports.

Event-Driven Processing¶

multiflexi-event-processor¶

Location: https://github.com/VitexSoftware/multiflexi-event-processor

Purpose: Event-driven job triggering daemon (multiflexi-eventor). Complements the time-based scheduler by firing jobs in response to external events.

Service: multiflexi-eventor.service

Install:

sudo apt install multiflexi-event-processor

Example Applications¶

These repositories demonstrate how to build MultiFlexi-compatible applications:

MultiFlexi-Golang-App-Example — https://github.com/VitexSoftware/MultiFlexi-Golang-App-Example: Demonstrates the Go pattern: read environment variables, perform work, output structured JSON.
MultiFlexi-Java-App-Example — https://github.com/VitexSoftware/MultiFlexi-Java-App-Example: Comprehensive Java example with environment variable handling and JSON result output.
multiflexi-node-app — https://github.com/VitexSoftware/multiflexi-node-app: Node.js / Express template for building MultiFlexi applications.

Terminal User Interface¶

multiflexi-tui¶

Location: https://github.com/VitexSoftware/multiflexi-tui

Purpose: A modern terminal UI frontend for multiflexi-cli, built with the Charmbracelet Bubbletea framework (Go).

Install:

sudo apt install multiflexi-tui

Launch:

multiflexi-tui

multiflexi-zabbix¶

Location: https://github.com/VitexSoftware/multiflexi-zabbix

Purpose: Zabbix monitoring integration, including Low-Level Discovery (LLD) scripts and Zabbix templates.

Key Features: - Low-Level Discovery (LLD) for companies, apps, and jobs - Pre-configured Zabbix templates - Integration with MultiFlexi API for monitoring data - Automated alerting based on job status

Deployment and Infrastructure¶

multiflexi-ansible-collection¶

Location: https://github.com/VitexSoftware/multiflexi-ansible-collection

Purpose: Ansible collection for automated deployment and configuration management of MultiFlexi components.

Key Features: - Infrastructure as Code - Multi-environment deployment - Configuration management - Service orchestration

Usage:

# Install collection
ansible-galaxy collection install .

# Deploy MultiFlexi
ansible-playbook deploy.yml -i inventory

Development Workflow¶

Source Code vs Vendor Dependencies¶

Editable Source Code (Full write access as author):

https://github.com/VitexSoftware/php-vitexsoftware-multiflexi-core  (src/MultiFlexi/)
https://github.com/VitexSoftware/multiflexi-database
https://github.com/VitexSoftware/multiflexi-server
https://github.com/VitexSoftware/multiflexi-cli
https://github.com/VitexSoftware/multiflexi-web  (src/MultiFlexi/)

Vendor Dependencies (Read-only, prefer modifying source):

vendor/vitexsoftware/ease-core/
vendor/vitexsoftware/ease-fluentpdo/
vendor/fpdo/fluentpdo/

Common Development Tasks¶

Adding New Application Support:

Create application JSON definition
Validate against schema
Add credential types if needed
Test execution in different environments

Extending API:

Update OpenAPI schema in multiflexi-api/
Regenerate API classes
Implement endpoints in multiflexi-server/
Update CLI commands in multiflexi-cli/

Database Changes:

Create migration in multiflexi-database/db/migrations/
Test migration on all supported database types
Update related model classes in core library

Adding New Executor:

Implement executor interface in core library
Add executor configuration options
Update job execution logic
Test in executor service

Testing Strategy¶

Each component has its own testing approach:

Unit Tests: PHPUnit tests in tests/ directories
Integration Tests: Database connectivity and API endpoint testing
Validation Tests: JSON schema validation for applications
End-to-End Tests: Complete workflow testing across components

Running Tests:

# Run all tests in a component
./vendor/bin/phpunit

# Run specific test
./vendor/bin/phpunit tests/JobTest.php

# Generate coverage report
./vendor/bin/phpunit --coverage-html coverage/