code structure

Here is a high-level description of how the code in the Conzept project is structured. You can also browse it online here.

.
├── app (all ~40 embedded apps, including the Conzept main app, see next section)
│  ├── ...
│  ├── ...
│  └── ...
│
├── assets (globally shared assets)
│  ├── icons
│  └── fonts
│
└── services (background services started upon system boot)
   ├── allorigins (general CORS proxy)
   └── json-proxy (JSON-only CORS proxy, which can also handle secret API-keys)

The Conzept-project root-directory also contains the following relevant files:

• authors, copyright and license file
• manifest.json (this enables Conzept to be installed as a desktop app)
• service-worker.js (required for making the Conzept app installable)
• opensearch.xml (used by search engines and web browsers to understand the URL search format of a website)

The Conzept main app - the UI wrapping all the other apps! - is located in the “<root_directory>/app/explore2” directory and has the following structure:

.
├── assets
│   ├── geojson (used only for the data-layers in the organism-occurrence web-component)
│   ├── i18n (localization files)
│   ├── images (some static images)
│   ├── json (mainly used for storing lists of Wikidata "topic theme" entity IDs)
│   ├── models (used to store Draco-optimized GLB 3D models)
│   └── svg (used for flags, former-flags)
│
├── css
│   ├── conzept (all the Conzept style files)
│   ├── openmoji (icon set style)
│   └── various (a few style files not yet installable with NPM)
│
├── dist (the build-output directory - never manually edit these files)
│
├── libs (a few JS libraries not yet installable with NPM)
│
├── notes (a collection of design notes)
│
├── php (PHP mobile-detect library)
│
├── src (Conzept source directory)
│   ├── core (core code parts)
│   ├── data (code which creates dynamic data structures)
│   ├── datasources (code which functions to handle various datasources, such as "wikipedia" and "wikidata")
│   ├── command ([[command API]] related code)
│   ├── fetch (code which fetches API data, each API has its own file - see the section "API code" below)
│   └── webcomponent (used for storing web-components)
│
└── tools (various tools used for: building, installing services, fetching monthly covers, etc.)

The Conzept app is started in “src/core/main.js” and will from there call various function located in the “src/core/lib.js|lib.js”.

From “main.js”:

• All the URL parameters are cleansed, parsed and stored.

• The global object “explore“ is created. The values in this JS-object can be accessed through: “explore.<property-name>” (see next section). Note: The explore-object is not accessible in the embedded apps, use URL-parameters to pass relevant data into the embedded app.

• The language and locale are setup (while checking for the language setting in the persistent browser storage).

• Dynamic UI-element are setup and activated (autocompletion, user settings UI, etc.).

• Keyboard event-handlers setup.

This is the global data-structure which Conzept uses for the main app. All its values can also be accessed from field definitions.

Here are some of the important properties on this object:

All the (non-essential) API data-fetching code is hosted in “app/explore2/src/fetch”. There are currently over 40 different API integrations in use for Conzept.

Each API has its own file, but shares a common structure. This makes adding new API's relatively easy, though it still requires some coding and looking at the data structures of the API returned results.

That common code structure is used to handle:

• The input arguments (title string, current paging status and sometimes custom data)
• Result paging (page size, current page, total results)
• Sorting options (optional)
• Rendering the returned results into Conzept

To add a new API, see integrating an API.