Architecture

From Project Auriga

We're using a basic Model-View-Controller (MVC) architecture, and are working on having clear interfaces to make it a simple matter to extend and customize. See ideas for some things we plan to implement.

Contents 1 Model 2 View 3 Controller 4 Authentication 5 Source Code Layout 5.1 base directory 5.2 configs 5.3 include 5.4 public_html 5.5 templates

[edit] Model

The model contains the objects and data that represent real stuff. We are mapping out classes to represent things like employees, projects, time entries, invoices, customers, accounts, tasks, etc.

The model is mostly contained in a set of PHP classes with a variety of methods that act upon individual objects. The model has some built-in base classes which may be extended to quickly add new features.

See Objects for more.

[edit] View

The view consists largely of the user interface and what the user sees. Most of the view is defined in a set of Smarty templates for easy customization. We do not yet have a way to override built-in templates--a theming engine is a relatively low priority for the time being, but should be relatively straightforward to implement in the future.

See Views for more.

[edit] Controller

Controllers are scripts, functions, and classes that tie the views to the model. The centerpiece of the controller is the script located at the URL loaded for each module. This controller defines a minimum authorization level, and what actions may be taken on a given view. It then shepards the data to the appropriate model object to record an action, and sends a response back in the appropriate format.

The current early releases of the system put almost all of the controller logic into a set of controller classes, along with the landing URLs. Future versions may move much of the controller logic to JavaScript on the client.

See Events for more.

[edit] Authentication

The authentication system supports multiple authentication sources. In our initial project, we want to have a built-in authentication source for fine-grained control of which users have access to which items. We also want to allow our customers to log in to view project reports, invoices, and the like. We foresee being able to accomodate any number of authentication sources, using a registration interface that can be called in the config file and checked as needed.

See Authentication System for more...

[edit] Source Code Layout

Find the source code here.

Also see Installation.

[edit] base directory

Inside the root directory of a working instance of Project Auriga, you'll find these things:

• cache - Smarty cache. Not currently used.
• config.php(.dist) - main configuration file. This file creates $t, a Smarty object, sets the include path, registers database connections/plugins, and loads the site registry and utils.php file for utility functions.
• configs - miscellaneous files you'll need to install Auriga.
• include - core server-side programs
• public_html - web root for project
• templates - Smarty templates for all server-generated views
• templates_c - Smarty compiled template directory

[edit] configs

• auriga.conf - Sample Apache configuration for an Auriga virtual host. This should be ready to drop into a Debian /etc/apache2/sites-available directory after editing the ServerName. Set up SSL as appropriate (nothing about Auriga is secure enough to run without SSL, other than on a dev localhost environment).
• auriga.profile.js - Dojo build profile to speed up all Javascript. Build Dojo with this profile and turn the build flag on inside config.php for much better performance. See the comment at the top of the file for the build command.
• db_schema.mysql - Current database structure. Import this into MySQL to get Auriga running.

[edit] include

All PHP code that doesn't need to be inside the web root is stored inside the include/ directory. We're gradually moving this code into module-specific code. Most module code is loaded using a PHP5 _autoload function, which searches inside include/plugin first, allowing you to override model/controller code by simply replacing the base class file with one in the plugin/ directory. All non-core classes should go in here, to keep maintenance easier.

Here are the special files in include:

• utils.php - convenience functions, helper functions. These include debug_msg for logging messages, handle_put(), for decoding Ajax put requests, and others.
• site_registry.php - creates a global $registry array that defines the various modules and classes available, along with default authorizations and user levels. This registry array is loaded by config.php, and values may be overridden there or extended with custom settings. This file also contains the __autoload() function to locate class files.
• session_login.php - handles authentication/authorization for any request. Should be included on every request for protected stuff (which is just about everything other than our simple password generator).
• fl_class.php - contains base class definitions for fl_auth (user authentication class with authorization methods), fl_date (date handling object), fl_base (base data object class, with load/save methods) and fl_db, a singleton class that keeps track of database connections and data plugins.
• fl_data.class.php - contains fl_data base class for data plugins. Data plugins allow for data to be stored in multiple sources.
• lib/ - third party libraries (currently JSON.php)
• account/ - contains account classes.
• manage/ - contains controller classes for managers - manage_time_approve, manage_time_bill, manage_time_pay, manage_account_edit
• plugin/data/ - contains database plugins, including the base auriga data plugin. Custom authentication plugins may be added here.
• plugin/ - other directories may be dropped in to autoload (and override existing) classes. For example, to override project/project.class.php, copy the file and make your changes in plugin/project/project.class.php. Your class will be used as the new base instead of the original base class. Drop custom modules in here, as well.
• project/ - contains all core project classes: the base project class, the project_c controller class, and child classes that inherit from the base project class.
• task/ - task classes
• time/ - time classes - time_clock, time_report, time_entry
• user/ - user classes
• workpane/ - Workpane controller class

The __autoload function splits a class name on the first underscore to get the base name. For a class named "my_widget" it first looks for plugin/my/my_widget.class.php, then my/my_widget.class.php, and finally my_widget.class.php.

[edit] public_html

The controller stubs, css, javascript, and images are under public_html - basically only what must be under the web root. The list below shows the areas of current development--all of the old generations of code will be ignored...

• dispatcher.php - Main controller stub. This file loads session_login.php, and handles the core module_id and view request parameters. See Request API for details. This replaces ajax.php, timeclock.php, and many of the other php files in the web root.
• show_invoice.php - client invoice page
• project_report - client project report
• confirm.php - handles payment confirmation from external payment processor
• auriga/ - directory containing current Javascript, using Dojo build system to provide modules
• auriga/Main.js - Set up global variables related to current user and view
• auriga/plugin/ - area for custom plugin code
• auriga/Project.js - Most functional code for Projects module
• auriga/templates/ - templates for Auriga widgets based on dijit._Templated
• auriga/Timeclock.js - timer handling
• auriga/Tasklist.js - Tasklist widgets, currently used on Projects page
• auriga/Workpane.js - handle workpane widgets, as well as login/logout
• css/auriga.css - current CSS file for all core CSS
• dojo/ - External load of most recent Dojo stable release (currently 1.0.1)
• dojo-trunk/ - External load of current Dojo trunk, mainly for testing
• js/ - legacy scripts, not used at all in current generation (new code)

[edit] templates

The main templates directory contains Smarty templates for the entire system. Each little chunk of HTML is pulled from here, or generated by Javascript (possibly with a JS template under public_html/auriga/templates). In the current system, we're starting to move these templates into directories that correspond to the particular module.

Templates do not have an autoload feature--you must specify the directory containing the template when you load it. Our plan is to create a pseudo autoload feature, which would allow you to create a "theme" and override any given template. We plan to do this by creating a custom Smarty function to load templates, which will first look in the templates/theme/CURRENT_THEME/ for a given template file. If it's not there, then it will use templates/ as the starting path.