Magic Smoke Architecture

MagicSmoke uses a basic Client-Server-Architecture with the server being implemented in PHP to run on a web server (usually Apache) and two client modes: a stand-alone application for internal users and a web browser interface for customers. Accordingly the server has two interfaces to face each of those clients.

The stand-alone client is implemented in Qt to run natively on each platform.

This architecture follows the model of the PACK framework.

A more complete rendering of the architecture:
Theater Access Admin Access Customer Access
Qt Client Browser
Network (HTTP)
machine.php
(Theater Interface)
admin.php
(Admin Interface)
index.php
(Customer Interface)
MagicSmoke Middleware (Server)
PACK Framework
PHP5/Apache
MySQL or PgSQL Database

Backend: Howling with the WOLFs

The storage and communication infrastructure of MagicSmoke is based on the PACK framework. It is controlled by WOLFs - or Web Object Language Files. Those files are located in the wob folder:

wob/magicsmoke.wolf links all of the control files together and configures what is generated from them.

wob/db/* contains a complete description of the database layout.

wob/classes/* contains classes describing the domain objects of MagicSmoke and how they are converted to and from database objects.

wob/transact/* contain all transactions that can be performed on the server - input and output parameters of the transactions and what part of the server code is responsible for implementing it.

.../basics.wolf helping classes and transactions that do basic bookkeeping for MagicSmoke.

.../audit.wolf auditing functionality - auditing stores historical changes for certain data elements.

.../cart.wolf configures functionality related to the shoppin cart in the web UI.

.../customer,wolf contains customer data and related functions.

.../db.wolf basic configuration of the database.

.../event.wolf contains data and functions related to events, their scheduling, changing them, etc.

.../order.wolf is about ordering things, contains tickets, ordered items, vouchers, ...

.../template.wolf contains the infrastructure to store document templates used by the MagicSmoke to render tickets, vouchers, bills,...

.../user.wolf management of users, roles and rights for the standalone client.

Server: Interfaces

index.php is the customer interface. It decides according to the parameters given to it by the users browser how to render itself and what data to show.

admin.php is the admin interface. It is used to create and initialize the database. Except for the option to create new admin users, actual account management is done from the Qt client. The purpose of this interface is to get MagicSmoke started far enough so that the client can continue.

machine.php is the machine interface for the stand alone Qt client. It uses the web service protocol of PACK to communicate and will not display anything to a normal browser. For details of the transactions it can handle see the Web Object documentation.

Server: Files and Directories

www is the root directory of the server - it can be used directly during development.

autoload.php is contained in most sub-directories of www. It registers all classes declared in that directory with the autoloading mechanism of PACK.

www/images and www/styles are part of the example layout pages of the customer interface.

www/template contains the template files for the customer interface. See the Template Documentation for details.

www/inc/* contains all classes used by the server components.

www/inc/wbase is a symbolic link to the PHP base classes of the PACK framework.

www/inc/Twig is a symbolic link to the Twig template engine.

www/inc/classes some base classes for the system - mostly related to the customer interface.

www/inc/db special adaptations of database code for MagicSmoke.

www/inc/machine files related to the machine interface of MagicSmoke. Most of them are indirectly called by transactions.

www/inc/rendering classes related to rendering pages of the customer interface.

www/inc/wob automatically generated code for the transactions that the MagicSmoke server can perform. The web object classes (WO*) defined here are used throughout the server to represent data in the MagicSmoke database, The transaction classes (Wtr*) defined here are used both by the machine interface and the customer interface to execute specific queries on the backend. See the Web Object docu for a language independent description of those classes and the PHP source docu for implementation details.

www/inc/wext extensions to abstract web object classes. These extensions implement specific handling of some data items, calculations of some properties, and the implementation of most of the transactions.

Qt based Client

External Dependencies

The client relies on several external libraries:

pack/qtbase - the PACK base classes, used for the communication with the server.

tzone - the time zone database, which is used for converting time stamps received from the server into the correct time zone of the theater.

zip - code to read and write ZIP files - this is used for templates.

Sources

The client itself is stored in the src directory, with the following sub-directories:

crypto - implementations of some basic cryptographic functions used for authentication.

dialogs - various dialogs used by the program.

iface - an extension to the communication interface of PACK to meet MagicSmoke's needs.

images - image files used by MagicSmoke.

misc - small helper classes, minor widgets

mwin - tabs of the main window.

script - scripting classes

templates - rendering classes for ODF and ticket printing.

tests - unit tests.

wext - extensions of abstract generated classes.

widgets - base utility widgets.

wob - automatically generated Web Object code. Do not change anything in this directory. If there is a need to modify those objects: modify them in the *.wolf files, possibly marking them as abstract and overiding them in wext.

Build Order

Either build the entire system using the Makefile in the main directory or follow these steps:
  1. build the web object compiler in pack/woc
  2. go to the wob directory and call make (or call ../pack/woc/woc magicsmoke.wolf)
  3. build the libraries in pack/qtbase, tzone, elam, and zip
  4. go to src and build MagicSmoke
Each of the libraries and MagicSmoke itself are built by using qmake to create the necessary makefiles and make to compile.

Source Documentation