Create high level architectural diagram

[Ainali]

The feature

Create a high level architectural diagram that explains how the different pages are generated and how the data is collected and from where.

Why?

This would help new users understand how the website is built and guide them on how to suggest, or work on, improvements.

The Standard for Public Code also says:

The documentation SHOULD describe the key components or modules of the codebase and their relationships, for example as a high level architectural diagram.

Examples and inspiration

No response

[Abbe98]

Note to self: It would be nice if one could generate this from any Snowman views.yaml file.

[Abbe98]

Maybe something like this?

Mermaid source

graph TD
    Root["/ 
    template: landing.html"] --> About["/about
    template: about.html"]
    Root --> Tools["/tools
    template: tools.html"]
    Root --> StandardPublic["/standard-for-public-code
    template: standard-for-public-code.html"]
    Root --> Statistics["/statistics
    query: countries.rq
    template: statistics.html"]
    Root --> Topics["/topics
    query: topics.rq
    template: topic-list.html"]
    Root --> Countries["/countries
    query: countries.rq
    template: country-list.html"]
    Root --> Error["/404
    template: 404.html"]
    Root --> Sitemap["/sitemap.xml
    query: countries.rq
    template: sitemap.xml"]
    Root --> MapData["/map.json
    query: countries.rq
    template: map-data.json"]
Statistics --> StatsSVG["/statistics/statistics.svg
query: countries.rq
template: statistics.svg"]

Countries --> CountryMap["/countries/map
template: countries-map.html"]

Countries --> CountryNodes{Country Pages}

CountryNodes --> greenland["/greenland/{{qid}}
query: generators/greenland.rq
template: org.html"]
CountryNodes --> sweden["/sweden/{{qid}}
query: generators/sweden.rq
template: org.html"]
CountryNodes --> denmark["/denmark/{{qid}}
query: generators/denmark.rq
template: org.html"]
CountryNodes --> norway["/norway/{{qid}}
query: generators/norway.rq
template: org.html"]
CountryNodes --> ghana["/ghana/{{qid}}
query: generators/ghana.rq
template: org.html"]
CountryNodes --> germany["/germany/{{qid}}
query: generators/germany.rq
template: org.html"]
CountryNodes --> southAfrica["/south-africa/{{qid}}
query: generators/south-africa.rq
template: org.html"]
CountryNodes --> netherlands["/netherlands/{{qid}}
query: generators/netherlands.rq
template: org.html"]
CountryNodes --> newZealand["/new-zealand/{{qid}}
query: generators/new-zealand.rq
template: org.html"]
CountryNodes --> finland["/finland/{{qid}}
query: generators/finland.rq
template: org.html"]
CountryNodes --> ukraine["/ukraine/{{qid}}
query: generators/ukraine.rq
template: org.html"]
CountryNodes --> russia["/russia/{{qid}}
query: generators/russia.rq
template: org.html"]
CountryNodes --> eastTimor["/east-timor/{{qid}}
query: generators/east-timor.rq
template: org.html"]
CountryNodes --> philippines["/philippines/{{qid}}
query: generators/philippines.rq
template: org.html"]
CountryNodes --> india["/india/{{qid}}
query: generators/india.rq
template: org.html"]
CountryNodes --> belgium["/belgium/{{qid}}
query: generators/belgium.rq
template: org.html"]
CountryNodes --> canada["/canada/{{qid}}
query: generators/canada.rq
template: org.html"]
CountryNodes --> indonesia["/indonesia/{{qid}}
query: generators/indonesia.rq
template: org.html"]
CountryNodes --> luxembourg["/luxembourg/{{qid}}
query: generators/luxembourg.rq
template: org.html"]
CountryNodes --> singapore["/singapore/{{qid}}
query: generators/singapore.rq
template: org.html"]
CountryNodes --> bermuda["/bermuda/{{qid}}
query: generators/bermuda.rq
template: org.html"]
CountryNodes --> malaysia["/malaysia/{{qid}}
query: generators/malaysia.rq
template: org.html"]
CountryNodes --> czechRepublic["/czech-republic/{{qid}}
query: generators/czech-republic.rq
template: org.html"]
CountryNodes --> nepal["/nepal/{{qid}}
query: generators/nepal.rq
template: org.html"]
CountryNodes --> peru["/peru/{{qid}}
query: generators/peru.rq
template: org.html"]
CountryNodes --> austria["/austria/{{qid}}
query: generators/austria.rq
template: org.html"]
CountryNodes --> iceland["/iceland/{{qid}}
query: generators/iceland.rq
template: org.html"]
CountryNodes --> malta["/malta/{{qid}}
query: generators/malta.rq
template: org.html"]
CountryNodes --> morocco["/morocco/{{qid}}
query: generators/morocco.rq
template: org.html"]
CountryNodes --> switzerland["/switzerland/{{qid}}
query: generators/switzerland.rq
template: org.html"]
CountryNodes --> cameroon["/cameroon/{{qid}}
query: generators/cameroon.rq
template: org.html"]
CountryNodes --> ireland["/ireland/{{qid}}
query: generators/ireland.rq
template: org.html"]
CountryNodes --> portugal["/portugal/{{qid}}
query: generators/portugal.rq
template: org.html"]
CountryNodes --> latvia["/latvia/{{qid}}
query: generators/latvia.rq
template: org.html"]
CountryNodes --> uk["/united-kingdom/{{qid}}
query: generators/united-kingdom.rq
template: org.html"]

uk --> scotland["/united-kingdom/scotland/{{qid}}
query: generators/united-kingdom/scotland.rq
template: org.html"]

classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px;</pre>

[Abbe98]

It's a visual view of views.yaml so it's more of a sitemap but it includes the query and template used as well. We only have a single page layout so I think it works.

[Ainali]

It's almost impossible to read due to the width. Instead of creating a box for each country, perhaps just have one box stack representing countries?

[Abbe98]

Updated diagram:

graph TD
    Root["/ 
    template: landing.html"] --> About["/about
    template: about.html"]
    Root --> Tools["/tools
    template: tools.html"]
    Root --> StandardPublic["/standard-for-public-code
    template: standard-for-public-code.html"]
    Root --> Statistics["/statistics
    query: countries.rq
    template: statistics.html"]
    Root --> Topics["/topics
    query: topics.rq
    template: topic-list.html"]
    Root --> Countries["/countries
    query: countries.rq
    template: country-list.html"]
    Root --> Error["/404
    template: 404.html"]
    Root --> Sitemap["/sitemap.xml
    query: countries.rq
    template: sitemap.xml"]
    Root --> MapData["/map.json
    query: countries.rq
    template: map-data.json"]

Statistics --> StatsSVG["/statistics/statistics.svg
query: countries.rq
template: statistics.svg"]

Countries --> CountryMap["/countries/map
template: countries-map.html"]

Countries --> CountryNodes{"Country Pages (examples)"}

CountryNodes --> greenland["/greenland/{{qid}}
query: generators/greenland.rq
template: org.html"]
CountryNodes --> uk["/united-kingdom/{{qid}}
query: generators/united-kingdom.rq
template: org.html"]

uk --> scotland["/united-kingdom/scotland/{{qid}}
query: generators/united-kingdom/scotland.rq
template: org.html"]

classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px;