mirror of
https://github.com/plan-player-analytics/Plan.git
synced 2024-12-01 23:23:26 +01:00
Created Architectural Decision Records (markdown)
Rsl1122
parent
49a6f1015e
commit
a65e69e2ca
256
Architectural-Decision-Records.md
Normal file
256
Architectural-Decision-Records.md
Normal file
@ -0,0 +1,256 @@
|
|||||||
|
|
||||||
|
# Architectural Decision Records
|
||||||
|
|
||||||
|
This page attempts to cover how the project has progressed to where it is today, decisions made along the way that have shaped the development to better or worse & contributions made by other people.
|
||||||
|
|
||||||
|
It has been made so that new developers can more easily work on the project. The dates reflect time of development spent on the versions next to them.
|
||||||
|
|
||||||
|
|
||||||
|
This page was first written on **23.08.2018**, so decisions made before that are post fact.
|
||||||
|
Last Modified: **23.08.2018**
|
||||||
|
|
||||||
|
### 1.0.0 - 1.6.2 (1st - 27th December 2016)
|
||||||
|
|
||||||
|
First Java Project by Rsl1122.
|
||||||
|
|
||||||
|
**Development Goal:** Combine many of the different `about <player>` commands different plugins provide
|
||||||
|
**State:** At this state the plugin hooks into various plugins, to display statistics in game chat. More plugins are introduced during the month of December.
|
||||||
|
**Important Features:** `/plan inspect` and `/plan analyze` commands display information in game
|
||||||
|
**Plugin at this state:** https://www.spigotmc.org/resources/planlite-player-analytics-lite.34889/
|
||||||
|
|
||||||
|
### 2.0.0 (28th December 2016 - 16th January)
|
||||||
|
|
||||||
|
**Development Goal:** Display statistics on a website, hosted from a web server on the plugin.
|
||||||
|
**Development Goal:** Start recording own data
|
||||||
|
|
||||||
|
**Architectural Decision:** Chart Visualization: [Google Chart API](https://en.wikipedia.org/wiki/Google_Chart_API) _(Replaced in 2.4.0)_
|
||||||
|
|
||||||
|
Due to lack of knowledge of JavaScript programming language, an old Java library was chosen to perform data visualization. This library was already deprecated, but the term was not understood at the time. This API used URL parameters to source data for image graphs.
|
||||||
|
|
||||||
|
Impact: In 2.3.1 (13 days after release) Visualization stopped working due to URL size growing past the limitations
|
||||||
|
|
||||||
|
**Architectural Decision:** Web Backend: [Java ServerSocket](https://docs.oracle.com/javase/tutorial/networking/sockets/clientServer.html) _(Replaced in 3.5.2)_
|
||||||
|
|
||||||
|
Impact: Due to improper closing of resources the website functioned extremely poorly, and required two refreshes to load the page, leading to swap of server code later.
|
||||||
|
|
||||||
|
**Architectural Decision:** Server side rendering
|
||||||
|
|
||||||
|
Use html "rendered" to a String from data held in an object cache each time a request was made on the server. This decision was made as Java was the only language I knew.
|
||||||
|
Html files are first read from the jar, then placeholders are replaced with values.
|
||||||
|
|
||||||
|
Impact: Html generation is dependent on the server running on the plugin, or files generated by the plugin. Client side implementations will take a lot more effort in the future.
|
||||||
|
|
||||||
|
**Architectural Decision:** SQLite & MySQL
|
||||||
|
|
||||||
|
[Fe](https://www.spigotmc.org/resources/fe.723/) - plugin was used as an example for the database code. No SQL knowledge present.
|
||||||
|
|
||||||
|
Impact: SQLite has limitations in table alterations, leading to version transition bugs in the future.
|
||||||
|
|
||||||
|
**Architectural Decision:** Gather data to a cache _(Removed in 3.0.0)_
|
||||||
|
|
||||||
|
Data was placed into a cached object, and that object was saved when the player left.
|
||||||
|
|
||||||
|
Impact: Data loss on server shutdown, not so good use of memory
|
||||||
|
|
||||||
|
### 2.1.0 - 2.3.1 (17th - 30th January 2017)
|
||||||
|
|
||||||
|
**Development goal:** Bugfixes & Improvements
|
||||||
|
|
||||||
|
**Architectural Decision:** SQLite files as backups
|
||||||
|
|
||||||
|
Impact: SQLite has limitations in table alterations, leading to version transition bugs in the future.
|
||||||
|
|
||||||
|
### 2.4.0 - 2.6.2 (31st Jan - 22nd February 2017)
|
||||||
|
|
||||||
|
**Development goal:** Make the page more visually appealing
|
||||||
|
**Development goal:** Provide more data
|
||||||
|
|
||||||
|
**Architectural Decision:** Sessions
|
||||||
|
|
||||||
|
Impact: Riddled with issues related to not understanding how to calculate things in programming, and how to save sessions when the server goes down (all now fixed), these small objects turned out to be a great addition that is now heavily relied on the plugin. Possible drawback from them is the sheer number of them could cause performance impacts in the future.
|
||||||
|
|
||||||
|
**Architectural Decision:** Security by obscurity: Randomized code to access pages _(Removed in 3.5.2)_
|
||||||
|
|
||||||
|
Impact: Stupid from the inception, this was the first way of protecting against unwanted page snooping.
|
||||||
|
|
||||||
|
**Architectural Decision:** Single page JavaScript tabs
|
||||||
|
|
||||||
|
Impact: Single page to load for multiple tabs of information - less scrolling. Causes loading times to increase for server pages in the future.
|
||||||
|
|
||||||
|
### 2.7.0 - 2.8.4 (23rd Feb - 15th March 2017)
|
||||||
|
|
||||||
|
**Architectural Decision:** Chart Visualization: [ChartJS](https://www.chartjs.org/) _(Replaced in 3.6.0)_
|
||||||
|
|
||||||
|
Due to old visualization running out of character space in URL specification, the graphs stopped working, so a new graphing library was needed. After some searching ChartJS found to be a viable option. The script was served via CDN and all graph data was replaced into the html files via placeholders.
|
||||||
|
|
||||||
|
Impact: While amazing compared to the old graphs (and very good quality), ChartJS started to lag the websites around 10k points in the graphs. This lead to point reduction algorithm later.
|
||||||
|
|
||||||
|
**Architectural Decision:** Icons: [Font Awesome](https://fontawesome.com/) 4
|
||||||
|
|
||||||
|
**Architectural Decision:** Cards (Split tabs in 2 with css float propery)
|
||||||
|
|
||||||
|
### 2.9.0 - 3.0.2 (16th Mar - 9th May 2017)
|
||||||
|
|
||||||
|
**Architectural Decision:** Save data at first possible moment
|
||||||
|
|
||||||
|
A vital change to data gathering was made, where when an event fired, the data gained from that was saved to the database as soon as possible.
|
||||||
|
|
||||||
|
Impact: Data loss reduced - Still struggling with Session loss on shutdown
|
||||||
|
|
||||||
|
**Architectural Decision:** plotly.js for World Chart visualization _(Replaced in 3.6.0)_
|
||||||
|
|
||||||
|
Impact: Due to poor documentation, the map is limited to a 300x300 pixel square, which leads to it's replacement
|
||||||
|
|
||||||
|
### 3.1.0 - 3.5.1 (10th May - 9th July 2017)
|
||||||
|
|
||||||
|
**Architectural Decision:** Display Plugin Data on the website
|
||||||
|
|
||||||
|
Impact: While great for displaying data of other plugins, this leads to requirement for Bungee - Server connections to obtain data. This dependency on server specific plugin data turns out to be a very difficult dependency to remove.
|
||||||
|
|
||||||
|
### 3.5.2 - 3.5.5 (10th - 26nd July 2017)
|
||||||
|
|
||||||
|
23rd July *fuzzlemann* joins development.
|
||||||
|
|
||||||
|
**Development Decision** Moved to IntelliJ IDEA as IDE from Netbeans
|
||||||
|
|
||||||
|
### 3.6.0 (26th Jul - 1st August 2017)
|
||||||
|
|
||||||
|
**Architectural Decision:** Web Backend: [sun.java.HttpServer](https://docs.oracle.com/javase/8/docs/jre/api/net/httpserver/spec/com/sun/net/httpserver/HttpServer.html)
|
||||||
|
|
||||||
|
Impact: Higher performance, HTTPS & more reliable web server, that can use multiple threads & offers high customizability via code. Because this relies on sun.java code, the webserver may one day stop working if Oracle decides to remove this code from the JRE.
|
||||||
|
|
||||||
|
**Architectural Decision:** User Authentication: [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)
|
||||||
|
|
||||||
|
Impact: Easy to implement, but limited to HTTPS connections. HTTPS set up is difficult due to lack of a good tutorial. (Good tutorial is now available in this wiki)
|
||||||
|
|
||||||
|
**Architectural Decision:** Data Visualization: [HighCharts](https://www.highcharts.com/)
|
||||||
|
|
||||||
|
Impact: Very good performance compared to ChartJS and Plotly. Free for non-commercial projects, which prevents Plan from becoming premium unless a license fee is paid.
|
||||||
|
|
||||||
|
**Development Decision:** JFrog Artifactory used for a Maven repository _(Abruptly offline on ???)_
|
||||||
|
|
||||||
|
Impact: Reliance on another user from the internet hosting a JFrog Artifactory server. Server goes offline at some point, getting the project back up and running takes a while.
|
||||||
|
|
||||||
|
### 3.6.2 - 3.6.4 (2nd - 18th August 2017)
|
||||||
|
|
||||||
|
**Architectural Decision:** Guava Cache _(Removed in 4.1.5)_
|
||||||
|
|
||||||
|
Impact: 1.7.X servers become unsupported because Guava 10 is not shaded into Plan
|
||||||
|
|
||||||
|
**Architectural Decision:** Locale uses Enum for keys (no default values) _(Improved in 4.4.2)_
|
||||||
|
|
||||||
|
Impact: Due to default values being absent from the locale keys, it becomes difficult to add new messages.
|
||||||
|
|
||||||
|
### 4.0.0 (19th Aug - 1st October 2017)
|
||||||
|
|
||||||
|
**Development goal:** Support BungeeCord networks
|
||||||
|
|
||||||
|
**Architectural Decision:** Database Schema based on Server table
|
||||||
|
|
||||||
|
Impact: Multiple servers are supported, more join operations in queries. Most of old data has to be discarded due to bad database schema
|
||||||
|
|
||||||
|
*fuzzlemann* stops developing Plan, JFrog Artifactory goes down, MySQL testing server goes down
|
||||||
|
|
||||||
|
Impact: It takes a while to get a testing set up back up and running. Testing set up is installed on a laptop.
|
||||||
|
|
||||||
|
**Development Decision:** Do not accept unreliable changes to vital parts of the release cycle, such as addition of Jenkins, snapshot repositories or PRs that remove all files at some point in their commits.
|
||||||
|
|
||||||
|
**Architectural Decision:** MySQL Connection pooling: DHCP2
|
||||||
|
|
||||||
|
Impact: Improved performance
|
||||||
|
|
||||||
|
**Architectural Decision:** Processing Queue
|
||||||
|
|
||||||
|
Impact: Reduced reliance on BukkitScheduler
|
||||||
|
|
||||||
|
### 4.0.1 - 4.0.7 (2nd Oct - 13 November 2017)
|
||||||
|
|
||||||
|
**Development Goal:** Bugfixes to network functionality
|
||||||
|
|
||||||
|
### 4.1.0 (14 Nov - 2nd December 2017)
|
||||||
|
|
||||||
|
**Development Goal:** Improve visual aspect of the website.
|
||||||
|
|
||||||
|
**Architectural Decision:** Admin Dashboard Template: [Admin BSB](https://gurayyarar.github.io/AdminBSBMaterialDesign/index.html)
|
||||||
|
|
||||||
|
Impact: Beautiful website, with many functional features, such as a searchable player table. Increases server page load time.
|
||||||
|
Impact: Professional look brings more users
|
||||||
|
|
||||||
|
### 4.1.1 - 4.1.7 (3rd Dec 2017 - 2nd March 2018)
|
||||||
|
|
||||||
|
**Development Goal:** Fix bugs & improve existing features
|
||||||
|
|
||||||
|
**Architectural Decision:** Attempt to reduce Bungee - Bukkit connection reliance by transferring pages via MySQL instead.
|
||||||
|
|
||||||
|
Impact: MySQL database size on disk goes through the roof, connection reliance is still there because requests need to be transferred in some way between the servers. Ultimately reverted, but setting transfer is kept around.
|
||||||
|
|
||||||
|
**Architectural Decision:** Removed Google Guava usage
|
||||||
|
|
||||||
|
Impact: 1.7.X servers supported again
|
||||||
|
|
||||||
|
**Architectural Decision:** Refactor plugin to different "Systems"
|
||||||
|
|
||||||
|
Impact: Easier to develop.
|
||||||
|
|
||||||
|
**Bad Architectural Decision:** Make "Systems" accessible via static `getInstance()` methods
|
||||||
|
|
||||||
|
This decision came from exposure to Kingdoms API, which uses getInstance() methods that seemed convenient.
|
||||||
|
Unforseen at the time, this increases their usage everywhere and this can lead to a lot of code smells further down the line.
|
||||||
|
|
||||||
|
### 4.2.0 (2nd May - 7th April 2018)
|
||||||
|
|
||||||
|
**Development Goal:** Support Sponge
|
||||||
|
|
||||||
|
**Development Decision:** Keep a `html` branch up to date with changes to the html files for easier customization
|
||||||
|
|
||||||
|
### 4.3.0 - 4.3.2 (3rd Apr - 31st May 2018)
|
||||||
|
|
||||||
|
**Development Goal:** Comply with GDPR (Anonymize IPs)
|
||||||
|
|
||||||
|
### 4.4.0 - 4.4.4 (1st June - 23rd August 2018)
|
||||||
|
|
||||||
|
**Development Goal:** Make it easier to develop Plan
|
||||||
|
|
||||||
|
**Architectural Decision:** Data structure
|
||||||
|
|
||||||
|
Data structure was refactored to a Key - Supplier model, where objects don't know what data they contain.
|
||||||
|
|
||||||
|
Impact: Massive increase to speed of addition of features to the web pages because changes do not cause large amount of methods to be added. Extremely flexible to extend. Easy to test.
|
||||||
|
|
||||||
|
**Architectural Decision:** Move Inspect page generation to BungeeCord
|
||||||
|
|
||||||
|
Impact: BungeeCord servers start crashing due to hiding bug in java UrlConnection timeouts being set with System properties. This takes a month to hunt down, and a lot of architectural changes are made as attempted fixes.
|
||||||
|
This bug was hidden before, because Bungee made less connections per day.
|
||||||
|
|
||||||
|
**Architectural Decision:** Locale rework
|
||||||
|
|
||||||
|
Because locale did not contain default values it was difficult to extend. Addition of default values & split to an interface instead of a single enum.
|
||||||
|
|
||||||
|
Impact: Easier to update locale, easy to test.
|
||||||
|
|
||||||
|
**Architectural Decision:** MySQL Connection Pool: HikariCP
|
||||||
|
|
||||||
|
As an attempt to fix Bungee crashing
|
||||||
|
|
||||||
|
Impact: Performance increase, no impact on the bug
|
||||||
|
|
||||||
|
**Architectural Decision:** Bungee - Bukkit Connections: Apache HttpClient
|
||||||
|
|
||||||
|
As an attempt to fix Bungee crashing
|
||||||
|
|
||||||
|
Impact: Better API, no impact on the bug. Bug later fixed with two system properties
|
||||||
|
|
||||||
|
**Architectural Decision:** Database patch system
|
||||||
|
|
||||||
|
Patch system checks if the patch has been applied to the database, instead of relying on a single number to tell it.
|
||||||
|
|
||||||
|
Impact: More reliable database changes from version to version, allows patching after a patch fails.
|
||||||
|
|
||||||
|
### 4.5.0 (11 August 2018 - ?)
|
||||||
|
|
||||||
|
**Development Goal:** Remove usage of Bungee - Bukkit connection requirement
|
||||||
|
**Development Goal:** Remove use of `getInstance` methods
|
||||||
|
|
||||||
|
**Architectural Decision:** Dependency Injection: [Dagger](https://google.github.io/dagger/users-guide)
|
||||||
|
|
||||||
|
Impact: Removal of `getInstance` methods is easy because Plan is already split into module like "Systems". Some cyclic dependencies exist.
|
||||||
Loading…
Reference in New Issue
Block a user