ArchitectureOverview.md

Architecture Overview

Arisia is a science-fiction / fantasy / general geekery convention, held on Martin Luther King weekend every year. Virtual Arisia was the website for Arisia 2021, aka "What We Did With Our Plague Year". It was a determined attempt to create as good an experience as we could for the attendees of the convention, integrating a number of different technologies in the process.

These pages lay out, at a high level, how the system works. We don't expect anyone to simply pick up this code and run it for another convention -- it is quite specific to Arisia 2021 in many ways -- but it's intentionally open-source. We encourage you to pick this up, adapt it to your needs, lift out libraries, and generally strip it for parts. Hopefully you will find a bunch of reusable pieces that help you with your virtual-convention (v-con) needs.

Constraints

To understand this system, you need to keep in mind the constraints that it was designed for. Among other things:

• The budget was minuscule. Arisia is a fan-run, non-profit convention that works hard to keep itself affordable. So while we could and did use some commercial tools, the fancier convention packages were way out of our price range.
• The size was medium: we were figuring one to two thousand attendees. (We got around 1500 registrants, of whom a bit over a thousand actually logged into the system, and 900+ connected to Discord.) This meant that we had to pay some attention to scale, but did not have to build a fully-scalable system.
• Safety of the attendees was a critical priority: we wanted to make it challenging for trolls to crash the party. Hence, we focused on having the backend server authenticate that all participants in the interactive parts of the convention (in particular, Zoom and Discord) were registered members of the con.
• Accessibility was a firm requirement -- it's a priority for Arisia as a whole, so it was essential here. I can't say that the Virtual Arisia site was perfect in that regard, but we tried our best to provide a good experience for everybody.
• User Familiarity with the integrated tools was important. In practice, this is why we decided to integrate with Zoom for the A/V part of the convention, and Discord for the text chat. Neither is necessarily best-in-breed, but they were affordable, and they were the tools that the audience knew best.

Overview

First and foremost: this is a single-server system. Much of the architecture is designed around the assumption that one decently-beefy node would suffice to support the users.

As such, we were careful to offload as much as possible. For example, you will note that there are relatively few images in the repo, despite this being a fairly graphics-heavy website. Those graphics were kept on Amazon S3, so that the main server would not need to serve them out.

That in mind, from the thousand-foot view this is a pretty conventional website structurally. The UI is (mostly) rendered browser-side as a single-page application built with Angular, written in TypeScript. That talks to APIs provided by the backend server, which is built with the Play Framework and written in Scala.

(Why Play and Scala? Play is a high-performance, enterprise-grade webserver that we could trust; Scala is nice and strongly-typed, which makes for more robust code with fewer bugs. And they're the tools that I (Justin), the project lead who built the backend, knows intimately. Happy to geek about this more if you're curious -- I'm jducoeur on GitHub and basically everywhere else on the Internet.)

There is also an Admins-only, plain old MVC UI implemented in straight Play. (Specifically, implemented using the Twirl library, which provides HTML templating for Scala, similarly to how you define pages in Rails, Grails, Razor, PHP, etc.) That isn't remotely as pretty as the attendee-facing UI, but it doesn't need to be. The Admin UI is the behind-the-scenes stuff, largely concerned with permissioning and data management.

The backend also provides integration with the major external components:

• Convention Master is a commercial third-party package that we use for managing registrations. It does not provide any sort of API, so some of the scariest code here will be found in the sub-system that works with it.
• Zambia is an open-source scheduling system, which originated with Arisia but is now used by a bunch of conventions. We don't integrate deeply with it, but the backend polls it periodically for the current schedule info.
• Most program items such as panels and presentations happened in Zoom. The backend starts and stops meetings dynamically for these, based on the schedule.
• Text chat was in Discord. The backend didn't get as far as deeply integrating with that, but it does provide some simple hooks so that members could pass in their Discord ID, at which point we would assign them a Discord Role that gave them access to most of our Discord Server. There were also a few related functions for Discord integration, written in Python and running in AWS Lambda.

Other pages here will provide a bit more depth on these various topics.