Architecture¶

calServer is a multi-tenant PHP web application based on the Yii 1.1 framework. This section describes the technology stack, module structure, and directory layout.

Technology Stack¶

Layer	Technology
Language	PHP 7.4
Framework	Yii 1.1 (MVC)
Database	MySQL 5.7
Web Server	Nginx (Reverse Proxy)
Caching	Memcached
Report Generation	JasperReports (Report Runner, Java 21)
Containerization	Docker / Docker Compose
Orchestration	Kubernetes / Helm (optional)
Synchronization	SymmetricDS
Backup	Borg Backup
Real-time	Pusher (WebSocket)
SSO	SAML 2.0 / LDAP (onelogin/php-saml, adLDAP)

Container Architecture¶

The Docker Compose setup consists of the following services:

Container	Purpose
`calserver`	PHP-FPM + Nginx -- main application
`mysql_db`	MySQL 5.7 database
`report-runner`	Java service (Javalin + JasperReports) for report generation on port 8090
`nginx-proxy`	Reverse proxy with automatic SSL termination
`adminer`	Web-based database access (development/admin only)
`metteam`	MSSQL Server for Fluke MET/TEAM integration (optional)

Communication between calserver and report-runner occurs internally via HTTP (http://report-runner:8090). The Nginx proxy forwards external requests to the PHP-FPM process.

Module Structure¶

The application logic is organized into Yii modules located under httpdocs/protected/modules/:

Module	Purpose
`frontend`	Main module -- inventory, calibrations, customers, orders, reports, dashboard
`api`	REST API endpoints (Inventory, Calibration, Customer, Report, User, etc.)
`adminpanel`	Administration interface -- settings, field configuration, user management
`dms`	Document management system -- file upload, inbox, versioning
`support`	Support ticket system with email fetch
`wiki`	Internal wiki module
`jbackup`	Backup management via the web interface
`showcase`	Demo/presentation module

Each module follows the Yii MVC pattern with subdirectories for controllers, models, views, and optionally components.

Directory Layout¶

calServer-yii/
├── docker/                     # Docker Compose, Nginx config, environment variables
│   ├── docker-compose.yml
│   ├── nginx/
│   └── mysql/
├── configs/                    # PHP, Nginx, Memcached, cron configuration
├── httpdocs/                   # Webroot
│   ├── index.php               # Entry point
│   ├── protected/              # Protected application code
│   │   ├── commands/           # CLI commands (yiic)
│   │   ├── components/         # Application components and behaviors
│   │   ├── config/             # Yii configuration (main, local, constants)
│   │   ├── controllers/        # Global controllers (Site, Command)
│   │   ├── extensions/         # Yii extensions (RestfullYii, PHPExcel, Booster, etc.)
│   │   ├── features/           # Behat test scenarios
│   │   ├── helpers/            # Global helper functions
│   │   ├── messages/           # Translation files (de, en)
│   │   ├── migrations/         # Database migrations
│   │   ├── modules/            # Application modules (see above)
│   │   ├── sql/                # SQL scripts
│   │   ├── tests/              # Unit and integration tests
│   │   ├── vendor/             # Composer dependencies
│   │   └── vendors/            # Manual libraries (mPDF, html2pdf, FPDI)
│   ├── reports/                # JasperReports templates (.jrxml, .jasper)
│   ├── filemanager/            # DMS file storage
│   ├── uploads/                # User uploads (images, avatars)
│   └── themes/                 # UI themes
├── report-runner/              # Java-based report service
│   ├── pom.xml
│   └── src/
├── calserver-sync/             # SymmetricDS synchronization
├── borg/                       # Borg backup scripts
├── helm-chart/                 # Kubernetes Helm Chart
├── k8s/                        # Kubernetes manifests
├── ci/                         # CI/CD configuration
├── tools/                      # Utility scripts
└── docs/                       # MkDocs documentation

Core Components¶

The most important application components under httpdocs/protected/components/:

Component	Description
`Controller`	Base controller with authentication, layout, and tenant context
`DccXmlGenerator`	Generates DCC-compliant XML files from calibration data (see DCC Export)
`ReportEngineManager`	Controls report generation (legacy vs. Report Runner), feature flags, DCC plugin
`GridView` / `GridViewHelper`	Extended Yii grid view with configurable columns
`KCDbAuthManager`	Database-based access control (RBAC)
`KCDbConnection`	Extended database connection with tenant isolation
`CacheHelper`	Memcached abstraction
`DigitalOceanComponent`	Integration with DigitalOcean Spaces for file storage

CLI Commands¶

calServer provides numerous commands via the Yii console framework (yiic), located under httpdocs/protected/commands/. The general syntax is:

./yiic <command> run [--parameter=value]

Important commands:

Command	Description
`status`	Automatic status update of inventories
`mailer` / `sendemailqueue`	Process email queue
`dmsinboxcheck`	Move files from the inbox folder to the DMS
`backup`	Database and file backup (Borg)
`fetchmail`	Fetch emails for the support module
`exportreport`	Export reports from the email queue

A complete list of all commands can be found in the Administration.

Report Runner¶

The Report Runner is a standalone Java service (Javalin + JasperReports 7) that generates reports via an HTTP API. The main application sends JSON jobs to http://report-runner:8090, and the service renders the JasperReports template and returns the result (PDF, Excel, CSV).

Switching between the legacy report system (JasperStarter) and the Report Runner is controlled via feature flags in the ReportEngineManager class:

use_report_runner -- Enables the Report Runner (per user or globally)
enable_dual_run -- Parallel execution of both engines for comparison
enable_dcc_plugin -- Enables DCC XML generation (see DCC Export)

Configuration¶

The application configuration is located under httpdocs/protected/config/:

File	Content
`main.php`	Main configuration -- modules, imports, aliases, behaviors
`components.php`	Component registration (DB, Cache, Auth, ReportEngine)
`local.php`	Environment-specific settings (DB credentials, domain)
`constants.php`	System constants, field types, status definitions
`console.php`	CLI-specific configuration
`saml.php`	SAML SSO configuration