Disclaimer
I provide absolutely no guarantee, neither for the accuracy of this documentation nor for any property or feature of the software described here.
Do not use this software in critical situations or projects.
1. Introduction and Goals
Polly is a project for
-
letting me run live polls during a talk at a conference or meetup.
-
evaluating and learning certain technologies:
1.1. Requirements Overview
From a functional point of view, Polly is a web application for running a live poll during a talk or event. Consider it the digital version of the "show of hands", but with live display of what the audience voted.
From a project perspective, I use Polly to study and evaluate technology, patterns and frameworks. The functional requirements aren’t too complex, leaving me enough room for attention to quality goals.
-
Define a poll: a question with a predefined set of answers.
-
Define a poll instance, that is: one particular occurrence of a poll at a particular event.
-
Display an "event" view of a poll, consisting of a QR code for easy access to the voting page, and a graph that shows the live results.
-
This display should be embeddable in another HTML page.
-
-
Letting attendees vote on a poll instance.
I haven’t yet decided if I want or need a management user interface for defining those polls. For the first iteration, it may be enough to manually insert them into the persistent storage.
1.2. Main Quality Goals
The following list contains the most important quality goals for this application. The full list is in Quality Requirements.
| ID | Quality | Motivation |
|---|---|---|
QG01 |
Understandability |
Functional requirements should be simple and stay simple. This allows me to focus on the other goals (learning, experimenting) as well as writing quality code. |
QG02 |
Attractiveness |
Given I want to use Polly during events where I speak, the display should look good. |
QC03 |
Testability |
The architecture should allow easy testing of all main building blocks. |
1.3. Stakeholders
The following lists contains the most important personas for this application.
| Role/Name | Goal/Boundaries |
|---|---|
Developers |
Developers familiar with Java who want to learn about developing modern web applications without having to learn JavaScript/Typescript and an additional web application framework or two. |
Maarten Mulders (me) |
Improving my skills as an architect and a developer. Have some real-world, working sample code when discussing "traditional" web applications or Jakarta MVC. |
2. Architecture Constraints
2.1. Technical Constraints
| Constraint | Background and / or motivation | |
|---|---|---|
Software and programming constraints |
||
TC01 |
Use of Java |
One of the goals is to learn and evaluate certain technologies. I don’t want to learn too much new things at the same, so I stick to Java as the programming language. |
TC02 |
Use of open source technology |
Third-party (not written by me) software must be available under an open-source license. It should not be necessary to download or purchase proprietary software in order to study or contribute to this project. |
Operating System Constraints |
||
TC03 |
OS independent |
Developing and running the project should not require any particular operating system. It should be possible on at least Windows, Linux and macOS. |
2.2. Organisational Constraints
| Constraint | Background and / or motivation | |
|---|---|---|
OC1 |
Team |
Primarily myself, Maarten Mulders. Contributions from others are welcome, but I don’t expect too many. |
OC2 |
IDE independent setup |
Developing and running the project should not require any particular IDE or editor. The project must be compilable on the command line via standard build tools (e.g., Apache Maven). |
OC3 |
Configuration and version control / management |
Code is stored in a public Git repository with a complete commit history. This repository will host the code as well as this documentation. |
OC4 |
Testing |
Use JUnit to prove functional correctness using unit tests and optionally integration tests. Use JaCoCo to ensure a high test coverage and use PiTest to ensure high quality of tests. Use Playwright to write functional integration tests. |
OC5 |
Published under an Open Source license |
The source code as well as the documentation should be published under an Open Source license. |
2.3. Conventions
| Convention | Background and / or motivation | |
|---|---|---|
C1 |
Architecture documentation |
Structure based on the (English) Arc42 template. |
C2 |
Coding conventions |
The project uses the Palantir Java format. formatting is enforced through and can be executed using Spotless. |
C3 |
Natural language |
English. The project and the documentation both target an international audience. |
3. System Scope and Context
This chapter describes the environment and context of Polly. Who uses the system and on which other system(s) does Polly depend?
3.1. Business Context
3.1.1. Speaker
A speaker at a conference or meetup would like to know how their audience feels about a subject. For that, they ask their audience a multiple-choice question, or poll.
Also, they would like to immediately see how their audience thinks about the question.
3.1.2. Attendee
Somebody attending a talk by Speaker who would love to participate in their poll(s).
Apart from providing their own view, they would also like to see how other Attendees feel about the same question.
3.2. Technical Context
The technical context of Polly is pretty simple. Polly runs as a web application and is accessible to users primarily using their web browser:
| Interface | Description |
|---|---|
HTTP |
Serves the views to interact with a poll; this includes both viewing and voting. |
4. Solution Strategy
Polly is a single deployable application using a relational database.
The architecture of Polly follows the ideas of hexagonal architecture. This means that its domain model is unaware of the technology that powers it. Each component lives in its own Maven module, which is also a Java module. This approach makes it easier to test a large part of the application logic in a fast and light-weight way [QC.OE.01].
The core of Polly is its Domain Model, which is completely agnostic of any framework or library. It applies a few tactical patterns from Domain Driven Design. You will find Repositories, rich Entities and Value Objects.
Since the Domain is technology-agnostic, some parts cannot be implemented in the Domain. That’s why the Infrastructure provides implementations based on the selected technology stack. For instance, it provides implementations of the Repositories based on the Jakarta Persistence API.
The Web application is responsible for generating the web-based user interface. It uses Krazo to deliver fast, light-weight web pages rather than requiring users to download a large bundle of JavaScript [QC.PF.01], [QC.PF.02].
To bring it all together without introducing undesired dependencies, the Application module packages all these components together. It creates a Web Archive (WAR) using overlays, that can be deployed to any Jakarta EE 10-compatible application server [QC.OE.01].
5. Building Block View
Polly is divided in three main parts: the (Core) Domain, a Web application that exposes functionality from the domain, and the Infrastructure that provides technology-dependent implementations for components that live in the domain.
As outlined in the Solution Strategy, the domain model must be unaware of the technology that powers it. It is the responsibility of the Infrastructure module to provide the actual implementations for concerns like persistent storage of domain entities.
10. Quality Requirements
10.1. Quality Tree
The following list contains the quality goals for this application. The goals with an identifier between square brackets correspond with one of the Main Quality Goals.
| ID | Quality Category | Quality | Description | Scenario |
|---|---|---|---|---|
QC.US.01 |
Usability |
Attractiveness [QG02] |
I want to use Polly during events where I speak, so displaying polls should look good. |
|
QC.PF.01 |
Performance |
Responsiveness |
Displaying a poll during a talk should take less than 500 milliseconds. |
|
QC.PF.02 |
Responsiveness |
Voting on a poll should take less than 1 second. |
||
QC.OE.01 |
Operational & Environmental |
Runtime agnosticism |
The solution should work on any Jakarta EE 10 compliant application server. |
|
QC.MS.01 |
Maintainability & Support |
Understandability [QC01] |
Functional requirements should be simple and stay simple. This allows me to focus on the other goals (learning, experimenting) as well as writing quality code. |
|
QC.TS.01 |
Testability [QC03] |
The architecture should allow easy testing of all main building blocks. |