Online Record Keeper/ORK3 Developer Documentation/Overview

From AmtWiki
Revision as of 12:45, 25 May 2014 by Zellfaze (talk | contribs) (Created page based off original document available at https://docs.google.com/document/d/17OupAN0b63Jkij-lygOkmjlgFCH6vAB3PJ2W_VQIgeU)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This document attempts to give a broad overview of the design and goals of the ORK3, as well as an introduction to to the components, use of the ORK3, and development.

Resources

Source Code

Source code is available at http://www.amtgard-ork.org/AmtgardORK/ork3/ via SVN.

Test and Stage

Development, Stage, and Final Production Test are available at:

respectively. Final deployment is expected to be at amtgardrecords.com.

Design

The ORK3 is designed first and foremost as a Service, rather than as an application. Because there is a relatively large audience that may use the dataset of the ORK3 for various purposes, it would be cumbersome (as experience has shown), to lock up the data in a single application. Furthermore, this allows the ORK3 maintainers to concentrate on the important tasks of availability, scalability, and usability of the dataset, without necessarily having to spend time on interface issues (although UI improvements are a major goal of the ORK3 project).

Service

The ORK3 Service is a programmatic endpoint designed for use by developers. The ORK3 Service is actually a set of services, each exposing separate function of the ORK3. The implementation choice was MySQL/PHP/NuSOAP, because this platform is already supported by the major record keeping implementations, is relatively common and easy to install and frankly, happens to be what the primary developer is familiar with. The primary components of the ORK3 Service are as follows.

Components

  • Authorization - provides authentication, privilege, and access information for the other systems.
  • Player - encapsulates player details
  • Kingdom - encapsulates kingdom-level details
  • Park - encapsulates park-level details
  • Award - encapsulates awards (including custom awards, and awards assigned to players); this is an entry point for Awards, but not a reporting point (see Report)
  • Attendance - encapsulates attendance (including custom attendance, and attendance assigned to players for parks and events); this is an entry point for Attendance, but not a reporting point (see Report)
  • Report - provides reporting criteria based filters, including attendance, award, guild, and player roster summaries, and search functionality
  • Search - this is a lightweight search service, using REQUEST (GET/POST) criteria and returns JSON-formatted data
  • Unit - encapsulates Households and Companies, including membership management
  • DataSet - this is a lightweight service, using REQUEST (GET/POST) criteria and returns datasets
  • Event - encapsulates Event details, this is not an Event-entry or Reporting end point (see Attendance and Report)
  • Tournament - encapsulates Tournament details, match, and bracket results; this is not a reporting endpoint; this service also provides tournament accessors (Bracketing Services) for popular tournament styles. Tracks Tournaments, tournament-style (single, double, RR, swiss, point distribution method), brackets, matches (winner, loser), bouts (winner, loser, simo), bracket rankings, tournament rankings, reeves per ring, bouts ring (which ring the bout was in), Glicko2 rankings.
  • Issues - encapsulates Issues (but not bugs); issues are assigned to specific users
  • Calendar - a lightweight JSON interface designed to work with Calendar controls; exposes a cross-section of information from the Park, Kingdom, Event, and Tournament endpoints. This is not a traditional calendaring component per se, since this service merely exposes pertinent information which must be tracked for the purposes of attendance.
  • Map - a lightweight JSON interface designed to expose data for use with mapping functionality
  • Heraldry - encapsulates storing and fetching heraldry
  • Treasury - encapsulates a simple sub-account-oriented t-type accrual accounting system with default accounts and methods appropriate to amtgard

More Information

More information can be found in the ORK3 Service Specification document.

ORK UI

The ORK UI is designed as an lightweight, human-accessible interface to the ORK Service. The ORK UI serves two functions:

  • Provide a human accessible entry point to the ORK3 Service
  • Provide an example and framework for development ORK3 consumers

The ORK UI makes use of the locality of the ORK3 Service dataset, but is designed also to access the ORK3 Service via the normal service-oriented methods. The key benefit of this is that ORK UIs may be copied to other servers in a seamless manner, while sharing their dataset with all other ORK consumer applications.

The ORK UI is designed as a theme-able MVC application. Extensions of the ORK UI can and should extend this theme to any lesser or greater extent necessary to accomplish whatever task the developer has in mind.

More Information

More information can be found in the ORK3 User Guide, ORK3 User Interface Overview, ORK3 User Interface Requirements, and ORK3 User Interface Specification documents.

Other Apps

Other apps are being developed concurrently with the ORK UI, including a mobile site, and a windows desktop-based application.

ORK3 Tournament Tool

A tool that helps develop tournament brackets (Single Elimination, Double Elimination, Round-Robin, and Swiss), and tracks performance use a rating system (Glicko2).

ORK3 Desktop

A Windows Forms (native MS Windows) app for working with the ORK 3 Service. The primary purpose of this platform is to ensure cross-technology compatibility of the system. This application may also offer the ability to synch attendance (store attendance locally, and record in batches once network availability is made), as well as synch against pre-generated Excel worksheets (the software will generate a spreadsheet to be printed for site attendance, which can be used as a source for data-entry later).

ORK3 Mobile

A mobile website for the ORK3 for use with phones or other small-screen internet-capable sites.

More Information

More information can be found in the ORK3 Desktop User Guide, ORK3 Tournament User Guide, or ORK3 Mobile User Guide documents.