Challenge Overview
Challenge Objectives
-
Design API specification (Swagger)
-
Create database ER diagram
Project Background
-
Telecom providers sell products such as broadband and mobile phone contracts. These contracts consist of products of different types and capabilities and that are then sold in different markets. In this project we’re building a forecasting tool to predict variables like volume base, gross adds, churn, net migrations, average revenue per customer, etc
-
In this challenge we’re designing application backend API and database models
-
In the follow-up challenges we will develop the backend API, integrate with the frontend and third party APIs and build a test suite.
Technology Stack
-
Swagger Open API Specification
-
ERD
-
MongoDB
Resources
Application designs are available at https://marvelapp.com/3jia89d/screen/58091361 . See the below description for individual screen features.
Individual requirements
We’re aiming to create three things in this challenge:
-
REST API specification document (swagger)
-
Database collections structure (ER diagram)
-
Screen API calls mapping - a document detailing which API endpoints should be called on each screen
The central feature of the app is forecasting the KPI values (volume base, gross adds, churn, net migrations, average revenue per customer). Data will be imported from a CSV file into the database (sample data file attached in the forums). From the imported data we need to create lookup endpoints for brands, products, markets (pay attention to this in the data model - do we store lookup data in separate collections, or we create indexes in the data collection?).
Next step in the end to end worfklow is creating a forecast. Inputs to the forecast are the imported data and values for “KPI driver” attributes (each of them will essentially mark the significance of some input data features). See this screen as an illustration https://marvelapp.com/3jia89d/screen/58091357 (note that there is only one set of KPI drivers, not multiple sets as shown in the design). KPI drivers list and their allowed ranges will be a fixed list (we don’t have it yet) and the API should have a lookup endpoint that returns the configured KPI drivers.
Each forecast will also have a name, version (user specified values), list of selected products, brands, markets and a timestamp.
Implementation Note: To create the forecast, the backend has to select the data from the database (based on the selected brands/markets/products), call the forecasting module, and save the forecast results to the database.
Forecast outputs will be the timeseries data - same data used for the input, except that the dates go up to 5 years in the future. We will assume the forecast module will accept and return only monthly data and aggregating it to show quarterly/yearly results will be done in the frontend - backend only needs to provide endpoints to:
-
List the available forecasts (with pagination support, grouping by title), with versions
-
Get individual forecast+version (inputs, historical data and forecast results)
-
Update a forecast+version (change name, version)
-
Delete a forecast+version
Reforecasting is a feature that allows the user to create a new version of an existing forecast - name remains the same, but version, KPI drivers, brands, markets and products list is updated, The user has the option to just run a forecast and get results, without saving to database (what-if analysis, ex clicking on the refresh button in this screen https://marvelapp.com/3jia89d/screen/58091357). Once the user is happy with the results, the new version can be saved to the database (“Save new version” button).
We also need to save per user forecast display settings for each forecast - this includes displayed charts list (with order), and settings of each of the charts (let’s consider this as a JSON object - we don’t have the available settings yet).
Each forecast has multiple versions, but only one of them is considered a baseline forecast - that’s the role of “Lock version” feature in the app, so the update forecast version endpoint should also allow updating lock status of a forecast version
Another user setting that needs to be saved is Favourite charts - each entry links to a specific forecast version and a chart. Frontend will use get forecast version and get chart settings endpoints to display each of the favorite charts.
Data export will be done by the frontend, and should not be considered in the backend.
App will also have a login screen (username/password), so we need CRUD user management endpoints - two user levels: regular user and admin (only difference for now is that admin users can lock forecast versions). All api requests should require a JWT token for authentication.
Search and user profiles (image, name) are out of scope.
General for all requirements
Use camelCase for all JSON data attribute names, TitleCase for entity names.
What To Submit
Submit a Swagger API specification
Submit the ER diagram
Submit api calls to screen mapping diagram