1. Core Requirements
The CMES project consists of a multi-application process which delivers continuing medical training information to people in low-resource locations. The SkillRX project will deliver a new, fully tested application which will replace the existing CMES Admin Panel, which is the content management portion of the system. Delivery of the application will include migration of all data from the previous CMES Admin Panel with no disruption to the functioning of downstream applications.
There are four applications involved in this process.
Users representing medical training providers log into SkillRX. They create a Topic, mark that Topic as being in a particular language, upload individual Training Materials which are associated with that topic, and tag the topic for search purposes.
The application uses Azure's file storage REST API to deliver and manage XML, txt, csv, and media files in Azure file storage.
The XML Builder constructs XML files describing the uploaded topics, resources, and taggings. The app prepares a set of xml files for each language:
- providers
- new topics
- tags
- tags and titles
Training material media files are referenced in the XML by file name only, with no path.
The XML files are placed in the same Azure file storage and organized by language alongside the media files. SkillRX will be taking over the responsibility of building those XML files and placing them in the correct locations. This application will no longer be needed when SkillRX goes into production.
The CMES Pi application, running on a Raspberry Pi or another device, downloads the XML files, parses them, and downloads the training material media files. It then presents an interface which allows local health providers to find and view the topics and their related training materials. Subsequent downloads get only new or updated files. The process is designed to make the best of limited internet access and to allow full access to topics and materials when the internet is unavailable.
The CMES Pi app is currently in use at locations around the world.
Mini computers will be going into service this summer. These will run an application driven by a local database kept up-to-date by the csv and media files delivered to Azure by SkillRX.
- Most recent version of Rails
- Use defaults unless there’s a good reason to differ, including asset setup, rails views, Hotwire, etc.
- Install DartSass (the “CSS” option when creating the app; do not use the Boostrap option, which would install Yarn)
- We are using bootstrap but installing it separately
We will provide a link to a full ERD soon, including field details where appropriate. For now, this diagram includes images of Table diagrams with the relevant sections.
Changes in architecture internal to the application may be masked by interfaces with existing downstream applications; a core goal is for us to build this app well while minimizing changes to the downstream apps. Ideally we will not require any changes to those apps.
Key changes from existing CMES architecture:
- naming conventions will follow Rails conventions, so field and table name changes will have to be accounted for when scripting data migration from the existing app.
- Authors no longer exist
- Regions are a model (providers can have many regions)
- Languages are a model (topics must have a language)
- States are enumerables
Topics are the content heart of the app. Along with their related file uploads, they represent the training materials that are uploaded by providers and delivered to users.
- Belongs to Language
- Belongs to Provider
- Has many taggings (dependent on specifics of tagging solution TBD)
- Has many attached training_resources
Table diagram, including fieldnames from import:
Topics may be archived (see notes on schema). Archival will take the place of deletion in the UI. Actual deletion will only be available to admins and the UI for admins will clearly distinguish between archival and deletion.
Admins have access to all topics. (this is not settled; admins may end up limited to managing providers, users, and their association)
Non-admin users can do everything except delete (they can archive) topics related to their provider(s).
Changes from existing application:
- Topic volume and issue are no longer needed. Users do not need this or have awareness of it.
- Topic Counter is defunct.
- Category ID is defunct.
- Authors are defunct.
- Multiple changes to key created field: The two fields storing the creation month and year will be a single date field (Name TBD). (need to confirm) Created_months in the existing app are mapped in English and Spanish and stored as strings, so we will need to check on the reason for this to make sure they do not meet a need we do not understand.
Our requirements previously had training resources as their own model with one attached file each. After further discussions with stakeholders, we are simplifying this.
Training resources are simply a has_many_attached on Topics.
The requirements within our app are simple and hold to standard Rails practices: we will use the default has_many_attached with validations.
Size limits on files are TBD, but we should go ahead and set reasonable limits during our initial development. Since this is in support of getting these media files to machines in low-resource areas where internet may be slow, unreliable, and expensive, we should aim for a balance of limiting file sizes and maintaining quality.
Should support standard content types and prohibit dangerous content types:
- Standard image types: GIF, PNG, JPG, JPEG, SVG (WEBP and AVIF?)
- Video: MP4
- Other requirements are not yet established. PowerPoint? Stakeholder has specifically said there will be no Word files, which presumably also means no Excel files.
Providers manage their own set of topics. Non-admin users have rights one or more providers. The most frequent use of the app will be users logging in to manage their provider’s topics.
- Has many Topics
- Belongs to Region
- Has many Users
Name must be present and unique.
Table diagram:
Only admins can manage providers.
In the existing app, languages are a text field on Topic and there are two languages–English and Spanish, though there is hope of supporting more languages in the future. We’re moving this to a table for consistency, for ease of adding new languages, and for extending information about languages.
- Has many Topics
Table diagram:
Seeds will set up these records:
- English
- Spanish
The Language model offers a method called file_storage_prefix which will return an empty string for English or, for any other language, the first two characters of that language, capitalized, followed by an underscore. See the Azure delivery requirements for usage.
NOTE ABOUT SUSTAINABILITY: Realistically, we are not likely to deal with a proliferation of added languages, much less with adding a language that happens to begin with the same two characters as another language. This naming convention is enough for now.
See XML Generation application requirements for more information about the current application's storage names/locations.
Only admins can manage languages.
Topics can be tagged. The tags are delivered to the CMES Pi app via XML and are integrated into the search feature on that app and in SkillRX. Topics can have multiple tags. The solution should have the usual tagging trimmings (to be determined during design phase, which is ongoing, but examples are: autosuggest existing tags, create new tags on the fly, allow multi-word tags, etc.) plus one custom requirement: cognates.
Tags are scoped by the Topic language. When tagging a topic, users will see only tags scoped to the selected language. Tags added when tagging a topic will be scoped to the topic's language. This implies a strong argument for locking the UI to a particular language when creating a topic and for not allowing that topic's language to be changed.
Tags can be related to other tags as cognates. When a tag is added to or removed from a resource, all of its cognates are added or removed as well. We presume tag cognates should also observe the language scope.
The application will need an admin tool to allow tag management (add, update, delete) with changes to tags reflected on the relevant tagged content.
Tag models are not spelled out in detail in the schema. We have flexibility in choosing our approach to meeting these requirements.
UNCLEAR REQUIREMENT: The existing application's database allows for tagging of Providers but there appears to be no User Interface. Do Providers also need to be tagged? If so, what is the effect of those tags?
User, session, and authorization needs are fairly straightforward. We will use the new Rails 8 authentication generators. Has and belongs to many Providers (optional)
There are only two roles for logged-in users: Administrators and Contributors. Users can be contributors for one or more providers (the optional has and belongs to relationship). Administrator status will be a boolean. If a user is not an admin, they must have at least one provider.
An admin does not have to be associated with any providers. Admins can see all content. (This may change based on further discussions with the stakeholders, but we are sticking with this course for now.)
The issue of how this app would manage files within the existing Azure storage has been a key challenge. This is now resolved. Within SkillRX, we are managing and storing media files in the standard Rails way and in a storage repository unique to this application. These files, along with XML, txt, and csv files, will also be delivered to Azure storage via a separate process we will define in this requirements document. This gives SkillRX a distinct set of boundaries and allows us to treat the Azure delivery process as an interface.
Final delivery of the working application will include a scripted import of existing application data and media, and an execution plan for migrating to the new application.
Remote devices must be blind to the transition from the former app to SkillRX. The migration must not require the remote devices to resync any content. The keys to this are the topic months and years and the creation dates for uploaded files.
Topic ID values are used in the file naming conventions for stored media files. All existing files have names that include their topic's ID in the current system. Because of this, imported topics must maintain their IDs from the old application. IMPORTANT
The application currently has a draft import process and the related data files. Developers who wish to work with realistic data should:
- Open a Rails console
- DataImport.import_all
The current process does not maintain Topic ID values.
The media import process will:
- For each record in cmes_files.csv
- Find the related topic
- Read the media file from Azure
- Attach that file to the topic
- Make whatever alterations are needed to our records to ensure that our Azure sync does not resync these files TBD
This process will not change the files stored in Azure in any way.
We will need access to an up-to-date copy of all data as part of the migration. We will work out details in the execution plan.