MVP demo application

[felix-b]

We need an MVP demo application that would demonstrate the strengths of the framework.

[felix-b]

MVP application spec

Here I summarize a discussion that took place offline

Requirements

Create a billing application for a power plant operator. The application will be responsible for:

• collecting electricity consumption data
• calculating charging and billing information
• producing bills to customers
• processing customers' payments and manage debt collection

The application will serve the following actors:

1. Sensors (running on an IoT cloud): push consumption data to the application
2. Operator users: use administration UI for back-office management
3. Customers: use personal dashboard UI for payment and periodic reporting

Brief requirements:

1. a customer can have one or more associated sensors
2. each sensor is associated with a tariff plan; the association can be changed at any time
3. tariff plans are managed globally
4. customers are billed monthly
5. payments are charged through an online payment service (e.g. PayPal).
6. payments must be available in different currencies, including cryptocurrencies such as BitCoin -- according to customer's choice.

[felix-b]

Comments and suggestions are welcome! A BDD-style specification (given-when-then) would be very useful...

[felix-b]

Proposed analysis

Concept summary

This is a typical event processing system, where we:

1. receive a stream of sensor events (kWh meter readings)
2. receive a stream of configuration events (customers/pricing configuration)
3. process sensor events by applying pricing plans which are/were effective at the time of sensor reading
4. mutate the state of the system by storing results in customer invoices

Why event-driven? Since this system charges customers for a service, an inevitable situation must be handled where the system incorrectly charges a customer because of data corruption or human mistakes. The system must be robust in replaying its functions over the corrected inputs.

This doesn't automatically mean we're going into any special kind of technology that supports event sourcing (e.g. EventStore). We can implement event sourcing approach at specific points where it's actually necessary.

Detailed analysis

• Sensor Readings are received from an IoT cloud and stored under corresponding Sensors, with update rate of 15 or 30 minutes.
• A Sensor represents a physical device which measures electricity consumption in kWh. A Sensor can be associated with one paying consumer (a Customer), through a Contract.
  • The Contract defines a Pricing plan under which the Customer is charged for consumption measured by the Sensor.
  • A Pricing plan can be of one of these kinds:
    • Flat Price calculates charge amount by a user-defined flat rate per kWh.
    • Scaled Price is a scale of flat rates, according to consumption (example: $0.10 for 0-499 kWh, $0.15 for 500-749 kWh, $0.30 for 750+ kWh)
    • Rule-Based Price is an ordered list of rules. Each rule consists of a condition and a price, where the price is either flat or scaled as defined above.
      • Conditions are logical expressions, which may contain variables, constants, and logical operators. The variables can refer to customer details, timestamps of sensor readings, and current/past consumption aggregations. Exact list of variables can be defined separately.
      • The rules are evaluated in the list order. The price of the first rule whose condition evaluates to true is applied.
• An Invoice represents a monthly bill for a Customer to pay. An Invoice contains zero or more Invoice Rows.
  • An Invoice Row represents summary consumption and amount due for a specific Contract within the billing period. Therefore:
    • Customers with multiple Sensors will have separate Invoice Row at least per each Sensor.
    • Customers whose Pricing plan was changed (for example) mid-month, will have two separate Invoice Rows for the same Sensor: one for the previous Contract, and one for the new Contract.
• A Billing job will create/update Invoice Rows and Invoices. The job will take Sensor Readings as in input, pick associated Contracts and Pricing plans, and calculate amounts due. The job will run on schedule (e.g., once an hour).
  • Running the job continuously has the benefit of allowing the staff and the customers see ongoing consumption and charges through the current month. If it isn't necessary, the job can run once in a month, or be invoked manually.
• All currency values (prices, amounts due to pay, receipts, etc) are stored and presented in Operator currency, which is configured system-wide. When a Customer makes a payment using one of available payment processing services, the service would allow the Customer to pay in a different currency.
• A payment is processed through a Payment Method, which represents a payment processing service.
  • Since each payment service requires different set of identification details and associated logic, the Payment Method is an abstract entity. It is inherited and implemented by integration with every concrete payment processing service.
  • Important to emphasize: supported payment services aren't represented by the rows in the PaymentMethod table. A row in PaymentMethod table represents identification details filled by a customer for a concrete payment service. The type of the payment service is identified by the value of that row's discriminator column.
    • The Payment Method inheritors are pluggable. The set of supported inheritors is composed by registering the inheritors in a DI container. When a new payment service integration package is plugged in, it is seamlessly picked up by all layers, UI through DB.
• Any successfully processed payment from a Customer is represented by a Receipt. Though a payment is usually for a specific Invoice, there is no direct relation between the two.
  • What's important is the balance of a Customer, which equals total of all Invoices minus total of all Receipts belonging to the Customer.
  • With that, Receipt has a memo field which can indicate that a payment is for a specific Invoice, in free text. It can be filled automatically in "Pay This Invoice Now" use case, or typed manually by user.

Retroactive recalculations

