Skip to content

HOWTO prj framework_architecture

Jump to bottom
steveoro edited this page Jul 5, 2021 · 3 revisions

HOWTO: Project & Framework architecture, version 7+

Bird's eye view

Two web-apps are currently available:

  1. Main client front-end UI (project goggles_main); stand-alone Rails application used to search or check meeting results, swimmer progress, register new timings from live events (goggles_chrono) & request their storage, mainly by way of API requests (goggles_api). It can be run as a composed Docker container.

Goggles-v7 main

[UPDATE 2020-05-05]: goggles_chrono has been merged permanently into goggles_main to simplify the overall build pipeline & reduce stack size & memory requirements for the running host.

  1. Admin dashboard & interface UI (project goggles_admin); stand-alone Rails application for most manual administrative tasks. It can be run as a composed Docker container.

Goggles-v7 admin

Both Rails applications are using the same MySql/MariaDB database.

All models and most of the authentication utilities are stubbed inside the reusable core DB engine (project goggles_db), which is a Rails namespaced engine used by all other framework projects.

A third Rails application, Goggles Import (project goggles_import, which was actively used up to version 6 for scraping published results and meeting calendars from other Web sites), with an architecture basically analogue to "Goggles Admin" is currently planned for development but held until further notice.

Both "Goggles Admin" & "Goggles Import" talk the main front-end ("Goggles Main") via API calls which, in turn, serializes changes to its back-end database.

There are 2 ways of changing & updating with the data stored in the database:

  1. by direct API call, usable when all required fields are known;
  2. by enqueueing "micro-transactions", ideal when some of the required associations will be available or known later.

About micro-transactions

Each micro-transaction involves updating or creating a single specific database entity (such as Meeting or MeetingIndividualResult) and comes with implicit bindings to other linked entities (such as MeetingSession or MeetingProgram) or sub-entities (such as CategoryType or EventType).

At runtime, when considering each individual transaction, all linked data may be directly available allowing the transaction to complete. At some other time, obviously this may not be the case.

Thus, each micro-transaction can be flagged as:

  • Solvable, if it can resolve all of its linked sub-entities data.
  • Unsolvable, if allegedly some of its needed data will either become available later on or are completely missing. A micro-transaction can remain in the queue indefinitely in this state & can request manual intervention to be solved.
  • Solved & erasable, if all the required bindings have been solved and the micro-transaction row can be consumed.

Micro-transactions are processed by the Main application as ActiveJobs and manually managed by the Admin (v2) front-end.

                            +--------------+     +----------+    +----------+
                     +----> |   solvable   +---->+  solved  +--->+ erasable |
                     |      +--------------+     +----------+    +----------+
                     |
new ImportQueue +----+
      row            |
                     |      +--------------+
                     +----> |  unsolvable  |
                            +--------+-----+
                                     |               check for data
                                     +-----------+->    changes
                                                 ^
                                                 |         +
                                                 |         |
                                                 ^---------+

Framework projects recap

  • goggles_db: shared DB engine

    Namespaced Rails Engine encapsulating all main models and classes, strategies, decorators, spec factories and core support tasks and most of the basic configuration and settings.

  • goggles_api: API application

    Stand-alone Rails application that holds all the API endpoints with JWT-based authentication. Can be run as a stand-alone Docker container.

  • goggles_main: Main UI client web app

    Main Rails web client / front-end. Includes both goggles_db & goggles_chrono gems. Can be run as a composed Docker service, which includes a running goggles_api container image (plus the actual database engine).

  • goggles_admin2: Admin dashboard web app (v2)

    Stand-alone Rails application that implements an admin web interface for managing the database and importing new data sets. Can be run as a stand-alone Docker container.

Footnote regarding goggles_chrono (ex-Chrono UI sub-app)

Any reference to the goggles_chrono repository or Project you may find along in the source code or in this Wiki, has to be intended as referring to any /chrono endpoint or Chrono::-namespaced object that now resides in goggles_main project.

The goggles_chrono project started as as a Dockerizable stand-alone application, very much alike goggles_admin2.

Then, it evolved for a short while into a mountable Rails Engine (used by the Main UI) and, again, ended up being moved directly into goggles_main's repo to simplify the overall build pipeline.

Moreover, as of this writing (2021/05), encapsulating Webpacker assets inside a mountable engine is still too much convoluted for a Rails 6.0 application and there isn't (yet) a proper "Rails way" to do it.

Clone this wiki locally