Technical documentation

From AADoc

This will serve as the "root" page for all technical topics. It should link directly or indirectly to every technical article in the wiki.

The current version of Active Agenda is built for the Linux - Apache - MySQL - PHP platform (the "LAMP" stack), but thanks to the XML-based meta structure of its modules, it can be ported to support other platforms.

Active Agenda is intended to be installed on a dedicated server or a virtual dedicated server, but not on a shared hosting account. Current installations have all involved placing the MySQL database on the same box as the web server, but separating them shouldn't involve too many problems.

1 Installing Active Agenda
2 Architecture
3 Development Process
4 Customizing Active Agenda

[edit]

Installing Active Agenda

See: Installing Active Agenda.

[edit]

Architecture

Active Agenda is, technically speaking, a large relational database with a web interface that allows users to add and modify data. Each table in the database is represented by a "module", which serves as the metaphor for all meta-data that is associated with that table. This meta-data is defined in an XML file for each module, consolidating data table structure together with relationships with other tables, user interface "screens" and form fields, as well as module-specific documentation.

Rather than turning the XML meta-data into a running application "on the fly", Active Agenda uses a "generator" that translates the XML structure into generated files that contain the module-specific logic. Therefore we speak of "generating time" and "run time" as separate states in which the code might be executed. The generator will typically hard-code data from the XML definitions into the generated files, whick will then remain static unless the XML definition changes.

Functionality which is not module-specific is coded directly into the framework application, and is not represented in any XML file. This includes the user login functionality, user permissions, and the logic that handles the basic page display.

[edit]

Development Process

Also see Category:The Technology and Category:Developer Topics.

An important benefit of the XML module definition approach is that it enabled a "power user" (but non-programmer) to define what fields are displayed on what screen, how they are labeled and how the data in one module relates to another. Dan Zahlis, our domain expert, designed most of the user interface of the application and also did most of the data modelling.

Under a tradtional programming model, the domain expert would create specs or change requests using less structured formats (such as free form text or pictures), to be interpreted and implemented by a programmer. After the programmer is done, the domain person would check the new functionality, and if corrections or changes are needed (because of failures in the human communication), a new change request is started. Frequently, seeing the new functionality in action would give the domain person new ideas for improvements, or lead to the realization that the user interface is flawed from a user interaction perspective, which would then require another change request.

Active Agenda's XML spec development process changes all that. We refer to it as "spec2app". It means that the user expert can implement new modules, and do many changes, fixes and updates to the user interface and data structure without having to involve (and wait for) a programmer before seeing them in action. Precise definitions in a highly structured format also means that the risk of human misunderstandings in communicating and interpreting these specs is reduced. The XML specs also double as reference documentation.

[edit]