Skip to content

Developer guide: architecture

Jump to bottom
cgolubi1 edited this page Jul 2, 2015 · 11 revisions

Architecture of ButtonWeavers code and development process

This page is intended to give a high-level overview of the ButtonWeavers codebase, implementation, and development process, as an orientation for prospective developers, testers, and sysadmins.

Code architecture

The ButtonWeavers implementation of ButtonMen is designed as a REST-ful (ish) database-backed webservice. To that end, the pieces of the implementation are:

  • A database: we use MySQL. The database contains the full record of player state, game state, and game history. All information needed to recreate the state of a BM site should be contained either in the git codebase or in the buttonmen database.
  • The backend engine: the backend (BM engine) is written in PHP. It is the layer which reads state from the database, performs all logical operations to move state forward (e.g. a player taking a turn in a game), and stores the new state back into the database. All communication with the backend happens via the API.
  • The API: the API is also written in PHP, and served by an apache webserver. It defines all legal methods which players can use to talk to the site, and returns responses in a quasi-REST-ful JSON syntax.
  • The web UI: the primary web UI at e.g. http://www.buttonweavers.com is written in JavaScript/jQuery. It communicates only with the API, never with the backend or database directly, and uses API responses to assemble pages that players can see. The job of the UI is to relatively naively display the information it gets from the backend when a user asks for a given page.
  • Alternate API clients: since front-end/backend communication happens via API, in principle, there could be any number of UIs/clients. Currently, we maintain a small python library that players can use to write python scripts which talk to BM, but there could eventually be other UIs as well.

A checked out copy of the buttonweavers codebase, e.g. from https://github.com/buttonmen-dev/buttonmen/ will contain these pieces in the following locations:

deploy/database: database schema and static contents
src/engine: the backend engine
src/api: the API
src/ui: the web UI static pages and JS
tools/api-client: alternative API clients we maintain

Development lifecycle

The canonical home of the ButtonWeavers code is this github repo: https://github.com/buttonmen-dev/buttonmen/

We never commit code to that repo directly. Instead, we develop using branches in per-developer repos forked from the buttonmen-dev one. https://github.com/buttonmen-dev/buttonmen/wiki/Developer-guide%3A-getting-started describes how to set this up.

How code gets accepted into the buttonmen-dev repo:

  • Individual developers make code changes in branches associated with a given issue from the buttonmen-dev issue tracker. The branch naming convention is <issue#>_<description>, so we can associate changes with the issue they fix.
  • We use Jenkins, a continuous integration server, to run unit and regression tests on the PHP backend/API layer, the JavaScript UI, and the python API client. Each developer gets an account on Jenkins, and a branch has to have a passing (blue) run in Jenkins before it's eligible to be merged into buttonmen-dev. Jenkins is at: http://jenkins.buttonweavers.com:8080/
  • Once a branch has a passing Jenkins run, the developer submits a pull request via the github UI. Another dev will take a look at the request and iterate on architecture, syntax, and functionality. When the request is approved, it will be merged into buttonmen-dev/master.

After code is accepted into master, it is tested on dev.buttonweavers.com, both for bugs and for behavior that our dev testers consider incorrect or undesirable. The code running on dev.buttonweavers.com is pushed to www.buttonweavers.com at the beginning of each month. See the deployment schedule for details: https://github.com/buttonmen-dev/buttonmen/wiki/Deployment-schedule

Code testing

The Jenkins host runs a number of unit tests which code should pass. At a high level, these tests include:

  • Unit tests for each type of code:
    • PHP backend/API unit tests, executed by phpunit (in test/src/engine and test/src/api)
    • JavaScript UI unit tests, executed by QUnit (in test/src/ui)
    • Python API client unit tests, executed by pyunittest (in test/tools/api-client)
  • Coding style and layout auditing (these are all configured in deploy/jenkins):
    • PHP auditing for coding style (Checkstyle), code complexity (PMD), and duplicate code
    • Javascript auditing for coding style (jshint)
    • Small custom audit scripts to make sure the directory layout is reasonable, files have Unix line termination, etc
  • Reports on both PHP and JS code coverage (we don't currently fail builds because of these numbers, but we do keep an eye on them)

Where to go next

See https://github.com/buttonmen-dev/buttonmen/wiki/Developer-guide%3A-getting-started for information about how to get setup with github and Jenkins, and guidance about setting up a test environment to run the code.

Clone this wiki locally