Skip to content

Latest commit

 

History

History
291 lines (229 loc) · 12.2 KB

Design.md

File metadata and controls

291 lines (229 loc) · 12.2 KB
Raw

Tranzakt intentionally tries to use as many mature open source packages as possible in order to massively reduce the amount of bespoke code required.

However, whilst using open source in this way has huge benefits such as:

  • Reuse of existing technology which already has other users and therefore fewer bugs
  • Shared maintenance workload

it also has some downsides:

  • Lack of control over changes to these open source packages
  • Packages which lose support and fail to keep pace with other packages that they rely upon (like Laravel)
  • Conflicts between two different versions of a package required by 2 or more other packages
  • Security - esp. supply chain attacks where malicious security breaches get included in updates to packages

So packages need to be chosen wisely. I hope that I (Sophist) have chosen wisely...

Tranzakt Packages

It is intended that Tranzakt will be split into several packages that users will install one or more of.

Tranzakt Runtime

A runtime-only environment that can execute pre-developed Tranzakt user applications. The Runtime will provide all the supporting functionality to execute PHP code automatically generated by Tranzakt Developer (TBD).

This will include:

  • A generic authentication interface that can be interfaced to a variety of authentication packages.

  • A generic API interface which can be used to interface with other environments (such as Joomla or Wordpress) as a remote server rather than a stand-alone web server.

  • Support for a variety of different front-end technologies to match whatever front-end technology is used by the rest of the front-end environment.

    • Blade + jQuery
    • Livewire + Tailwind
    • Vue.js

    Blade (which is Laravel templating of HTML) + Livewire should be the first technology supported (because it is the simplest), with Vue.js as a second technology supported.

    Within these, Tranzakt must support easy visual tailoring using CSS classes etc.

Tranzakt Runtime Admin

A runtime environment (or possibly multiple alternative environments for different security packages and / or UI packages) which will deliver an administrative interface for defining run-time users when Tranzakt is used in stand-alone or remote server mode.

Tranzakt Runtime Joomla / Wordpress etc.

Packages which will provide an API interface with a front end-web server to provide Tranzakt user application HTML via RPC. Ideally these would be enabled (via an async first call and a sync second call - the second possibly being triggered by Ajax) to gather the necessary data and create the necessary HTML in parallel with the calling server. The Tranzakt Runtime interface would be accompanied by a matching Joomla / Wordpress etc. extension that would handle the remote interface.

Tranzakt Developer

The web-based development environment enabling Tranzakt user applications to be developed in the browser i.e. defining tables, forms etc.

This would support a minimal core set of data types and visualizers that covering basic displays (lists and forms) and basic fields (text/numeric input, dropdown).

Trazakt Developer is effectively a stand-alone Laravel environment with it's own Admin / Security based on Vue.js and Laravel Jetstream. Hopefully this will not create any incompatibilities with any other packages that may have been installed by the user in the Laravel instance.

Tranzakt visualisation and field (etc.) packages

Additional functionality over and above that provided in the above packages will be delivered by plugin packages.

Note: Ideally these would consist only of run-time functionality (web components, Laravel code) together with JSON definitions and online help that could be read by Tranzakt Developer and used to create any development UI that is needed without modifying or adding code to Tranzakt Developer. This would avoid delivering a combined package containing both runtime & developer code, however it remains to be seen if this is actually possible.

Tranzakt Standalone Runtime

A complete standalone webserver integrating:

  • Laravel itself
  • Same/similar user admin as Tranzakt Developer
  • Tranzakt Runtime
  • Tranzakt Runtime Admin
  • Laravel based CMS functionality (best of class)
  • Laravel based BB / Forum functionality (best of class)
  • Laravel based Wiki functionality (best of class)

designed to provide a fully featured fully functional web platform that can also run transactional SQL applications and which (with the addition of Tranzakt Developer) can also develop such SQL applications.

Tranzakt Standalone Runtime should be used to deliver the Trazakt web site.

Tranzakt Standalone Developer

Tranzakt Standalone Runtime with Trabnzakt Developer integrated in.

Each of the above packages would be Laravel packages (i.e. with their own independent dependencies) that can be independently installed, enabling infinite set of possibilities.

Tranzakt Master

An integrated environment for contributors that installs all of the above in a single go.

