From b42128014e4f4beec9711e1f3b184cc6867abce7 Mon Sep 17 00:00:00 2001 From: Diogo Peralta Cordeiro Date: Mon, 19 Jul 2021 17:33:30 +0100 Subject: [PATCH] [DOCS] Elaborate initial architecture page --- docs/developer/src/SUMMARY.md | 21 +++-- docs/developer/src/architecture.md | 83 +++++++++++++++++++ docs/developer/src/{plugins => }/events.md | 0 .../src/{plugins/database.md => files.md} | 0 .../src/{plugins/docker_web.md => http.md} | 0 ...ocker_shell.md => internationalization.md} | 0 .../routes_and_controllers.md => log.md} | 0 docs/developer/src/paradigms.md | 0 docs/developer/src/plugins.md | 1 + docs/developer/src/routes_and_controllers.md | 0 docs/developer/src/security.md | 0 docs/developer/src/templates.md | 0 12 files changed, 98 insertions(+), 7 deletions(-) rename docs/developer/src/{plugins => }/events.md (100%) rename docs/developer/src/{plugins/database.md => files.md} (100%) rename docs/developer/src/{plugins/docker_web.md => http.md} (100%) rename docs/developer/src/{plugins/no_docker_shell.md => internationalization.md} (100%) rename docs/developer/src/{plugins/routes_and_controllers.md => log.md} (100%) create mode 100644 docs/developer/src/paradigms.md create mode 100644 docs/developer/src/routes_and_controllers.md create mode 100644 docs/developer/src/security.md create mode 100644 docs/developer/src/templates.md diff --git a/docs/developer/src/SUMMARY.md b/docs/developer/src/SUMMARY.md index c3145bb6c0..f077540b3a 100644 --- a/docs/developer/src/SUMMARY.md +++ b/docs/developer/src/SUMMARY.md @@ -1,16 +1,23 @@ # Summary - [High level view](./high_level.md) -- [Architecture and Paradigms](./architecture.md) -- [Database](./database.md) +- [Architecture: Modules](./architecture.md) + - [Programming Style](./paradigms.md) + - [Events](./events.md) + - [Database](./database.md) + - [Cache](./cache.md) + - [Routes and Controllers](./routes_and_controllers.md) + - [Templates](./templates.md) + - [Internationalization](./internationalization.md) + - [Log](./log.md) + - [Queues](./queues.md) + - [Files](./files.md) + - [Security](./security.md) + - [HTTP](./http.md) - [Plugins](./plugins.md) - - [Event Handlers](./plugins/no_docker_shell.md) - - [Installation](./plugins/docker_web.md) - [Configuration](./plugins/configuration.md) - [Initialization and Clean Up](./plugins/lifetime.md) - - [Database](./plugins/database.md) - - [Routes and Controllers](./plugins/routes_and_controllers.md) - - [Events](./plugins/events.md) - [Sample Plugins](./sample_plugins.md) - [Injecting Javascript](plugins/sample_plugins/Awesomeness.md) - [Creating a block on the sidebar](plugins/sample_plugins/Sample.md) +- [Components](./components.md) diff --git a/docs/developer/src/architecture.md b/docs/developer/src/architecture.md index e69de29bb2..44f660dcd0 100644 --- a/docs/developer/src/architecture.md +++ b/docs/developer/src/architecture.md @@ -0,0 +1,83 @@ +# Architecture: Modules + +## Core + +The `core` tries to be minimal. The essence of it being various wrappers around Symfony. It provides: + +- the Module system described in this chapter; +- [Events](./events.md); +- data representation via an [Object-relational database](https://en.wikipedia.org/wiki/Object%E2%80%93relational_database), +which is elaborated in [Database](./database.md); +- [Cache](./cache.md); +- [Routes and Controllers](./routes_and_controllers.md); +- [Templates](./templates.md); +- [Internationalization (i18n)](https://en.wikipedia.org/wiki/Internationalization_and_localization), elaborated in [Internationalization](internationalization.md); +- [Log](./log.md); +- [Queues](./queues.md); +- [Files](./files.md); +- [Security](./security.md); +- [HTTP Client](./http.md). + +Everything else uses most of this. + +## Modules +The GNU social [Component-based architecture](https://en.wikipedia.org/wiki/Component-based_software_engineering) +provides a clear distinction between what can not be changed (**[core](http://foldoc.org/core)**), what is replaceable +but must be always present (**[component](http://foldoc.org/component)**), and what can be removed or +added (**[plugin](http://foldoc.org/plugin)**). + +This architecture has terminology differences when compared to the one that was [introduced in v2](https://agile.gnusocial.rocks/doku.php?id=v2modules). +In fact, back in v2 - as the term `modules` is not necessarily non-essential - we would keep a "modules" directory near +"plugins", to make the intended difference between both self-evident. + +Now in v3, **[Module](http://foldoc.org/module)** is the name we give to the core system managing all the `modules` (as +it is broad enough to include both components and plugins). N.B.: there are not `modules` in the same sense as +there are `components` and `plugins`, the latter descend from the former. + +### Components + +The most fundamental modules are the components. These are non-core functionality expected to be always available. +Unlike the core, it can be exchanged with equivalent components. + +We have components for two key reasons: +- to make available internal higher level APIs, i.e. more abstract ways of interacting with the Core; +- to implement all the basic/essential GNU social functionality in the very same way we would implement plugins. + +Currently, GNU social has the following components: + +- Avatar +- Posting + +### Plugins (Unix Tools Design Philosophy) + +GNU social is true to the Unix-philosophy of small programs to do a small job. + +> * Compact and concise input syntax, making full use of ASCII repertoire to minimise keystrokes; +> * Output format should be simple and easily usable as input for other programs; +> * Programs can be joined together in “pipes” and “scripts” to solve more complex problems; +> * Each tool originally performed a simple single function; +> * Prefer reusing existing tools with minor extension to rewriting a new tool from scratch; +> * The main user-interface software (“shell”) is a normal replaceable program without special privileges; +> * Support for automating routine tasks. +> +> Brian W. Kernighan, Rob Pike: The Unix Programming Environment. Prentice-Hall, 1984. + +For instructions on how to implement a plugin and use the core functionality check the [Plugins chapter](./plugins.md). + +## Dependencies + +* The Core only depends on Symfony. We wrote wrappers for all the Symfony functionality we use, making it possible to + replace Symfony in the future if needed and to make it usable under our + [programming paradigms, philosophies and conventions](./paradigms.md). V2 tried to do this with PEAR. +* Components only depend on the Core. The Core never depends on Components. +* Components never have inter-dependencies. +* Plugins can depend both on the Core and on Components. +* A plugin may recognize other plugin existence and provide extra functionality via events. + +N.B.: "depend on" and "allowing to" have different implications. A plugin can throw an event and other plugins may +handle such event. On the other hand, it's **wrong** if: +* two plugins are inter-dependent in order to provide all of their useful functionality - consider adding [configuration to your plugin](./plugins/configuration.md); +* a component depends on or handles events from plugins - consider throwing an event from your component replacement and + then handling it from a plugin. + +This "hierarchy" makes the flow of things perceivable and predictable, that helps to maintain sanity. \ No newline at end of file diff --git a/docs/developer/src/plugins/events.md b/docs/developer/src/events.md similarity index 100% rename from docs/developer/src/plugins/events.md rename to docs/developer/src/events.md diff --git a/docs/developer/src/plugins/database.md b/docs/developer/src/files.md similarity index 100% rename from docs/developer/src/plugins/database.md rename to docs/developer/src/files.md diff --git a/docs/developer/src/plugins/docker_web.md b/docs/developer/src/http.md similarity index 100% rename from docs/developer/src/plugins/docker_web.md rename to docs/developer/src/http.md diff --git a/docs/developer/src/plugins/no_docker_shell.md b/docs/developer/src/internationalization.md similarity index 100% rename from docs/developer/src/plugins/no_docker_shell.md rename to docs/developer/src/internationalization.md diff --git a/docs/developer/src/plugins/routes_and_controllers.md b/docs/developer/src/log.md similarity index 100% rename from docs/developer/src/plugins/routes_and_controllers.md rename to docs/developer/src/log.md diff --git a/docs/developer/src/paradigms.md b/docs/developer/src/paradigms.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/plugins.md b/docs/developer/src/plugins.md index e69de29bb2..72a0ac75bf 100644 --- a/docs/developer/src/plugins.md +++ b/docs/developer/src/plugins.md @@ -0,0 +1 @@ +# Developing Plugins diff --git a/docs/developer/src/routes_and_controllers.md b/docs/developer/src/routes_and_controllers.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/security.md b/docs/developer/src/security.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/developer/src/templates.md b/docs/developer/src/templates.md new file mode 100644 index 0000000000..e69de29bb2