Architecture

Collecting some notes on the code architecture...

Overview

 * Coding style
 * Class tree
 * Source tree layout

Initialization
All main code paths go through common initialization in common.php, which loads up some common classes, initializes default configuration, searches for configuration files, then sets up the database connection and loads the final configuration.


 * status_network table
 * config.php
 * config table

Web UI

 * index.php
 * Router class deciphers the URL path and arguments
 * (if necessary, redirect to canonical URL or login form)
 * Selected Action subclass is instantiated:
 * Action::prepare validates input
 * Action::handle performs save actions (if applicable) and HTML/XML/JSON output
 * Various other bits in Action and friends abstract away the standard web view template, etc
 * (error handling and cleanup)

Generally, each different action is handled by its own Action subclass. Similar actions may share code with additional common base classes.

AJAX form submissions are usually implemented as a special case; the submission handler accepts a parameter marking it as AJAX instead of JS-free web and it outputs a minimal page return with whatever content should be reinserted to replace the original form.

API
API hits go through the same general web infrastructure. Common code for API input and output systems are in a base class ApiAction.

Installer

 * install.php

Command-line scripts

 * scripts/*.php
 * scripts/commandline.inc handles setup

Various maintenance and utility scripts to aid in site administration, as well as long-running background processes for optional features.

The common scripts/commandline.inc handles framework setup, parameter parsing, and generic --help output.

Queue handlers

 * scripts/queuedaemon.php
 * lib/iomaster.php
 * lib/iomanager.php
 * lib/queuemanager.php
 * lib/queuehandler.php (and subclasses)
 * index.php
 * lib/unqueuemanager.php
 * lib/queuehandler.php (and subclasses)

A lot of our processing such as notifications, output to other services, distribution to many inboxes, etc can be done in the background. If no queueing system is enabled, they'll be run immediately during whatever processing triggers them; otherwise they're saved for later, then pulled up from queuedaemon.php to be run when we want it.

Individual bits of work store a serialized Notice or other object (or array, or string...) along with a transport/queue name -- which is used to load the appropriate QueueHandler class. Your class then takes that item and does whatever.

Fancier requirements can be dealt with by implementing things at the lower end (IoManager etc) such as is done for XMPP.

See Daemon redesign for some overview on the new queueing architecture in 0.9.

Plugins
At a high level, plugins are implemented as classes extending the Plugin base class. You toss that and any dependent files into a subdir under plugins or plugins/local, and it can all be loaded up in a chunk.

The Plugin class abstracts away some things for you, including localization setup and low-level initialization of event hooks. A simple plugin may just be that single class with a few methods as event handlers.

A more complex plugin may include custom tables, internal and external libraries, etc -- but they're all reached from that central point.

See Plugin development for more

Data storage
Database storage is abstracted through DB_DataObject. This is a kind of weird system but clever in its way; keep an eye out for code that calls ->find, ->fetch, ->insert etc.

We've subclassed the data objects to add some additional smarts for data caching (via memcached or other plugins) and easier memory management for long-running scripts.

Plugin schema changes can now be automated for creating and updating database tables from plugins, but you do have to create a wrapper class and jump through a few hoops. See existing plugins such as OStatus for real-world examples (or the 'Sample' plugin for a really simple one!)

File storage
Users can upload avatar and background images as well as upload file attachments of various types. These are stored in the avatar, background, and file subdirectories unless configured otherwise. Some but not all files are linked to various records in the database.

Files need to be in a path accessible to all web server(s), so may need to be on a networked filesystem for multi-server farms.

Key features

 * Attachments