Architecture of GobstonesWeb2

The architecture of GobstonesWeb2 combines several modules providing different functionalities. They all interrelate to conform what is known as the GobstonesWeb2, and together with the contents, pedagogic proposals and others conform the Gobstones Platform. This section lists all the different modules that compose the architecture, their current status, and how they interrelate.

Basic overview of the architecture

For each module, there will be a repository in the organization, that is to say, a GitHub project will be present for the module.

Some modules depend on another, generating a dependency tree. Modules at the bottom of the tree are usually projects that provide utilities and general behavior, while the full application will be at the top of the tree.

You may be wondering why we chose a polyrepo approach instead of a monorepo one. You may read A Monorepo vs. polyrepo Summary if you don't know what we are talking about.

In summary, we believe that polyrepo requires simpler tooling, less mental effort, and allows for new developers to jump in to a project easily. Additionally, not all project of GobstonesWeb2 are released as the same single package. With that in mind, we reached for a polyrepo approach, and wrote specialized tooling when needed.

Som of the modules are currently available or under development, while others are just stubs because they are planned, but no particular release date is yet defined.

The following is an overview of the projects and their dependencies.

GobstonesWeb2 Architecture Diagram

We are currently working in redesigning some of the modules into new grouping. Expect changes on this graphic in the future.

Most of the modules share a common structure, regarding files present at the root, the tooling used, how you can work with them, etc. Some files such as the "LICENSE" file, or the ".vscode" folder with recommended add-ons for the Visual Studio Code editor are required to live at the root of every project, but they are actually shared across all the modules. To ensure easy management of this, the gobstones-scripts module was created. Most modules in GobstonesWeb2 depend on the gobstones-scripts module.

List of Active Projects

This is the list of projects of GobstonesWeb2 that are either published under a stable release, or are under active development.

⦿ Gobstones-board

A representation for Gobstones boards.

⦿ Gobstones-board-React

The React layer over the Gobstones-board.

⦿ Gobstones-code-editor

A code editor to use with Gobstones.

⦿ Gobstones-core

A set of utility tools used through all GobstonesWeb2 repositories.

⦿ Gobstones-ide

The IDE component, with the actual environment.

⦿ Gobstones-gbb-parser

A parser/printer for GBB (Gobstones Board) file format.

⦿ Gobstones-guidelines

Fundamental documentation to contribute to GobstonesWeb2.

⦿ Gobstones-lang

A compiler for Gobstones language.

⦿ Gobstones-lang-def

A new module that will replace gobstones-lang-intl and gobstones-parser (currently not in the diagram).

⦿ Gobstones-lang-intl

Translation for Gobstones language built-ins and keywords.

⦿ Gobstones-markdown-view

A markdown viewer for Gobstones.

⦿ Gobstones-parser

A parser for Gobstones language v3.12.

⦿ Gobstones-scripts

Common configuration for all GobstonesWeb2 repositories.

List of Planned Projects

This is the list of projects of GobstonesWeb2 that are planned or on the roadmap, but that do not yet have a particular release date, nor anyone is currently working on them.

⦿ Gobstones-admin-dashboard

A dashboard for the Gobstones server.

⦿ Gobstones-assertions

A static and semantic code analyzer for Gobstones language.

⦿ Gobstones-blocks

A framework agnostic Gobstones Blockly component.

⦿ Gobstones-blocks-React

The React layer over Gobstones-blocks.

⦿ Gobstones-lint

A linter for Gobstones language.

⦿ Gobstones-refactors

A refactoring tool for Gobstones language.

⦿ Gobstones-server

The Gobstones server.

⦿ Gobstones-test

A unit testing framework for Gobstones language.

⦿ Gobstones-typechecker

A typechecker for Gobstones language.

Repositories configuration

The gobstones-scripts module is used to create other modules for the GobstonesWeb2 platform, to abstract away configuration details in all the projects and to maintain a common structure of files in all repositories, thus, partially aiding the polyrepo approach and helping in the scaffolding process.

The module can be used as a command line program that allows to create new modules, through the subcommands create or init. It provides several templates for different types of projects, such as creating simple libraries, command line applications that can be also used as libraries, React components, simple web components, and others.

Most of the project's created require tools such as typescript, rollup, nps, jest, typedoc and others. In that sense, the modules created do not have direct dependencies for all those tools in their declaration file (package.json``), instead having a dev-dependency only onGobstones-scripts`, which in itself have the dependencies on the tools. This allows for a centralized version management of all the tooling, that can be easily overwritten if needed by any project by just adding a different version of the tool into their own declarations.

Some configuration files needed by the tooling, such as tsconfig.js or rollup.config.js, are abstracted away by the gobstones-scripts module, which holds the configuration files. This allows for a less cluttered root for the projects, and also to centralize the process of building, style of the documentation, etc. In case some project requires a particular configuration, these configuration files can be overwritten in the projects, by the subcommand eject, which will copy the abstracted files to the project root.

Other configuration files for some tooling, such as .prettierc used by prettier, or .eslintrc used by ESLint, are required unfortunately to be in the project root, as editors such as Visual Studio Code or others expect to find the declaration file in order to provide meaningful hints, code completion and refactoring. This files are usually all the same for every project, and it's cumbersome to create and maintain them all. The gobstones-scripts package generate those files when creating new project and can help maintain the same version through the different project through the update command, that updates those files if needed. Changes to the files can be made tgo provide customization if any project requires it.

Finally, mot projects will require to execute scripts as to automate processes that help in the development, such as starting up a development server, build the project, generate the documentation webpage, run the tests and so on. We make use of nps, a task runner that is elegant in it's simplicity. This tool provides just one step over the simple scripts section of a package.json file, but allowing to declare the scripts into a separate file, usually called package-scripts.js. The tool also provides things such as listing the commands, print help, etc. When executing scripts from nps, many tools will expect to find the configuration files in the root of the project, instead of the abstracted configuration files provided by gobstones-scripts. To make it easy to run and execute the tooling, gobstones-scripts provides the run subcommand, that executes nps commands, but loading the configuration for each tool from the appropriate location (considering also that it may be abstracted, overwritten by the user, etc.).

Alongside the run command, the gobstones-scripts module may be used as a library, from which you may obtain the tasks object. This object is useful if you so decide to eject the configuration file for nps, as it provides a simpler way to execute the most common tools, such as rollup or typescript, and even other nps commands, running tasks in parallel or serially, etc.

You can read more about the gobstones-scripts project in the gobstones-scripts' repository. If you want to know more about the different configuration files and tooling we use, you can read about it in the Technologies Section.

Basic functionalities

Another useful project is gobstones-core, that provides some basic utilities used through different projects.

The project includes things such as the idea for Event's that have typechecking, for throwing events that objects can subscribe to, and some particular data structures or types, such as BiMap or Subset.

Another utility provided is the Expectations module, that allows for setting up expectations to validate user inputs and data.

The SourceReader module provides a class that allows to read code agnostic source files and process them as a stream, reading one or more character at a time. This is useful for tokenizing inputs.

This module is required by default in projects created by gobstones-scripts, and is required by most projects in used in GobstonesWeb2, although it's usage is not mandatory at all.

You can read more about the things the module exports in the gobstones-core's repository.

On this page: