Revision as of 14:51, 20 November 2016

Design

High level design decisions for ARK2.

Supported Platforms

ARK2 will be built using modern PHP standards to support multiple Operating Systems and Database Systems. ARK will only actively support platforms that are actively supported by their maintainers. ARK may work on earlier versions but this is not guaranteed.

For more details see the Technical Details page.

Framework

It is proposed to implement a new RESTful Request/Route/Response skeleton using a Front Controller model and token-based security, based on an external micro-framework and components adhering to the PSR standards and managed via Composer. This will reduce the amount of code maintained internally, update the code-base to modern web-app design principals, and provide a degree of future-proofing by allowing switching of components.

The Silex micro-framework and Symphony components have been selected due to their high quality, long support history, and wide use and support

For more details see the ARK2/Development page.

Database Abstraction

ARK2 will support the use of MySQL, PostgreSQL or SQLite as the database by using the Doctrine DBAL database abstraction layer.

While no available Object-Relation Mapper (ORM) library is able to support the ARK database model, a lightweight ORM will be implemented using the Doctrine ORM interfaces to allow for a future migration.

More details can be found on the ARK2/Database page.

Security

ARK currently uses PEAR LiveUser for user authentication, authorisation, and user management, but this hasn't been updated since 2010. It is a security risk, and also lacks many features like federated login. The ARK API currently uses plain text user and password in the request URL which is insecure. ARK2 will require a new security solution, especially for the API calls from client apps. This solution will be token based, support username/password and OAuth2 authentication, and use Role-Based Access Control for authorization. HTTPS will be required for the API.

For more details, see the Security page.

REST / HATEOAS / Hypermedia

An evolution of the ARK data model and API to try realise the full ARK vision will be based arround the Hypermedia concepts of REST and HATEOAS as developed by Roy Fielding in his doctoral thesis in 2000. These concepts include resources, relationships, state, and discoverability, and are closely related to the Semantic Web. ARK modules will evolve to represent Resources that can be linked in together in the current flat relationship structure, or organised into configurable hierarchies such as the default Site/Module/Item mostly used by ARK instances. These concepts will be most easily exposed through a RESTful API.

For more details see the API page.

Frontend

The frontend will be migrated to Bootstrap, jQuery, and Twig, the most popular and well-supported frontend ui component and template systems. This will allow for easier customisation of ARK's appearance by third parties.

For more details, see the Frontend page.

Migration

A migration process from ARK 1 to ARK 2 will be provided.

Data migration. Existing tables will need to change from MyISAM to InnoDB. Change in place carries a degree of risk of data loss if the migration fails part way. Attempting to restart failed migrations is also prone to error. To protect users data, a new database will be created with new tables and the data copied across. Should migration fail users will easily be able to roll back to their old install, or keep retrying the migration until it does succeed. In effect the ARK init script will be run, followed by the migration script.

User migration. Users will be migrated from LiveUser to the new RBAC system. This will require a compatible default user config.

Config migration. A config migration script will be provided, but may require adapting for individual ARKs.

Sysadmin Console

An sysadmin console will be provided for use on the command line. This will provide a number of tools:

• Database administration, such as creation, migration, backup, etc
• MultiArk installs
• ARK wide alerts
• Maintenance mode (immediate and schedule)
• Upgrade tools
• etc

Equivalents for some of these functions will be provided in an ARK Sysadmin panel (separate to the ARK Admin panel):

• ARK wide alerts
• Maintenance mode (immediate and schedule)
• etc

Translations / Localisation

A key to providing Ark-As-A-Service will be translating the user interface and schemas into as many languages as possible to maximise the potential user base. ARK1 does not have the tools to make this process easy to perform or manage, and it would be a waste of resources to build them. It is recommended to use one of the existing online open-source translation projects to crowd-source the translations. This will allow interested parties and potential clients to translate ARK for themselves and to grow a local community to support ARK in their country.

Changes will be made to the translation process to bring ARK into line with industry best practices and tooling, allowing for common features such as correct plural forms. This will be based on the Symfony Translation componant.

More details can be found on the ARK2/Localization page.

Action Logging / Activity Streams / Gamification

All user actions and events in ARK will be logged, enabling an standard Activity Stream at user level that can support gamification. The actual gamification is considered outside of the scope of core ARK2. Some inspiration for the implementation can be taken from Event Sourcing, but a full implementation will not be attempted.

• http://martinfowler.com/eaaDev/EventSourcing.html
• http://activitystrea.ms/
• https://www.w3.org/TR/activitystreams-core/
• https://github.com/barnabywalters/php-activitystreams
• https://github.com/redpanda/ActivityStreams
• http://jwage.com/post/54480997504/building-activity-streams
• https://dev.playlyfe.com/guides/getting-started.html

Command Bus Architecture / Application Services

A Command Bus / Event Bus architecture will be implemented to support execution or queuing of synchronous and asynchronous Commands and Events. Console Commands will be wrappers around Commands that parse input from the command line.

• http://php-and-symfony.matthiasnoback.nl/2015/01/a-wave-of-command-buses/
• https://github.com/SimpleBus/
• http://tactician.thephpleague.com/
• http://culttt.com/2014/11/10/creating-using-command-bus/

Workflow Management

Stretch goal. Needed for Avalon. Packages exist to define workflows using state machines.

Possible workflow scenarios:

• Post-ex
• Sample taking
• Avalon jobs and documents
• Data checking

Document Management

Stretch goal. Needed for Avalon. Management of documents and versions a la Sharepoint. Try use CMIS standard as used in LibreOffice app, or WOPI used by LibreOffice online.

• https://www.alfresco.com/cmis
• https://packagist.org/packages/dkd/php-cmis
• http://wopi.readthedocs.io/projects/wopirest/en/latest/
• https://kolabian.wordpress.com/2016/11/16/collaborative-editing-with-collabora-online-in-kolab/
• https://www.collaboraoffice.com/code/
• WebODF?

CMS / Blog / Project Websites

Either provide an OoB Wordpress integration and host client websites, or add features to ARK to provide the basic project website features (home page, blog, contact us, calendar).

• https://github.com/bolt/bolt CMS built using Silex/Symfony

Errors

Standardised error codes will be used, based on the JSON API standard format. Error codes will be stored in a database table and exported via the API, with actual error messages translated via the standard methods, with detailed debug/help available on the ARK wiki via standardised links. Fatal errors will be thrown as exceptions, with the Controller responsible for catching the error and reporting it in the appropriate manner, i.e. via web or api. Non-fatal errors such as validation errors can be batched before return. While numeric error codes are convenient, they make code hard to read and debugging tracebacks harder, so all error conditions should be explicitly commented in the code, and error codes should be as unique as possible..

Matrix / Graph

PHP:

• https://github.com/clue/graph
• https://github.com/graphp/algorithms
• https://github.com/cpettitt/graphlib/wiki/API-Reference

Spatial

Basic spatial support is required, e.g. storing find points or area bounding boxes, as well as the advanced mapping interface options, such as displaying spatial layers, spatial search, etc.

Back-end support will utilise an OpenGIS standard compliant geometry library to manipulate and store basic geometries, support a basic level of geometry calculations, and provide data import/export.

• https://github.com/brick/geo - OpenGIS geometry library, requires GEOS, MySQL, PostGIS, or Spatialite. Has WKT and WKB support, but no file import/export support. Current but low-level maintenance, but not widely used.
• https://github.com/phayes/geoPHP - OpenGIS geometry library, internal routines but supports GEOS, lots of basic file import/export 2D only, effectively unmaintained but widely used, would need to fork and do major cleanups.
• https://github.com/symm/gisconverter (and several others) - Various file importer libraries with partial OpenGIS class support but no functions.

Likely solution will be to use Brick and fork various file libraries to work with it. May also fork geoPHP to work as a Brick backend? Alternative is major refactor of geoPHP, or piecemeal integration of each converter library.

Front-end support will continue to use OpenLayers.