Techscore is a web-based, sailing regatta scoring and management platform. It runs on Object-Oriented PHP as part of a standard LAMP stack. For information about running Techscore on AWS, see the techscore-aws project.
As of 2024, Techscore can also be run on Docker containers, see section below for notes.
Techscore was first openly published in 2018, ten years after the project began as simply a web-based UI to scoring regattas. It replaced a DOS-based, survey driven application known only as "Navy Scoring". The web was different in 2008. JavaScript support was very fragmented across different browsers and the few PHP frameworks that existed focused on speed over security and maintainability. As a result, Techscore introduced and has since created different conventions and is best approached with a fresh pair of eyes. All the same, experienced developers will soon find obvious implementation analogies to common design principles.
The key to getting started developing for Techscore is to get a sense of the directory structure. The subdirectories are labeled to mimic a mini UNIX filesystem, including the trite convention of using three-letter names.
repo root: The root of the repository; i.e. the directory containing this README.md file. Without any other qualifier,rootrefers to this directory. May be calledglobal root.
Everything that is directly served to the user's browser by the HTTP server (usually: Apache) is
located in this directory. This includes every statically generated CSS, JavaScript, image file;
favicon; and, notably, exactly one PHP file: index.php. This file is the entry point to the
application from the web. It is the script loaded by Apache for every route or webpage visited
that is not one of the aforementioned static files. (This is done via Apache rewrite rules; covered
under a separate guide.) This directory is sometimes called the web root.
Most of Techscore resides outside this directory, and the index.php file serves as an adapter:
handling all the HTTP and URL-related logic, before delegating to the application underneath.
This is the most important directory: lib is supposed to stand for "library". It is where all the
logic is tucked away. It resides explicitly outside the web root so that there is never a
possibility of direct access via URL 1. Free from meddling or risks of
exposure by an errant URL path, the files in this tree can be web-agnostic, Object-Oriented
classes. Indeed, all but a handful of specific ones are exactly that, and the file name matches
exactly the name of the single class they contain, analogous to a Java project.
Short for "resource", this directory houses the source version of the static files: CSS, JavaScript, and images. Techscore is written in pure CSS and JavaScript: no frameworks like Less, Sass, jQuery, etc. This is an explicit design decision from the early days (see Apologia). Each JavaScript file is self-sufficient and represents a standalone "module". However, were there to be any processing, building, or compiling of these source files before making them available to the browsers, this is where their sources would reside. As of today, files are copied as-is from this directory to the web root, optionally applying minification if available.
This directory contains source files used to create system-level configuration such as the Apache
VirtualHost webserver and the crontab. The runtime versions are generated by the project's
Makefile by incorporating global settings under lib, the single source of truth.
Of particular interest in this directory is the db subdirectory, which covers database schema
migrations, a technique borrowed somewhat from Rails, and the well known bane of relational database
maintenance.
As the name suggests, contains executable scripts. With the exception of cli.php and Make.php,
these are mostly auxiliary scripts meant to aid in the operational maintenance of the
application. They are meant to be exercised by a human, and do not form part of the day-to-day
(i.e. crontab or web-triggered) part of the application.
A recent addition (hence the new naming scheme), this directory contains hooks needed for running the application on AWS. See the techscore-aws project for more details.
[WIP as of 2024-01-27]
Use Docker compose to stand up a local version of Techscore for development. This will launch a local MariaDB container as well.
To release a new version, use docker-release.sh. This requires access to the AWS account that owns
the Techscore docker container registry. Bump up the APP_VERSION number in lib/conf.php.
1. By contrast, most other PHP applications are "drop-in" by nature: unzip a
directory tree and drop it into the "web root" of your web server, usually a third-party
website. For example, in WordPress, you can directly access PHP files that are internal to the
application by going to a URL matching the filesystem path of the file: /wp-includes/foo.php.