architecture

The main architectural choices made in the Conzept application are:

  • Keep things simple, web native and fun to code and maintain. Performance is secondary.
app composability (image modified from here).

Conzept app state + links → URLs with parameters → embedded app views

See also: narrow-waist, Perlis-Thompson principle
  • Use embedded iframes (and self-hosted app URLs) as a form of simple, well-isolated, micro-services. To the user it should feel as one application.
  • Use declarative data definitions where needed (examples: sections, fields, topic tags and indicators). Avoid code duplication where possible, instead use use expressive data structures parsed by minimal code.
  • The communication between Conzept and embedded apps is done using URL-parameters (title string, ISO-2 language code, Qid, etc.) and postMessage() function calls.
    • Note: Some styling of embedded apps is also applied by directly setting common CSS classes on the body-element of the iframe (such as the “dark” class for dark-mode styles, or the “rtl” class for right-to-left language-scripts).
  • Use vanilla JS (avoid complex frameworks inverting control), with jQuery for managing the DOM.
    • jQuery - and the jQuery-dependent plugins - may be removed or replaced in the future, if possible and beneficial.
    • When needed: use WebAssembly for performance-demanding, compute parts in the code. (eg. for OCR).
  • Main types of data-types to use: plain strings, URLs, Wikidata Qid's, JSON and JS object lists.
  • Allow the safe use of eval() needed for flexible field definitions. This is safe, as only the admins/devs can update the field definitions. Conzept is also a mainly client-side application, with no user-data being stored on the server.

URL structure

Conzept is mainly based around URLs and iframes.

Let's first look at some example URLs and then look at all the available parameters.

example URLs

  • conze.pt/explore/Semantic_Web (Minimal URL with a query-string. The user-language will be based on: the stored language setting, the browser language or simply fallback to English.)

URL parameters

There are various parameters available to structure URLs.

parameter description default value
l language “en”
t action-type “wikipedia”
i Wikidata Q-identifier (qid)
u URL-string
c custom data
s sidebar visibility true
v view-mode requested, can be “desktop” or “mobile” (determined by the device type, but can be overruled)
c custom data field (its format is not specified)

URL action types

The types parameter (“t”) in Conzept URLs indicated what type of content should be loaded.

The following action-types are available:

type argument data-type description
wikipedia string request the Wikipedia page
wikipedia-qid Wikidata qid request the Wikipedia or the Wikidata page (in that order)
link-split url load two content panes and load the URL into the first content pane, in the second-content pane load the Wikipedia page for the search-string
articles string (only used internally) to update the sidebar with a new string-search (and not update the content area)
random string (only used internally) to load a random Wikipedia topic
wander string loads the Wander-app to show a series of YouTube videos (note: this type may be removed in the future)