[ENHANCEMENT] Documenting how a lookup is executed

[roald-teunissen]

Is your feature request related to a problem? Please describe. Having no clear overview in the documentation of how a lookup is being executed in the backend. From looking up a IP or url to actually verifying it.

Describe the solution you'd like It would be nice to have a flowchart, showing how this evaluation is done.

[roald-teunissen]

I'm thinking of a flowchart or sequence diagram. The goal is to depict the flow of evaluating a URL for using a green infrastructure.

@mrchrisadams can you point me to the files that handle a lookup? And I've made a very simple sequence diagram to depict the flow. I don't think we need a lot of info depicted in these graphs (such as function names), but simple a process that is taking place such as "retrieving ip range".

[roald-teunissen]

I wanted to add Mermaid JS to be able to use it in my markdown files. What is the preferred way to add this? If it simply is adding the min.js file to the project: where do you want me to place it and where do I link it (as we have multiple applications in this project)

[mrchrisadams]

thanks for this @roald-teunissen - I had in mind a flow chart to show the branching logic, more than the sequence of events, largely because while it can be useful to understand that the API talks to, I was hoping we could use it as a graphical accompanyment to the branching logic cases described below in the new docs site:

If we don’t have a matching range for an IP address, we can perform a lookup to see which AS Network the IP address belongs to - if an entire AS network belongs to one organisation, and we have supporting evidence for the organisation using enough green energy, this saves duplicating the records that the AS network is managing themselves.

As before, we support two cases - an organisation providing a digital service themselves, or an organistion using a green provider to provide a service.

Linking directly to a provider by ASN

In this case, a domain might be provider-b.com, resolving to the IP address 231.231.231.231. From there we perform a lookup to find Autonomous Network 12345 (AS 12345), which is owned exclusively by Provider B, the organisation, and has been registered with us.

By following the link to supporting evidence shared by Provider B, we can establish the link to green energy.

Linking a site to a provider in the site’s supply chain

Similarly, a domain my-green-site.com, which resolves to the IP address 213.213.212.213. From there, we perform a lookup to the same Autonomous Network 12345 (AS 12345). We folow the link from `AS 12345 to link to Provider B, and refer to their evidence to establish the link to green energy.

Source: Understanding checks for green sites - Green Web Foundation Platform documentation

I've had a quick go below:

graph TD
    A[Checking a site is hosted green] -->|Submit domain over API| B(resolve domain to IP address)
    B --> C{Exists in Green IP ranges?}
    C -->|Yes| D[Show as Green]
    C -->|No| E[Carry out look up for Green ASN]
    E -->F{Exists in Green ASN list?}
    F -->|Yes| G[Mark as Green] 
    F -->|No| H[Mark as Grey]

We'd need diagrams for :

• doing a look up using entirely IP ranges
• doing a look up using references to ASNs that have been registered with us

Once we have this, we can look at the carbon.txt based approach. This is where it might be useful to have a sequence diagram.

Where to put mermaid js

To be honest, I'm not totally sure yet. Our docs site relies on sphinx, and I think sphinx has some specific places to put it.

There may be mermaidjs plugins for sphinx though that takes care of this for us, as it's quite a common tool now.

[mrchrisadams]

Oh yeah, there is.

We could add this to our config, and Sphinx, our documentation tool would natively understand mermaid documents.

https://pypi.org/project/sphinxcontrib-mermaid/

[roald-teunissen]

Flowchart of the technical aspects of executing a lookup