It wouldn't be necessary in an ideal world. But in reality, some Invoices might be sometimes found incorrect. This can be caused (for example) by:

• Missing or incorrect Sensor Readings, probably due to misconfiguration of IoT cloud or sensor devices.
• A wrong Pricing plan that was by mistake associated with a Contract.
• A bug in the application

The Billing job will be responsible for retroactive recalculations.

• In order to fix an incorrect Invoice, once the raw data is fixed, the Invoice must be invalidated, and the Billing job should be run.
• The job will identify invalidated Invoices, and recalculate them (now based on the correct data).

One pitfall to avoid during retroactive recalculations, is accidentally rewriting the past. As a mitigation, these restrictions apply:

• A Contract can never be changed, except that it can be invalidated.
  • A Contract has a validity period. The validity period starts when the Contract is created, and ends when the Contract it's invalidated.
  • When invalidated, a Contract can be replaced by a new Contract
  • At any moment, there can be only one valid Contract that associates a specific Customer with a specific Sensor.
  • Thus a Customer with multiple Sensors, will have one valid Contract per Sensor.
  • There can be multiple invalidated Contracts. They are not deleted, in order to allow retroactive recalculations and aid bookkeeping.
  • When the Billing job performs retroactive recalculations, it picks the Contract that was valid at the date of Sensor Reading, and its associated Pricing plan.
• A Pricing plan can be edited as long as it isn't associated with any Contract.
  • Once a Pricing plan is assigned to at least one Contract, that Pricing plan becomes read-only forever (even after all related Contracts are invalidated).

[felix-b]

Data flow diagram

Entity relationship diagram

(work in progress -- suggestions are welcome)

[godrose]

Looking good. No need in supporting all kinds of price plans and currencies right from the start. Also i recommend replacing the word "tariff" with "price plan"

[godrose]

Why there's need in two different apps? One app might be enough for demo purposes. The user will be redirected according to their identity to the correspondent root view

[felix-b]

@godrose yes, I agree about not implementing variations of pricing strategies etc right from the start. Just wanted to illustrate how they are planned to be implemented.

"Pricing Plan" indeed sounds better. "Rate Plan" can also be good -- here is an indication of usage from Google Books

As for having 1 or 2 apps, I'd like to demonstrate a production-ready system, so I'd rather apply considerations about production. Since the apps serve two different kinds of users, I'm considering these points:

• The style/theme can differ, which affects the login page itself (ascetic vs attractive)
• The set of credentials can differ (AD/SSO and/or 2-factor vs email/password + captcha)
• Options like "forgot password" or "don't have an account? sign up" might not be relevant for both kinds of users.
• Last but not least, having 2 separate apps allows granular deployment and availability. The apps can be independently upgraded. Or if one app is taken down, the other one can still be operational.

One interesting alternative is display 2 different login forms on a common login page. But then we have 3 apps: login, back office, and dashboard.

[felix-b]

List of microservices (~ subdomains)

Service	Responsibilities	API Endpoints
Sensor service (red color, daemon)	Sensors subdomain; store sensor readings	(1) push sensor readings (2) TX = submit transaction requests (3) QX = run entity queries
Customer service (cyan color, daemon)	Customers subdomain; manage pricing plans and contracts	TX, QX
Billing service (purple color, daemon)	Billing subdomain; query and invalidate invoices	TX, QX
Billing job (purple color, batch job)	Generate invoices based on data from Sensors and Customers subdomains	N/A
Payment service (green color, daemon)	Payment subdomain + process payments through integration with online payment services	TX, QX + callback endpoints specific to payment services
Login service (yellow color, daemon)	User Accounts subdomain + authenticate users	TX, QX
Admin App service	Host back-office web app	Web
Dashboard App service	Host dashboard web app	Web

[felix-b]

The MVP application is a driver for design and implementation of programming models in use. I gather related issues in the list below:

• Design of DDD and DB programming models

[felix-b]

Progress update

What's ready for review by now:

• The sample application is in the PR branch pr-mvp
  • https://github.com/felix-b/NWheels/tree/pr-mvp/Samples/02-ElectricityBilling/ElectricityBilling
• SLN file:
  • https://github.com/felix-b/NWheels/blob/pr-mvp/Samples/02-ElectricityBilling/ElectricityBilling/ElectricityBilling.sln

The solution is structured as follows:

• ElectricityBilling.Domain - "shared kernel", all domain data and logic in one class library
• ElectricityBilling.XxxxxService - a microservice console app project; there is one per microservice

Note that the solution doesn't yet consume NWheels NuGet packages. Temporarily, a class library named NWheelsTempApiLib contains mocks of all NWheels APIs (https://github.com/felix-b/NWheels/tree/pr-mvp/Samples/02-ElectricityBilling/ElectricityBilling/NWheelsTempApiLib). The mocks are just for the application code to compile, they can't execute.

This is still mid-work. The most of the progress was with the Sensor Service (https://github.com/felix-b/NWheels/tree/pr-mvp/Samples/02-ElectricityBilling/ElectricityBilling/ElectricityBilling.SensorService)