All-Dings-HLD

I am a Design-Document.

About

• My Predecessor is All-Dings-Overview.

General

All Dings are defined with Markdown-Files in separate Git-Repositories.

The Top-Level-Repository collects the Dings-Files into Work-Dir, builds the current Json Representations and renders Html into Day.

Core Concepts

• Dings: Object, that is described by Dings-Files.
• Dings-Number: Stable Identifier of a Dings.
• Dings-Name: Human-readable Name of a Dings.
• Dings-Reference: Link from one Dings to another Dings.
• Repository: Git-Repository, that stores Dings-Files.
• Work-Dir: Collected Dings-Files from Repositories.
• Day: Rendered Html-Files for Presentation.

Representations

The Dings-System uses multiple Representations of Dings-Files:

• md: Document-Truth written by Humans.
• ir: Parsed Representation of md.
• sm1: Explicit semantic Document-Truth extracted from one md Document.
• sm2: Derived semantic View based on sm1 and cross-document Resolution.
• html: Human-readable Document-View rendered from ir or by the legacy Html Generator.

Build and Deployment Flow

Collect all Dings-Files into Work-Dir:

~/All-Dings/111 (Master)$ make workdir

The current Work-Dir step also keeps the semantic Json View current:

md -> ir -> sm1 -> sm2

Render the Ir Document-View into Html-Files under Day/:

~/All-Dings/111 (Master)$ make render

The current default Html Render-Path is:

md -> ir -> html

Sync with the Dings-Server:

~/All-Dings/111 (Master)$ make prod

The Dings-Server currently runs on AWS.

Docker

A Docker-Image is built with a configured Apache Web-Server:

~/All-Dings/111 (Master)$ make docker

Web-Serving

A Web-Server (currently Apache) is started with the Docker-Image and exports the Day Directory:

~/All-Dings/111 (Master)$ dings-host docker web start

This can be done locally for Testing or for Production on the Dings-Server (AWS).

Tools

• dings: Tool, that runs in the Dings-Container
• dings-host: Tool, that runs on Host
• dings-gpt: Tool, that runs on Host and supports GPT-related Workflows

dings-gpt show sm

dings-gpt show sm is the user-visible Command-Family for inspecting semantic Views of Dings as readable Text.

Purpose

The Purpose of show sm is to make semantic Information visible for Humans and useful for Development.

It helps to inspect:

• Dings-Objects
• Classes
• Relations
• Names
• Claims
• Derived Semantic-Views

Semantic Layers

From a User-Perspective, the important Layers are:

• sm1: Explicit semantic Document-Truth extracted from one Markdown Document.
• sm2: Derived semantic View across Documents.

sm1 answers the Question:

• What does this Document directly say?

sm2 answers Questions like:

• Which Classes does this Dings belong to?
• Which Relations point to or from this Dings?
• Which Names are known for this Dings?
• Which Claims originate from this Dings?

The show sm Command-Family mainly uses sm2, because sm2 contains the resolved cross-document View.

User-visible Views

The current user-visible Views are:

• dings TARGET: Show the semantic View of one Dings.
• list [TARGET] [where PREDICATE=OBJECT]: Show a Dings-Set.
• names-of TARGET [BASE]: Show observed Names and Reference-Labels for a Dings.
• claims-from CLAIMER [PREDICATE]: Show Claims that originate from a Dings.

Low-Level Details

Concrete Directories, Files, Configs, Logs and Runtime-Details are described in All-Dings-LLD.