Optimized documentation

DOCUMENTATION_CONVENTION.md

@@ -1,7 +1,9 @@
-# Documentation
-## convention
+# Documentation Convention
+
+## Key Words
 The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
 “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the README.md files and in the comments of the code are to be
 interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
+
 ## README.md
 Each folder SHOULD contain a README.md file, which describes the domain of the folder.

README.md

@@ -35,7 +35,7 @@ To contributions of this project the "Contributor Covenant Code of Conduct" appl
 Further information you will find in the [administration README.md](./administration/README.md).
 
 ## Application
-Further information you will find in the [application README.md](./application/README.md).
+Further information about the application and the architecture you will find in the [application README.md](./application/README.md).
 
 ## Documentation Convention
 Further information you will find in the [DOCUMENTATION.md](./DOCUMENTATION_CONVENTION.md).

administration/README.md

@@ -42,7 +42,7 @@ This script copies the ***.env.dist*** files to the right locations.
 This script formats the PHP code with [PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer).
 
 ###  [generate-coverage-report.sh](./generate-coverage-report.sh.sh)
-This script generates a coverage report with PHPUnit [PHPUnit](https://phpunit.de/).
+This script generates a coverage report with  [PHPUnit](https://phpunit.de/).
 
 ### [init.sh](./init.sh)
 

application/README.md

@@ -0,0 +1,75 @@
+## Application
+## Architecture
+
+### Design Principles
+The software MUST follow this design principles:
+
+#### [Domain Driven Design](https://de.wikipedia.org/wiki/Domain-driven_Design)
+The software MUST use a DDD architecture.
+
+#### [SOLID](https://de.wikipedia.org/wiki/Prinzipien_objektorientierten_Designs#SOLID-Prinzipien)
+SOLID allows to easy maintain and expand the functions of the software.
+
+It is based on the following princibles:
+- [Single-Responsibility-Prinzip](https://de.wikipedia.org/wiki/Single-Responsibility-Prinzip)
+- [Open-Closed-Prinzip](https://de.wikipedia.org/wiki/Open-Closed-Prinzip)
+- [Liskov substitution principle](https://en.wikipedia.org/wiki/Liskov_substitution_principle)
+- [Interface-Segregation-Prinzip](https://de.wikipedia.org/wiki/Interface-Segregation-Prinzip)
+- [Dependency Inversion Prinzip](https://de.wikipedia.org/wiki/Dependency-Inversion-Prinzip)
+
+#### [12 factor](https://12factor.net/)
+The following 12 factor allow to get the application ready for [IaaS](https://de.wikipedia.org/wiki/Everything_as_a_Service) and make it [high scalable](https://en.wikipedia.org/wiki/Scalability):
+
+##### I. Codebase
+One codebase tracked in revision control, many deploys
+##### II. Dependencies
+Explicitly declare and isolate dependencies
+##### III. Config
+Store config in the environment
+#### IV. Backing services
+Treat backing services as attached resources
+##### V. Build, release, run
+Strictly separate build and run stages
+##### VI. Processes
+Execute the app as one or more stateless processes
+##### VII. Port binding
+Export services via port binding
+##### VIII. Concurrency
+Scale out via the process model
+##### IX. Disposability
+Maximize robustness with fast startup and graceful shutdown
+##### X. Dev/prod parity
+Keep development, staging, and production as similar as possible
+##### XI. Logs
+Treat logs as event streams
+##### XII. Admin processes
+Run admin/management tasks as one-off processes
+
+## Tested
+The software MUST be automized tested by the following tests:
+
+- [Functional tests](https://en.wikipedia.org/wiki/Functional_testing)
+- [Integration tests](https://de.wikipedia.org/wiki/Integrationstest)
+- [Unit Tests](https://en.wikipedia.org/wiki/Unit_testing)
+
+A test coverage of 100% must be reached.
+
+### Continues Integration
+The software MUST be [continues integrated](https://de.wikipedia.org/wiki/Kontinuierliche_Integration).
+
+### Applications
+The application is a merge out of two indepentend applications.
+#### Core Application
+More informations you will find in the [symfony README.md](./symfony/README.md)
+
+This software offers the following interfaces:
+##### [REST](https://de.wikipedia.org/wiki/Representational_State_Transfer)
+This interface allows a client, which can be e.g. a Java Application or an SPA to process the domain logic.
+
+##### HTML
+This interface offers an static GUI which allows the user to execute basic tasks.
+
+#### Single Page Application
+This application offers a [SPA](https://en.wikipedia.org/wiki/Single-page_application) on the base of [Vue.js](https://vuejs.org/) to allow a good and dynamic user experience.
+
+More informations you will find in the [node README.md](./node/README.md)

application/symfony/README.md

@@ -1,34 +1,43 @@
-## backend application
+# Core Application
 
-## conventions
+## Conventions
 
-### coding
+### Symfony
+The application MUST use [Symfony 4. coding standards](https://symfony.com/doc/current/contributing/code/standards.html).
 
-#### symfony
-The application MUST use Symfony 4. coding standards
-
-#### php
+### PHP
 PHP code MUST follow the [PSR-4](https://www.php-fig.org/psr/psr-4/) standard.
 
-#### twig
+### Twig
 Twig templates MUST follow the [Symfony Template best practices](https://symfony.com/doc/current/best_practices/templates.html).
 
-### naming
+### Naming
 
-#### interfaces
+#### Interfaces
 
 A Interfaces MUST be named *ClassnameInterface*.
 
 It SHOULD be based in the directory of the class.
 
-#### abstract classes
+Each class SHOULD implement an interface.
+
+#### Abstract Classes
 
 A abstract class MUST be named *AbstractClassname*.
 
 It SHOULD be based in the directory of the classes which inherit from it.
 
-###### entities
+## Technologies
+The following Symfony related components will be used:
+- [Services](https://symfony.com/doc/current/service_container.html)
+- [ORM](https://symfony.com/doc/current/doctrine.html)
+- [Routing](https://symfony.com/doc/current/routing.html)
+- [Form](https://symfony.com/doc/current/forms.html)
+- [Validation](https://symfony.com/doc/current/validation.html)
+- [Events](https://symfony.com/doc/current/event_dispatcher.html)
+- [Twig](https://twig.symfony.com/)
+- [REST](https://symfony.com/doc/master/bundles/FOSRestBundle/index.html)
+- [User Bundle](https://symfony.com/doc/current/bundles/FOSUserBundle/index.html)
 
-####### source
-
-A source MUST be named *SourcenameSource*.
+## Domain
+More information about the domain logic you will find in [./src/Domain/README.md](./src/Domain/README.md).