Readme

The purpose of this project is to give to a potential customer the means to subscribe to a service provider (e.g. electricity, internet) without him/her accessing directly to the website.

For all intents and purposes this software is just a series of crawlers that will visit websites of every service provider (list at the end), fill the forms requested and make the purchase automatically. All of this wrapped up with a simple ui for the user to use or for a dev to integrate through API.

Going deeper

Let's start with some definitions.

A provider is a real entity (e.g. fastweb) that can offer multiple products (e.g. adsl, fiber, 4g, 5g, etc..).

The customer is the final real person which information will be used to make the purchase

The user is the entity that will either use the administration panel or integrate through the API

A driver is a class that will handle a specific provider (e.g. "fastweb.com") following a specific task.

One driver can have multiple actions, for now there are only 2:

Check coverage for the given address

Subscription of a product for the customer

The process of executing any action will be handled through a workflow in order to handle interruptions.

Many errors could occur during the execution of this process, such as:

Missing fields

Wrong value fields

Already registered in the service

Internal Error

Driver error

Besides errors, some interruptions may (most likely will) appear, such as:

OTP requested

Credit Card

Captcha

In order to handle interruptions, every action will be dispatched in a queue system and will use a workflow system

Each workflow can have multiple states, representing the flow of the workflow through time.

Cycle of actions

List of possible states of workflow:

pending: Has been requested and it's waiting to be executed

running: Has been executed and is currently running

interrupted: Cannot continue because an error has been found or new information must be provided. Intervention is required

canceled: Has been stopped and canceled

done: Has been concluded successfully

This is the flow of a typical workflow

As the diagram show, interrupted can go back to the state of running once the data required/problem has been solved.

Field validation is usually handled at the start of the workflow, but nonetheless some validation can only occur once the workflow starts. For example some providers offer products only in some geographical areas, (e.g. fiber only in big cities).

Use case

Coverage Area

Provide a list of all products available based on the address

Subscription

Subscribe the customer to a provider

Administration panel

An administration panel is provided to visualize all the data saved in the database, to check all the workflow executed and to manually call the actions for testing purposes.

The admin can be accessed by the endpoint /admin

Organizations and Permissions

In order to handle partnerships and permissions the concept of Organization has been introduced.

An organization is merely a group of people and/or entities under a certain name that will be able or not to perform certain activities inside the scope of the api and the administration panel.

Each organization can have only one parent but many sub organizations (or children).

As the visual graph suggests, the organizations are handled as a tree structure.

A more real scenario would be something like this

One important note is that each organization will be able to see only his own data and those of all organizations created under it (children, grand-children, etc ...), but never upwards.

So, for example Compare Tech will be able to see every customer, workflow, user and tokens of every organization in the database

Handling organizations

For each organization there are users and api_tokens.

This means that each organization can choose if they want to share the access of the admin panel, the api or avoid any of that.

An organization has 3 flags:

api_token: Give the access to create their own apiTokens

user: Give the access to manage their own users

organization: Give the access to create and manage their own sub organizations

An api_token is simply a token that can be used as authentication to call the api. You can choose to enable/disable it and provide a rate limit (expressed as every minute).

A user it has already been defined. It's up to you to decide how many users/people you want to give access to that organization. A user has to be both with the role admin and have the organization with flag user true to manage other users in the same organization. If no user has the role on admin, this means that every users will be handled from the parent organization.

With the flag organization comes 3 different types of sub-fields, that can have 2 types of integer values:

-1: to indicate infinity, no limit

0...N: to define the limit of the value (0 is disabled, 1 is max 1, 10 is maximum 10, etc...)

The fields are:

max_depth: Specify how deep this organization can become. So if the value is 0, this new organization you are creating will not be able to create any sub organization. If the value is 2, it means they can create sub organization and their subs can create other subs (basically grand children), but those at the 2nd level will not be able to create any more subs. -1 for infinite depth

max_degree: Specify how many organization this organization can create on his level. So for example if you put 10, this means they will be able to create maximum 10 sub organization.

max_total_nodes_degree: Specify how many organization can spread from this organization. This is introduced for e.g. if you want to give some unlimited criteria, but still want to keep a limit at for e.g. 500 nodes

Keep in mind that the "parent" or the "root", has always precedence over any sub. So if you put a finite number for any of those 3 fields, your subs will not be able to overwrite you, even if they put very high numbers, or -1, your priority will always take precedence.

Examples

These are some of the scenarios:

An organization (e.g. Compare Tech) decides to not allow their own partners to access the admin panel, and merely provide the apiKeys. This can be done by simply creating an organization based on the partner, not adding any users under that organization and just create some api_tokens

An organization decides to give more independence for some of their partner, but doesn't want to allow them to create their own suborganizations. In this case this can be done by creating a new user with the role admin under that organization and simply giving them access to it. Keep in mind that by giving access to it, they will be able to create as much as api_tokens they want.

List of drivers

Fastweb

Enel

Aruba

Continue with the API

Going deeper#

Cycle of actions#

Use case#

Coverage Area#

Subscription#

Administration panel#

Organizations and Permissions#

Handling organizations#

Examples#

List of drivers#