Note: This is the intended end-result. The PoC may be structured differently (though ideally it would be structured in a way that is broadly compatible with this and which would not require wholesale code changes to

Dependencies

Server Dependencies

Wherever possible packages should come from one of a few major Laravel infrastructure contributors like e.g. Spatie.

Packages should have been updated for Laravel v9 and had recent updates (i.e. within the last 6 months) to demonstrate that the package is currently supported.

Ideally the package should have been downloaded at least 100k times as an indication of functionality, maturity and popularity which is a good indicator that the package will continue to be maintained.

Browser Dependencies

Similar to the above but relating to Vue.js rather than Laravel.

Obsolescent bullet list

  • Laravel UI 3.4.6
  • Laravel Sanctum 2.15.1 (for checking session cookies etc.)
  • Mews Purifier 3.3.7
  • Mateus Junges' Laravel-ACL 4.1.1 (for roles security)
  • Spatie Laravel-Permission 5.5.4 (for roles security)
  • LaraCache 2.1.0 (cache ORM models)
  • Jess Archer's Laravel-castable-data-transfer-object 2.2.0 (Make columns holding JSON work like normal columns)
  • Laravel Jetstream (to provide user registration and authentication functionality) plus Inertia for Vue integration
  • bennett-treptow/laravel-migration-generator - create migrate table definitions from database tables
  • kirschbaum-development/eloquent-power-joins - do joins with this using proper relationships rather than the join method
  • archtechx/enums 0.3.0 - enums helpers
  • Spacie Laravel Data objects 1.5.0 - simply conversions between object types
  • Sqits Userstamps v* (from master because packagist version doesn't support v9) to record creation / update user names in Tranzakt tables.

General Dependencies

PHP

PHP has been chosen as the server-side script language because it is the most prevalent, and because it is more available as a cheap hosting solution than python or node.js, and because there is a suitable mature, open-source framework (Laravel) which will provide the fundamental foundation for Tranzakt and avoid bespoke coding.

In addition PHP now has a governance model, coding standards, and a package manager (Composer) and package repository (Packagist) which support complex open-source dependency trees.

PHP v8.1 is now the current PHP release and this should already be supported by most major hosting companies (and even more so by the time Tranzakt is ready for formal release), and it has a range of capabilities (most notably namespaces) which are extremely useful when creating a product like Tranzakt.

Tranzakt Runtime - Server Dependencies

Laravel

Laravel has been chosen as the foundation framework on which Tranzakt will be built because it provides:

  • A mature Object Relational Model (ORM) to manage SQL access
  • A mass of other useful supporting functionality
  • A raft of 3rd party enhancements

Nicolas Widart's Laravel Modules

Provides support for Modules - creation of separate instances of the standard Laravel directories in order to separate out logically independent sections of code (like packages).

Alternatives rejected: https://github.com/caffeinated/modules, https://github.com/Flutterando/modular, https://github.com/InterNACHI/modular, https://github.com/keljtanoski/modular-laravel

Note: This might not be a Runtime package, but rather a support tool used when creating Tranzakt i.e. this block might be in the wrong section of this document.

Sqits Laravel Userstamps

Provides created_by, updated_by and (for softDelete tables) deleted_by fields akin to the created_at, updated_at and (for softDelete tables) deleted_at fields.

Laravel Localization

A basic foundation for delivering i18n for all Tranzakt packages.

  • Detect language from browser
  • Smart redirects (Save locale in session/cookie)
  • Smart routing (Define your routes only once, no matter how many languages you use)
  • Translatable Routes
  • Supports caching & testing
  • Option to hide default locale in url
  • Many snippets and helpers (like language selector)

Tranzakt Runtime - Browser Dependencies

Tranzakt Developer - Server Dependencies

Tranzakt Runtime

Obviously!

Laravel Debugbar

Comprehensive debug bar shown at the bottom of a page during development which lists SQL calls, log messages etc.

Laravel Menu

Tranzakt Developer needs menus.

The same package should be used by Tranzakt Standalone.

Laravel JetStream

Laravel Developer - Browser Dependencies

Tranzakt contributors

The above packages are those required for the various Tranzakt packages to run. In addition the following packages are included to assist with development of Tranzakt itself:

Server Dependencies

Orchestral Testbench

Documentation: https://packages.tools/testbench Github: https://github.com/orchestral/testbench Currently used version: 7.6.0

Unit test support for packages

Browser Dependencies

Directory Structure

All Tranzakt files will be stored in a /Tranzakt directory in the Laravel root directory.

In order to keep the files for each of the above packages grouped together (and separate from other user Laravel app files) the various packages will be created as "modules" (and may if appropriate have sub-modules), with each module occupying a subdirectory of /Tranzakt/. This will also enable these to be converted easily to packages for publishing.

Routing

Routing is the mechanism by which a particular URL call is used to decide what (Laravel) code to run.

Tranzakt Admin & Tranzakt Developer will have their own standardised routing, as will the API to be used by e.g. Joomla or Wordpress - and these will be (by default) /Tranzact/Admin/... or /Tranzakt/Dev/... or /Tranzakt/API/... (though these will need to be easily changeable if they conflict with other Routes). Standalone runtime URLs will need to be able to be aliased in order for developers to do SEO.

Coding Standards

Tranzakt follows PSR-1 and PSR-2.

You can use PHP-CS-Fixer to make sure everything is following the correct coding style. This tool can be integrated with your IDE to ensure that all code conforms when it is saved. It is intended to integrate this into Github workflow.

Unit tests & coverage

It is intended to integrate code coverage analysis and unit testing into Github workflow.