Challenge Overview
Project Overview
The Department of Energy’s Building Technologies Office (BTO) is developing a modeling system called “Scout” that will help measure the energy conservation potential of new technologies on a national scale. BTO calls these new technologies “energy conservation measures” (abbreviated as ECMs).
Competition Task Overview
In this challenge, we are going to build the REST API to support the web application.
Please make sure you check the design for the web app here since you will need to carefully go through it to understand the description below: https://marvelapp.com/49f09ed
Data Source Overview
Generally, all the data used in the web app comes from this github repo: https://github.com/trynthink/scout/tree/master/web
1. ECM Summaries page will draw from ecm_prep_web.json (for the summary list and plots) and the individual ECM JSONs from /web/ecm_definitions (for downloading or editing existing ECMs). There’s also a package_ecms.json file that’s used for packages feature.
2. Analysis Results page will draw from ecm_results_web.json
3. Market Calculator page will draw from mseg_res_com_cz_web.json
More details in the sections below.
Also check out this data usage guideline which could be very useful: https://docs.google.com/document/d/1hseafMWOKEbMxDkz2SzNE0d9WpzLhg_6YN7jDwtqtE8/edit?usp=sharing
Use Cases Overview
This web app is a readonly web app, i.e. users won't be able to update any data, instead all the data in the web app can be viewed or downloaded only. The users can also upload a custom file to view in the web app.
ECM Summaries -> Dashboard
- This page is backed by the data from the ecm_prep_web.json file, each row on this page either refers to a Single ECM or an ECM Package.
- The user can upload custom files following the same format as ecm_prep_web.json file, however these files are only available to the user with the user's session (i.e. if the user closes the web app these files will be gone). Users can also delete any custom ‘ecm_prep_web.json’ file uploaded in this session using the dropdown arrow from ‘Custom ECMs’.
- The user can search for ECMs by name
- The user can see the detailed ECM view / plots when expanding a row, the API needs to provide endpoint(s) get necessary data
- The user can filter records using the filters in the left sidebar
- Each ECM row will match exactly one of the JSONs from /web/ecm_definitions folder. So the download action will just download that corresponding JSON file. Edit will load the content of that JSON file and open the 'Add New ECM' -> Single ECM page with all fields pre-filled. Note the edit feature is only available for the default ecm_prep_web.json file which is pulled from the github repo. For custom file, the user will be able to delete that row from the view (and/or file).
- The ecm_prep_web.json file also contains a list of packages (also reflected in ecm_packages.json) which are displayed as Package rows on the web app. Download will download the ecm_packages.json file, edit will load the content of that specific package into the 'Add New ECM' -> 'ECM Package' page with all fields pre-filled.
ECM Summaries -> Add New ECM
- The user can Add New ECM or Edit ECM (not shown in the design, but basically same as Add New ECM), either Single ECM or ECM Package.
- When user clicks Generate ECM, the backend should generate a new JSON file (either the individual JSON file or the ecm_packages.json file), and download it to the user's computer. And if the 'Send ECM for Review' option is checked, the system will email that new JSON file to a configured email address for approval. For an ECM Package, it will download the entire ecm_packages.json file with the specific package updated, but the email should only send the trimmed ecm_packages.json file that only includes the specific package.
- You can check the ECM JSON schema here: http://scout-bto.readthedocs.io/en/latest/ecm_reference.html#ecm-json-schema
- We also have the overall outline of the fields in the ECM web form here: https://docs.google.com/document/d/1f6J-3t4C4j417-gxqZvcPrydqYKM85ZNjsjhSvfsvF8/edit
Analysis Results
- The pages under this tab is all about graphing / charting, the data comes from ecm_results_web.json, in fact we have implemented a prototype for these pages and we provided the code in the forum for your reference so you can see how that works
- The user can upload custom files following the same format as ecm_results_web.json file, however these files are only available to the user with the user's session (i.e. if the user closes the web app these files will be gone). Users can also delete any custom file the upload in this session.
- The user can filter records using the filters in the left sidebar
- The user can switch between the different tabs to see different charts
Market Calculator
- The data for this page comes from the mseg_res_com_cz_web.json file
- This page provides a wizard like UI to guide the users to get to the final results using the calculator.
- The existing calculator page is hosted here which you can check for reference: https://trynthink.github.io/scout/calculator.html
- The source code for the calculator can be found here: https://github.com/trynthink/scout/tree/gh-pages
Challenge Requirements
- You must provide full implementation for a set of node.js based API to support the blue use cases above.
- The API must be RESTful.
- The API will not have authentication or authorization, but it will need to be able to maintain a temporary session for each user so it can properly handle each user's custom files.
- You may use Postgres or SQLite if you feel that's necessary or helps improve performance or data processing.
- Performance must be taken into consideration because the JSON files the app needs to read from may be very big, it will not be practical to simply load the whole file to the browser, which means the API will need to make sure it only sends the necessary data to the web frontend
- The API should get all these default json files from a configurable path
- Good documentation on the code
Testing
You must provide postman collection for the API and also for testing.
Technology Overview
Node.js
JSON
REST
Final Submission Guidelines
Submission Deliverables
Below is an overview of the deliverables:
- Full API code as described above
- Complate and detailed README file in markdown format explaining how to configure / deploy / test / verify the code
- A file describing the mapping from API endpoints to features on the pages.
Final Submission
For each member, the final submission should be uploaded via the challenge detail page on topcoder.com.