Skip to content

Commit

Permalink
Remove background (will appear in a blog post)
Browse files Browse the repository at this point in the history
  • Loading branch information
kellpossible committed Nov 17, 2023
1 parent 77313c0 commit 6456840
Showing 1 changed file with 0 additions and 38 deletions.
38 changes: 0 additions & 38 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,41 +157,3 @@ api_key="SECRET"
```

Options can also be specified using the `AVALANCHE_REPORT` environment variable, with a multiline string containing all options specified in TOML format. See the [`fly.toml`](./fly.toml)'s `env.AVALANCHE_REPORT` key for an example of this in a deployment.

## Project Background

This section is written from my personal perspective (Luke Frisken) as the person who started writing this software to serve as a background for other who are interested in motivations and direction for the project.

The project was started in January 2021 in collaboration with members of the [Georgia Avalanche and Snow Conditions🇬🇪ზვავის და თოვლის შესახებ](https://www.facebook.com/groups/830534093958221) community in order to power [avalanche.ge](https://avalanche.ge). We wanted a platform to allow us to produce and publish avalanche forecasts. Research of the existing options was conducted, I eventuall found some exisiting open source projects:

- [`ac-web`](https://github.com/avalanche-canada/ac-web) (deprecated?)
- [`albina-euregio`](https://gitlab.com/albina-euregio) (hosted on <https://avalanche.report>)

`albina-euregio` seemed like the most promising project to adopt, it seems to be developed and adapted to the needs of the forecast regions it is serving, but if we had an allocated budget for paying someone to do the work to make it useful for Georgia, that's probably what we would have done, and maybe will do in the future. However with a budget of $0 with no interest for funding, and deadline of "now" (season had already started), we had to rely on volunteer work and a desire to achieve minimum viable product, as soon as possible.

For my own part, launching into adopting a complex (but fantastic looking) project like `albina-euregio` felt too much like my day job, and could potentially take many weeks or even months to produce something we could use for a forecast. It also has many components which need to be hosted, which rely on NodeJS (not exactly known for its slim resource consumption), and that hosting and associated maintenance needs to be paid for with our budget of $0. For motivation to remain high, I decided to "re-invent the wheel", and take a different approach.

I'm personally motivated by a desire to help this community and my love for Georgian mountains, people and culture. I also can see how a project like this could be useful for other communities which also lack the resources to develop their own comprehensive solution or to adopt the existing ones. With this in mind I intend to create a solution from the ground up with a goal to service multiple regions and languages, with minimal cost or effort required to deploy on the part of the users. It's also just fun to work on software projects like this which combine multiple interests, and has real-world applications. It can also serve as a test-bed for many ideas I have about how to improve avalanche forecasting in the future.

We started with the primary goal of minimum viable product in as short a time as possible, and I knew that we needed to iterate quickly in order to establish our forms for entering data. The initial solution I produced was using Google Sheets, yes you heard it correct, a spreadsheet! This has the benefits that it's very fast to iterate, it's completely free, anybody can make contributions, or run it themselves without requiring any techninical knowledge, and it even has live collaboration features. In theory vendor lock-in is reduced with the possibility to export to spreadsheet file (in practice this isn't completely true due to the use of google sheets specific functions).

And so a mother of all avalanche forecasting spreadsheets, [Avalanche Forecast Template](https://docs.google.com/spreadsheets/d/1vkav8SNr4uv1sOtc6mp2eTDa7nYTj5k852T1rD8F_8Y/edit?usp=sharing) was completed in a few weeks. It has localizations for English and Georgian, a sheet for producing the forecast and a sheet formatted for printing to PDF which we could share with our community on Facebook. It also has dynamically generated diagrams which were the inception for the software in this repository, which contains diagram rendering code in [`src/diagrams`](./src/diagrams/), which can render diagrams to png images to be embedded dynamically in the spreadsheet using the [`IMAGE`](https://support.google.com/docs/answer/3093333?hl=en) function.

I chose to implement this software using [Rust](https://www.rust-lang.org/) with a long view for the project, because it's what I use primarily for my day job, and I have also implemented several other similar style personl projects (e.g. [`email-eather`](https://kellpossible.github.io/email-weather/)) with it. The language is well suited to reliable, self-contained software which uses minimal resources to run. It also offers an opportunity to access native libraries like [`GDAL`](https://gdal.org/index.html) for implementing interesting GIS related features in the future. There's something satisfying about crafting efficient systems from a climate perspective too! I realise this does place a barrier for entry for contributors over using something more popular like TypeScript/Javascript, but in my day job we are already migrating to Rust for all new projects or rewrites in preference to TypeScript it is going well!

Once we had a PDF version of the forecast working the first stage of the project was successful. It was evident however that there were several problems with the spreadsheet approach that needed addressing:

+ Forecasters were accidentally making edits which break the spreadsheet.
+ This can be partially be addressed by locking cells, however when forecasters copy the template to create the forecast they can unlock them.
+ Re-ordering the problem types is error-prone.
+ Using the spreadsheet is more difficult than a website and probably requires more training.
+ Producing the PDF is a multi-step process, and forecasters were forgetting to produce the Georgian version, even though that functionality is available.
+ Formatting on the PDF was sometimes a bit wonky.

Most of the friction encountered was on the PDF generation, and sharing via Facebook posts. To this end I embarked on creating a website to replace this role. The first step was to have a way to share forecast PDF files on the website, so I created a "Published" folder in our shared google drive, where published forecasts can be placed, and this software would, when handling a request, fetch available forecasts and present them to the user on the index with links to download the PDF files. With the help of @PSAvalancheConsulting we added a forecast area map, along with highlighted forecast elevations to our home page. This served us well for the remainder of the season. I added some analytics collection capability so we could observe website traffic in relation to published forecasts, and some caching to avoid exceeding the Google Drive API request limits.

With the first season over, we had some time to work on the next stage, publishing forecasts via HTML instead of PDF. This would make the forecasts more accessible on mobile, and reduce the overhead on forecasters for producing PDF files in various languages. Taking a very similar approach, the "Published" folder is re-used, instead of PDF files, forecast spreadsheets are moved here when they are ready to be published on the website. The software parses these sheets to extract only the relevant data, and renders the forecast as HTML, essentially using Google Drive like a CMS, to ammend a forecast one only needs to edit the spreadsheet!

From a technical perspective, the HTML rendering and interaction on the website is mostly achieved through the use of [`HTMX`](https://htmx.org/), instead of using a more popular Javascript single page application framework (SPA) like React. This hearkens back to the older days of the internet when times were simpler, one could spin up a website with a few lines of PHP. This is for the most part, fundamentally a simple website, we present information to users on almost-static pages. Using hyperlinks, HTML forms, and HTMX has allowed me to implement most of this functionality on the backend in a single language (Rust). What little low latency client-only interaction we do need to support can be done with a couple of snippets of Javascript and simple self-contained libraries like [`leafletjs`](https://leafletjs.com/). My working theory is that there is simply no need to introduce the [significant complexity associated with adopting a Single Page Application](https://htmx.org/essays/a-response-to-rich-harris/#the-elephant-in-the-room-complexity) javascript framework approach, nor does this team of 1 developer have the [complexity budget](https://htmx.org/essays/complexity-budget/) available to adopt it. In a sense this project for me serves as a real-world experiment to test that position.

As of this writing (November 2023), the plan is to complete a more professional looking website design before the season begins, with the ability for forecasters to edit content on the home page (such as announcements) without requiring a website re-deploy. We will again make use of the forecast spreasheet template to capitalize on the work done to create it, and retain flexibility if we wish to change it, however the long term goal is to eventually bring the data entry capability over to this server, making this software an all-in-one solution for avalanche forecasting.

0 comments on commit 6456840

Please sign in to comment.