diff --git a/.classpath b/.classpath index 8024414..2d6b392 100644 --- a/.classpath +++ b/.classpath @@ -1,30 +1,26 @@ - - - - - - - + - - + - + + - + + + diff --git a/.externalToolBuilders/org.eclipse.jdt.core.javabuilder.launch b/.externalToolBuilders/org.eclipse.jdt.core.javabuilder.launch new file mode 100644 index 0000000..c1caeea --- /dev/null +++ b/.externalToolBuilders/org.eclipse.jdt.core.javabuilder.launch @@ -0,0 +1,7 @@ + + + + + + + diff --git a/.externalToolBuilders/org.eclipse.m2e.core.maven2Builder.launch b/.externalToolBuilders/org.eclipse.m2e.core.maven2Builder.launch new file mode 100644 index 0000000..f075191 --- /dev/null +++ b/.externalToolBuilders/org.eclipse.m2e.core.maven2Builder.launch @@ -0,0 +1,7 @@ + + + + + + + diff --git a/.gitignore b/.gitignore index b83d222..c341579 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /target/ +**/*.md.html \ No newline at end of file diff --git a/.project b/.project index b7e14e7..26de7d7 100644 --- a/.project +++ b/.project @@ -6,8 +6,23 @@ - org.eclipse.jdt.core.javabuilder + org.eclipse.ui.externaltools.ExternalToolBuilder + full,incremental, + + LaunchConfigHandle + <project>/.externalToolBuilders/org.eclipse.jdt.core.javabuilder.launch + + + + + org.eclipse.ui.externaltools.ExternalToolBuilder + full,incremental, + + + LaunchConfigHandle + <project>/.externalToolBuilders/org.eclipse.m2e.core.maven2Builder.launch + diff --git a/.settings/org.eclipse.jdt.core.prefs b/.settings/org.eclipse.jdt.core.prefs index abec6ca..d43d712 100644 --- a/.settings/org.eclipse.jdt.core.prefs +++ b/.settings/org.eclipse.jdt.core.prefs @@ -1,5 +1,9 @@ eclipse.preferences.version=1 +org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.5 org.eclipse.jdt.core.compiler.compliance=1.5 +org.eclipse.jdt.core.compiler.problem.assertIdentifier=error +org.eclipse.jdt.core.compiler.problem.enumIdentifier=error org.eclipse.jdt.core.compiler.problem.forbiddenReference=warning +org.eclipse.jdt.core.compiler.release=disabled org.eclipse.jdt.core.compiler.source=1.5 diff --git a/Jenkinsfile b/Jenkinsfile new file mode 100644 index 0000000..e508796 --- /dev/null +++ b/Jenkinsfile @@ -0,0 +1,44 @@ +pipeline { + agent { + label "docker" + } + + environment{ + def DOCKER_IMAGE = "jenkins-oft-arch-builder" + def DOCKER_REGISTRY = "" + } + + stages{ + stage("checkout") { + steps{ + checkout scm + } + } + + stage("build docker") { + steps{ + sh "docker build -t ${DOCKER_IMAGE} -f docker/Dockerfile ." + } + } + + stage("render html") { + steps { + sh "docker run --rm -v $WORKSPACE:/home/jenkins -v $WORKSPACE/.m2/:/root/.m2/repository ${DOCKER_IMAGE} mvn -B -U clean compile" + archiveArtifacts artifacts: '**/target/*.html,**/target/**/*', fingerprint: true + } + } + + stage("render pdf") { + steps { + sh "docker run --rm -v $WORKSPACE:/home/jenkins -v $WORKSPACE/.m2/:/root/.m2/repository ${DOCKER_IMAGE} mvn -B -U compile -P render-pdf" + archiveArtifacts artifacts: '**/target/*.pdf', fingerprint: true + } + } + } + + options { + buildDiscarder(logRotator(numToKeepStr:'10')) + timeout(time: 60, unit: 'MINUTES') + disableConcurrentBuilds() + } +} diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 5de6479..0000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2018 It's all code - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..e04b480 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,427 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + + including for purposes of Section 3(b); and + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/README.md b/README.md index fb32968..6167ede 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,221 @@ -# openfasttrace-architecture-template -Template for system and software architecture done with OpenFastTrace +# OpenFastTrace Architecture Template -## Build Dependencies +Template for system and software architecture done with OpenFastTrace. + +## Acknowledgments + +The architecture documents structure is based the the [arc42](https://arc42.org) architecture template by Dr. Gernot Starke, Dr. Peter Hruschka. + +The [arc42 template](https://github.com/arc42/arc42-template) is offered under the [CC-BY-SA](LICENSE.txt). Please keep attributions in all derived works. + +This build automatically includes license headers in the Markdown files for that reasons. See ["Automatic License Headers"](#automatic-license-headers) for details. + +## Change Log + +* [Change log](doc/changelog.md) + +## Installation + +### On Debian / Ubuntu Linux + +If you only want to render the document to you need to install [Pandoc](https://pandoc.org). UML diagrams are rendered with [PlantUML](https://plantuml.com). + +```bash +apt install plantuml pandoc +``` + +Since Pandoc renders PDFs with the Help of `pdflatex` you also need to install a appropriate TeX distribution. On Linux the [TeX Live](https://tug.org/texlive/) packages are typically part of the standard repositories. Since PlantUML generates SVGs as vector format, we also need a converter from SVN to PDF. + +```bash +apt install plantuml pandoc texlive-latex-base texlive-fonts-recommended librsvg2-bin +``` + +### On Fedora Linux + +```bash +yum install plantuml pandoc texlive-schema-full librsvg2-tools +``` + +## Project Layout + +The directory structure below shows the most important parts of the project layout and what they mean. + +``` +project root + |-- launch Eclipse launch configurations + | + |-- src + | |-- assembly Configuration for creating archives (TAR, ZIP) + | | + | |-- doc Markdown sources of the specification + | | |-- css CSS for the HTML output + | | ... + | | + | |-- license License and license headers + | | + | |-- main + | | '-- lua Lua filters for Pandoc + | | + | '-- uml PlantUML sources for the UML model + | |-- actors + | |-- classes + | |-- diagrams Sources for the UML diagrams + | | |-- activity + | | |-- class + | | ... + | ... + | + |-- target + | |-- .html Generated HTML output of the specification + | '-- .pdf Generated PDF + ... + '-- pom.xml Maven project configuration +``` + +**⚠ Be careful not to accidentally edit files in the target directory. It happens to us now and then and is each time a source of annoyance since the changes are gone with the next build run.** + + +## Authoring + +For authoring any text editor will work. + +We recommend using [Eclipse](https://eclipse.org), the built-in WikiText editor for [Markdown](https://daringfireball.net/projects/markdown/) and the [Eclipse PlantUML plug-in](http://plantuml.com/eclipse). + +Read the [OpenFastTrace User Guide](https://github.com/itsallcode/openfasttrace/blob/master/doc/user_guide.md) to learn how to create specifications in the OFT Markdown format. + +### Stripping the OFT Comments + +The template contains a lot of comments in the form of Markdown quotes starting with "OFT:". You can strip them with your editors multi-file search and replace function (e.g. CRTL+H in Eclipse). + +Or you can use command line tools like `sed`. Run the script below on the root directory of the architecture template. + +```bash +find src/doc -name '*.md' -exec sed -i -e '/^>\s*OFT:.*/d' {} \; +``` + +## Building + +### Build Dependencies + +| Dependency | Purpose | License | +|-----------------------------------------------------------------------------------------|------------------------|------------------------------------------------------------------------| +| [Assembly Maven plugin](https://maven.apache.org/plugins/maven-assembly-plugin/) | Pack into archive | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) | +| [Copy resources Maven plugin](https://maven.apache.org/plugins/maven-resources-plugin/) | Copy original files | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) | | +| [Exec Maven plugin](https://www.mojohaus.org/exec-maven-plugin/) | Running Pandoc | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) | +| [License Maven plugin](http://www.mojohaus.org/license-maven-plugin/) | Adding license headers | [GPL v3.0](http://www.gnu.org/licenses/quick-guide-gplv3.html) | +| [Maven](https://maven.apache.org/) | Build | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) | +| [Pandoc](https://pandoc.org) | Document rendering | [GPL v3.0](http://www.gnu.org/licenses/quick-guide-gplv3.html) | +| [PlantUML Maven plugin](https://github.com/jeluard/maven-plantuml-plugin) | Diagram rendering | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) | + +### Configuration + +You can find the configuration for the build in the [Maven `pom.xml` file](pom.xml) of this project. + +To configure the build variables like document name and version number change the properties: + +```xml + + + + ${project.version} + ${maven.build.timestamp} + AutoYummiBox ${spec.version} - Software Architectural Design + S. Bär, M. Thielcke + SwAD-AutoYummiBox + architecture.md introduction.md context.md + ... + glossary.md bibliography.md + + + +``` + +The `spec.files` property must contain all files you want to render into the specification in the order in which that must be concatenated. + +#### Defaults + +The document version (`spec.version`) defaults to the version of the Maven artifact. This has the advantage that the version only needs to be maintained in a single place. + +The document date (`spec.date`) defaults to the date of the build which is usually what you want if you build, release and deploy a document with [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration). + +While you will have to adapt the document's title (`spec.title`), we recommend that you let the build inject the version number as in the original example. + +**⚠ If you introduce new files, don't forget to list them there!** + +### Automatic License Headers + +The Maven build automatically checks whether all markdown files have a license header in in life cylce phase "validate". The build fails if one or more headers are missing. + +Run the following Maven command to create or update the file headers: + +```bash +mvn license:update-project-license license:update-file-header +``` + +### Conversion + +The original files are in Markdown format. The general idea of the links between those files is that you can navigate without conversion to other formats already. This way you can read your specifications directly in your favorite repository viewer. + +On the other hand you of course want the links to work properly when converting to HTML or PDF too. Pandoc allows us to use filters during conversion that achieve this. Either as filters in a pipe on the console or via the built-in Lua interpreter. + +Check the following [Lua](https://www.lua.org/) file to see how the original links between the source Markdown files are converted to the target format. + + src/main/lua/link_converter.lua + +The filter is applied via the `--lua-filters` command line switch. + +### Running the Build + +If you only want to render the document and UML source into HTML and images run: + +```bash +mvn compile +``` + +To create archives from the rendered documents run: + +```bash +mvn package +``` + +## Validation + +It is a good idea to check the links in your document from time to time. + +### Under Debian / Ubuntu + +Install the `linkchecker` package: + +```bash +apt install linkchecker +``` + +Check the links in the generated HTML docuements: + +```bash +linkchecker --check-extern target/*.html +``` + +If you remove the command line switch `--check-extern` only local links are checked. + +## Continuous Integration + +This project contains a CI setup for Jenkins. The build uses [Docker](https://www.docker.com/) to provide a stable environment for its execution. So Jenkins needs to be able to execute Docker commands. +The build process itself is defined within `Jenkinsfile` and consists of these stages: +- checkout : Get the source from repo +- build docker : Create the Docker image to be used during build execution (only once if it doesn't exist locally) +- render html : render a HTML file from sources +- render pdf : render a PDF file from source + +The rendering of HTML, PDF,... is controlled with Maven profiles (`render-html`, `render-pdf`). To enable other/ additional formats new profiles can be defined within `pom.xml`. + +### Build without Docker + +If there is no Docker installation available the required tools/ dependencies described above need to be provided on Jenkins or at least one of its agents. +- [docker/Dockerfile](docker/Dockerfile) can be used as template for the setup of the required tools. +- the Jenkins agents should be labeled accordingly (i.e. pandoc) +- `Jenkinsfile` : label needs to match agent-labels (i.e. pandoc) +- `Jenkinsfile` : the "build docker" stage has to be removed +- `Jenkinsfile` : the "run docker"-part has to be removed from sh-executions -| Dependency | Purpose | License | -|-----------------------------------------------------------------------------------------------------------|------------------------|------------------------------------| -| [License Maven Pplugin ](http://www.mojohaus.org/license-maven-plugin/) | Adding license headers | GPL v3.0 | -| [flexmark-java](https://github.com/vsch/flexmark-java) | Rendering | Non-standard free software license | -| [Markdown to HTML page generator Maven plugin](https://github.com/walokra/markdown-page-generator-plugin) | Rendering | MIT License | \ No newline at end of file diff --git a/doc/changelog.md b/doc/changelog.md new file mode 100644 index 0000000..4046949 --- /dev/null +++ b/doc/changelog.md @@ -0,0 +1,3 @@ +## Change Log + +* [1.0.0](changes_1.0.0.md) \ No newline at end of file diff --git a/doc/changes_1.0.0.md b/doc/changes_1.0.0.md new file mode 100644 index 0000000..f9daed0 --- /dev/null +++ b/doc/changes_1.0.0.md @@ -0,0 +1,5 @@ +# OpenFastTrace Architecture Template - 1.0.0 + +In this release we updated the PlantUML dependency to fix CVE-2023-3432. + +* #8: Updated the PlantUML dependency to fix CVE-2023-3432 \ No newline at end of file diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..59c39e8 --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,18 @@ +FROM maven:3.5-jdk-8 + +ARG PANDOC_VERSION="2.2.3.2" + +# Install dependencies texlive, graphviz +RUN apt-get update \ + && apt-get install -y texlive-latex-base graphviz \ + && apt-get autoremove --purge -y \ + && apt-get autoclean -y \ + && apt-get clean + +# pandoc 2.x required +RUN curl -fL https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/pandoc-${PANDOC_VERSION}-linux.tar.gz | tar xzv --strip-components 1 -C /usr/local/ + +RUN apt-get install -y texlive-fonts-recommended librsvg2-bin + +# Set workdir (also mountpoint for docker volume) +WORKDIR /home/jenkins diff --git a/launch/arch-template - clean.launch b/launch/arch-template - clean.launch index c4731af..e06667b 100644 --- a/launch/arch-template - clean.launch +++ b/launch/arch-template - clean.launch @@ -12,6 +12,9 @@ + + + diff --git a/launch/arch-template - compile.launch b/launch/arch-template - compile.launch new file mode 100644 index 0000000..d8cf717 --- /dev/null +++ b/launch/arch-template - compile.launch @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/launch/arch-template - license update.launch b/launch/arch-template - license update.launch index 84cd807..68bcf03 100644 --- a/launch/arch-template - license update.launch +++ b/launch/arch-template - license update.launch @@ -12,6 +12,9 @@ + + + diff --git a/launch/arch-template - package.launch b/launch/arch-template - package.launch new file mode 100644 index 0000000..0d9f4b0 --- /dev/null +++ b/launch/arch-template - package.launch @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/launch/maven license-list.launch b/launch/maven license-list.launch index ed49743..ff92d0b 100644 --- a/launch/maven license-list.launch +++ b/launch/maven license-list.launch @@ -12,6 +12,9 @@ + + + diff --git a/pom.xml b/pom.xml index 56a1d57..6b48446 100644 --- a/pom.xml +++ b/pom.xml @@ -2,27 +2,78 @@ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - openfasttrace-architecture-template + org.itsallcode openfasttrace-architecture-template - 0.1.0 + 1.0.0 https://github.com/itsallcode/openfasttrace-architecture-template.git itsallcode.org - - https://github.com/itsallcode/openfasttrace-architecture-template/issues - https://github.com/itsallcode/openfasttrace - OpenFastTrace + OpenFastTrace Architecture Template Free software requirement tracing suite + + yyyy-MM-dd + ${project.version} + ${maven.build.timestamp} + AutoYummiBox ${spec.version} - Software + Architectural + Design + S. Bär, M. Thielcke + SwAD-AutoYummiBox + architecture.md introduction.md context.md + solution_strategy.md building_block_view.md + building_block_view/MachineApplication.md runtime_view.md + runtime_view/ordering_dishes.md + runtime_view/preparing_dishes.md + runtime_view/paying_with_credit_card.md deployment_view.md + concepts.md design_decisions.md quality_scenarios.md + risks.md + glossary.md bibliography.md + UTF-8 + + ${project.basedir}/src/doc + ${spec.source.directory}/css + ${project.basedir}/src/uml + ${project.build.directory} + ${project.build.directory} + ${project.build.directory}/uml + ${project.build.directory}/css + ${spec.build.html.directory}/${spec.filename}.html + ${spec.build.pdf.directory}/${spec.filename}.pdf + ${project.basedir}/src/main/lua + - com.github.jeluard + maven-resources-plugin + 3.3.1 + + + copy-resources + process-resources + + copy-resources + + + ${spec.build.css.directory} + + + ${spec.source.css.directory} + true + + + + + + + + com.github.davidmoten plantuml-maven-plugin - 1.2 + 0.2.9 + plantuml process-resources generate @@ -30,57 +81,193 @@ - - ${basedir}/src/main/resources/uml/diagrams + + ${spec.model.directory}/diagrams **/*.plantuml - - svg - ${basedir}/target/html/uml + + + svg + + ${spec.build.uml.directory} + true net.sourceforge.plantuml plantuml - 1.2018.8 + 1.2023.13 - com.ruleoftech - markdown-page-generator-plugin - 2.1.0 + + org.codehaus.mojo + license-maven-plugin + 2.3.0 + + false + true + cc-by-sa-4.0 + ${project.baseUri}/src/license + itsallcode.org + 2018 + + + true + true + true + UTF-8 + false + + xml + xml + + + ${spec.source.directory} + + + **/*.md + **/*.markdown + + - process-resources + check-file-header - generate + check-file-header + validate + + + first + + update-file-header + + process-sources + + + org.apache.maven.plugins + maven-assembly-plugin + 3.6.0 - ${project.basedir}/src/main/resources/markdown - true - md, markdown - UTF-8 - UTF-8 - ${basedir}/src/main/resources/html/header.html - css - true + + ${project.basedir}/src/assembly/htmldoc.xml + + ${spec.filename}-${project.version} + + + assembly + package + + single + + + - - \ No newline at end of file + + + render-pdf + + + + org.codehaus.mojo + exec-maven-plugin + 3.1.1 + + + pandoc-pdf + compile + + pandoc + ${spec.source.directory} + --from=markdown + --to=latex + --standalone + --toc + --number-sections + --lua-filter=${lua.source.directory}/pdf_image_path_converter.lua + --strip-comments + --output=${spec.file.pdf} + --metadata=title:"${spec.title}" + --metadata=date:"${spec.date}" + --metadata=author:"${spec.authors}" + ${spec.files} + + + exec + + + + + + + + + render-html + + true + + + + + org.codehaus.mojo + exec-maven-plugin + 1.6.0 + + + pandoc + compile + + pandoc + ${spec.source.directory} + --from=markdown + --to=html5 + --standalone + --toc + --number-sections + --css=${spec.source.css.directory}/spec.css + --lua-filter=${lua.source.directory}/link_converter.lua + --strip-comments --output=${spec.file.html} + --metadata=title:"${spec.title}" + --metadata=date:"${spec.date}" + --metadata=author:"${spec.authors}" + ${spec.files} + + + exec + + + + + + org.apache.maven.plugins + maven-enforcer-plugin + 3.4.1 + + + enforce-maven + + enforce + + + + + 3.6.3 + + + + + + + + + + + diff --git a/src/assembly/htmldoc.xml b/src/assembly/htmldoc.xml new file mode 100644 index 0000000..10aafb6 --- /dev/null +++ b/src/assembly/htmldoc.xml @@ -0,0 +1,33 @@ + + htmldoc + + tar.gz + tar.bz2 + zip + + + + src + + LICENSE* + + + + target + + + *.html + + + + target/uml + uml + + **/* + + + + \ No newline at end of file diff --git a/src/main/resources/markdown/architecture.md b/src/doc/architecture.md similarity index 71% rename from src/main/resources/markdown/architecture.md rename to src/doc/architecture.md index d2f8ff5..ee5e2dd 100644 --- a/src/main/resources/markdown/architecture.md +++ b/src/doc/architecture.md @@ -1,13 +1,22 @@ -# OFTAutoYummy - System Architecture + > OFT: In this system architecture template we are discussing the design of a fictional product "OFTAutoYummy" that synthesizes meals from raw materials and is basically a 3D printer for ready-made food. The example is intended to demonstrate architectural considerations of a project that has both hardware and software parts. -> OFT: The structure of the architectural template is based on the arc42 template (https://www.arc42.de) by Dr. Gernot Starke and Dr. Peter Hruschka. Both, the arc42 template and this template are licensed under the [Creative-Commons-BY license](../LICENSE). +> OFT: The structure of the architectural template is based on the arc42 template ([arc42.org](https://arc42.org)) by Dr. Gernot Starke and Dr. Peter Hruschka. Both, the arc42 template and this template are licensed under the [Creative-Commons-BY-SA license](../LICENSE.txt). > OFT: In order to allow for requirement tracing, the template uses the "Requirement-enhanced Markdown format" defined by the [OpenFastTrace](https://github.com/itsallcode/openfasttrace) project. The examples and additions also come from this project. -> OFT: Comments are typeset as block quotes in this document and lead in by "OFT:" so that you can easily remove them with "search & replace". +> OFT: Comments are typeset as block quotes in this document starting with "OFT:" so that you can easily remove them with "search & replace". > OFT: The chapters of this document are contained in separate files. We recommend this especially for larger projects where multiple persons will work on parts of the document in parallel. This way the merging overhead is lower. Also this keeps the files from growing to sizes that are unmanageable. @@ -19,16 +28,16 @@ 2. [Context](context.md) 3. [Constraints](constraints.md) 4. [Solution strategy](solution_strategy.md) -5. [Building blocks](building_blocks.md) -6. [Runtime](runtime.md) -7. [Deployment](deployment.md) +5. [Building blocks](building_block_view.md) +6. [Runtime](runtime_view.md) +7. [Deployment](deployment_view.md) 8. [Cross-cutting Concerns](concerns.md) 9. [Design Decisions](design_decisions.md) 10. [Quality Scenarios](quality_scenarios.md) -11. [Risks](risks/risks.md) +11. [Risks](risks.md) 12. [Glossary](glossary.md) 13. [Bibliography](bibliography.md) > OFT: Note that in comparison to the original arc42 template, we exchanged the order of the chapters [context](context.md) and [constraints](constraints.md) since we feel that understanding the system context is necessary before understanding which constraints apply. -> OFT: the bibliography chapter does not appear in the original arc42 template but turned out to be a good idea nonetheless. \ No newline at end of file +> OFT: the bibliography chapter does not appear in the original arc42 template but turned out to be a good idea nonetheless. diff --git a/src/doc/bibliography.md b/src/doc/bibliography.md new file mode 100644 index 0000000..2d86a2e --- /dev/null +++ b/src/doc/bibliography.md @@ -0,0 +1,38 @@ + + +# Bibliography + +> OFT: The bibliography provides an overview over all external document and web site sources that you used when creating this architecture. Make sure to credit the authors. + +> OFT: One of the most important things is that you should add links to the original sources so that readers can find the information quickly. Keep in mind that not all readers have access to all the systems you have access to. A hint on how to apply for access is a nice gesture. + +## Specifications + +* SRS: "OFTAutoYummi - System Requirement Specification", *S. Baer, Chr. Pirkl*, 2018, [itsallcode.org](http://itsallcode.org) + +## Standards + +> OFT: List here any standards that you refer to in your documents. For example IETF RFCs or ISO standards. + +* "[RFC 2119: Key words for use in RFCs to Indicate Requirement Levels](https://tools.ietf.org/html/rfc2119)", *S. Brander*, 1997, Harvard Univerity + +## Documents + +* ASGL: "Logging Guideline", *J. Weng, M. Liu"*, 2017 +* OAY-ORGA: "OFTAutoYummi Organization", *J. Doe*, 2018 +* LGL: "Logging Guideline", *M. Mustermann"*, 2017 +* MGL: "Monitoring Guideline", *L. Smith"*, 2017 +* ATAM: "[The Architecture Tradeoff Analysis Method](https://resources.sei.cmu.edu/library/asset-view.cfm?assetID=13091)", *R. Kazman, et. al.*, Carnegie Mellon Software Engineering Institute, July 1997 + +## Web Sites + +> When your refer to web sites remember to add the date when you accessed them so that readers are not disappointed when they find out the content you referred to is gone. diff --git a/src/main/resources/markdown/building_blocks.md b/src/doc/building_block_view.md similarity index 81% rename from src/main/resources/markdown/building_blocks.md rename to src/doc/building_block_view.md index 39014a1..8ba76e2 100644 --- a/src/main/resources/markdown/building_blocks.md +++ b/src/doc/building_block_view.md @@ -1,3 +1,14 @@ + + # Building Block View > OFT: This chapter is usually every readers favorite. First because it usually contains a lot of pictures, second because it advances the understanding of the system most. @@ -50,6 +61,8 @@ This section contains the building block breakdown on the highest level. > OFT: If you want to make sure the components you define in this architecture appear in the actual detailed designs (and in the implementations) we recommend that you create one specification item for each internal component and require coverage on detailed design level (here `dsn`). Of course you should talk the component breakdown through with the implementing teams in order to get their agreement. Otherwise you will end up with a nice architecture document that nobody cares about. +> OFT: We use tags in the specification items to allow filtering. This helps splitting the workload between multiple development teams since each team can define tag filters to check coverage for the components they are responsible for. Check the [OFT User Guide](https://github.com/itsallcode/openfasttrace/blob/master/doc/user_guide.md) to learn more about tag filters. + ### AutoYummyBox `arch~ayb.autoyummybox~1` @@ -57,7 +70,9 @@ This hardware component is a vending machine with a built-in 3D food printer. It Needs: dsn -> OFT: Note that we did not cover a SRS requirement with this component decision. The reason is simple: you would have to link each SRS requirement that is implemented in this component with the component in addition to the runtime requirements. This is way to error-prone to be practical and also not very helpful. +Tags: AutoYummyBox + +> OFT: Note that we did not cover an SRS requirement with this component decision. The reason is simple: you would have to link each SRS requirement that is implemented in this component with the component in addition to the runtime requirements. This is way to error-prone to be practical and also not very helpful. ### MachineApplication `arch~ayb.machine-application~1` @@ -66,6 +81,8 @@ The MachineApplication is an embedded software that controls the operation of th Needs: arch +Tags: MachineApplication + ### MachineManager `arch~ayb.machinemanager~1` @@ -73,6 +90,8 @@ The MachineManager is a backend component that serves as a single entry point fo Needs: arch +Tags: MachineManager + > OFT: ... > OFT: We stop the enumeration of top-level components at this point of the example because adding more would not contribute to a better understanding @@ -81,5 +100,5 @@ Needs: arch ## Sub-Level 1 Building Blocks -* [MachineApplication Building Blocks](building_blocks/MachineApplication.md) -* ... \ No newline at end of file +* [MachineApplication Building Blocks](building_block_view/MachineApplication.md) +* ... diff --git a/src/doc/building_block_view/MachineApplication.md b/src/doc/building_block_view/MachineApplication.md new file mode 100644 index 0000000..66b44e2 --- /dev/null +++ b/src/doc/building_block_view/MachineApplication.md @@ -0,0 +1,70 @@ + + +### MachineApplication + +> OFT: Whether or not you go into more detail here in the architecture depends on multiple factors. + +> OFT: First there is the agreement with the development teams. Do they cover the full details of the sub-level 1 component design? If so, do you still hint at least the components on this level? + +> OFT Will there be a detailed design at all? + +> OFT: Note that in this example we are assuming that the development teams create an individual detailed design document for each top-level component and the architecture therefore requires the according artifact type `dsn`. We also assume that the teams and architects agreed that the architecture document should at least show the sub-level 1 components in order to help new developers get up to speed with the system quicker and also to see if architects and development teams have the same understanding of the component breakdown. + +This section contains the internal component breakdown of the MachineApplication component. + +The breakdown is kept rough intentionally to avoid excessive information duplication with the detailed design documents. + +![MachineApplication composition](uml/component/comp_machine_application.svg "MachineApplication composition") + +> OFT: The main purpose of the above diagram in the context of this architecture example is to demonstrate a variety of component and package relationships. Explaining the structure of the product is one of if not the most important job of a architecture. + +The MachineApplication is a combination of hardware and software components. With the exception of the [FoodPrinter](#foodprinter) all hardware components are designed and produced by external suppliers. + +In case of the paste containers this is due to the fact that the companies providing the pastes offer better prices when they are allowed to bundle the pastes with their own container designs. Nevertheless, physical outside dimensions as well as the electrical interface and communications protocol are defined by AutoYummyBox. + +> OFT: Look at the component diagram. You can see from the package structure that the interface is owned internally. This is the structure of choice if you want to create a plug-in architecture. + +The CreditCardReader is a self-sufficient standard component that only requires an external HttpClient. See ["Which Embedded HTTP Client do we use?"](../design_decisions.md#which-embedded-http-client-do-we-use) in the ["Design Decisions"](../design_decision.md) chapter for details about how this influences the architecture of the backend connection. + +> OFT: Some design decisions are a constant source of discussion. We intentionally picked the HTTP client as an example since from our experience this topic always ignites heated debates in the embedded world. + +> OFT: This also gives us the opportunity to demonstrate what you should do if you don't own an interface you depend on. Of course an external HTTP client brings its own interface, but we have the MachineBackendConnector component in place where adapt if necessary. Same is true for the CreditCardConnector and PaymentHanlder. + +#### PasteContainer +`arch~ayb.pastecontainer~1` + +A PasteCoPaymentHandlerardware component that contains one of the pastes that serve as raw material for the dishes AutoYummiBox serves. It has a controller built in that can identify the contents and fill grade. + +Comments: + +While the specification for the paste containers physical outside dimensions as well as the electrical and software interface are owned by the AutoYummiBox project, the containers themselves are designed and manufactured by external suppliers. + +Needs: dsn + +Tags: PasteContainer + +#### FoodPrinter +`arch~ayb.foodprinter~1` + +The FoodPrinter is a hardware component that is feed with [pastes](glossary.md#paste) and prints a dish out of them. + +Comments: + +The FoodPrinter is designed and produced by the hardware department of AutoYummiBox. + +Needs: dsn + +Tags: FoodPrinter + +> OFT: ... + +> OFT: we end the components list here since adding more would not advance the example. diff --git a/src/doc/concepts.md b/src/doc/concepts.md new file mode 100644 index 0000000..69f9240 --- /dev/null +++ b/src/doc/concepts.md @@ -0,0 +1,80 @@ + + +# Concepts + +This chapter contains cross-cutting concerns of the system, i.e. all architectural definitions that apply to multiple parts of the system. + +> OFT: Depending on the kind of concept, it can be really hard to use specification items and tracing. The reason is simple: since the concepts by definition often cut across big parts of the system, there is no single place where you can cover the specification items. This is especially true for [guidelines](#guidelines). + +> As a compromise we recommend creating specification items that do not require coverage. This way it is clear that they are normative but you do not expect implementors to invest unreasonable efforts to document the coverage. + +## Domain Models + +> OFT: Domain Models are one of the best ways to communicate with your end users. The problem domain is something they are concerned with every day, so they know it inside out. + +> OFT: One of the core concepts of Object Oriented Programming and Object Oriented Analysis is to model the object according to the experience of the end users. + +> OFT: The diagrams of choice for this part of the model are [class diagrams](http://plantuml.com/class-diagram) and [object diagrams](http://plantuml.com/object-diagram). + +### Menu, Dishes and Recipes + +This section describes the terms "menu", "dish" and "recipe" and their relationships. + +![Menu, dishes and recipes](uml/class/cl_dishes.svg "Menu, dishes and recipes") + +#### Dishes +`arch~ayb.dishes~2` + +Dishes have the following attributes: +* name (String) +* price (MonetaryAmount) +* recipe (Recipe) + +Covers: + +* `req~ayb.list-dishes~1` +* `req~ayb.pick-dish~2` +* `req~ayb.search-dishes~1` +* `req~ayb.pay-dish~2` + +Needs: dsn + +Tags: Cook, CookingBook + +#### Recipe +`arch~ayb.recipe~1` + +A Recipe is a series of steps to cook a Dish. + +Covers: + +* `req.ayb.cook-dishes~1` +* `req.ayb.list-nutrition-facts~1` + +Needs: dsn + +Tags: Cook, CookingBook + +> OFT: ... + +> OFT: As before we stop the specification item list here since you got the point. + +## Guidelines + +> OFT: Only guidelines that are project specific should appear in this section. For guidelines with a broader scope, a reference is a better idea. Don't forget to add them in the [Bibliography](bibliography.md). + +The following guidelines apply to the development of this system: + +1. [Logging Guideline](bibliography.md#lgl) +1. [Monitoring Guideline](bibliography.md#mgl) +1. [Account Security Guideline](bibliography.md#asgl) +1. ... diff --git a/src/main/resources/markdown/context.md b/src/doc/context.md similarity index 88% rename from src/main/resources/markdown/context.md rename to src/doc/context.md index 8aff8c7..255c59e 100644 --- a/src/main/resources/markdown/context.md +++ b/src/doc/context.md @@ -1,3 +1,14 @@ + + # System Scope and Context > OFT: Often you will find the general system context in your system requirement specification (SRS) already. Whether or not to copy that depends on if you prefer to present a mostly self-contained architecture document or to focus on the single-source principle (DRY). @@ -36,7 +47,7 @@ Machine Maintainers are responsible for keeping the AutoYummiBoxes clean and sto > OFT: Neighboring systems are project-external technical systems that are attached to your system or that your system attaches to. Systems run by the same company which are outside of the responsibility of this project also count as external. -> OFT: arc42 suggests listing technical details about the communication channels to the neighboring systems. We recommend that you do not go to this level of detail here since in a non-trivial system interface descriptions go beyond the scope of a simple system context, often involving painful architectural decisions between available communication options. Those details are better kept in the [Building Block View](building_blocks.md) and [Deployment View](deployment.md) chapter. Also keep in mind that the context chapter is often read by management and needs to be on an abstraction level managers are able to follow. +> OFT: arc42 suggests listing technical details about the communication channels to the neighboring systems. We recommend that you do not go to this level of detail here since in a non-trivial system interface descriptions go beyond the scope of a simple system context, often involving painful architectural decisions between available communication options. Those details are better kept in the [Building Block View](building_block_view.md) and [Deployment View](deployment.md) chapter. Also keep in mind that the context chapter is often read by management and needs to be on an abstraction level managers are able to follow. #### Payment Provider @@ -44,4 +55,4 @@ Payment Providers are companies offering to handle payment transactions. Since h #### Paste Factory -Paste Factories are production plants that deliver the [pastes](glossary.md#paste) that the OftAutoYummyBoxes need to operate. They accept automatic orders and deliver the [paste containers](glossary.md#paste-container) to [container distribution centers](glossary.md#container-distribution-center). \ No newline at end of file +Paste Factories are production plants that deliver the [pastes](glossary.md#paste) that the OftAutoYummyBoxes need to operate. They accept automatic orders and deliver the [paste containers](glossary.md#paste-container) to [container distribution centers](glossary.md#container-distribution-center). diff --git a/src/main/resources/markdown/css/spec.css b/src/doc/css/spec.css similarity index 52% rename from src/main/resources/markdown/css/spec.css rename to src/doc/css/spec.css index 84f494e..17206f4 100644 --- a/src/main/resources/markdown/css/spec.css +++ b/src/doc/css/spec.css @@ -1,6 +1,7 @@ @CHARSET "UTF-8"; body { + width: calc(100% - 32em); counter-reset: section; font-family: Helvetica, arial, sans-serif; font-size: 14px; @@ -12,6 +13,23 @@ body { color: #333; } +.title { + font-size: 40px; +} + +.author { + font-weight: bold; + text-align: center; +} + +.date { + text-align: center; +} + +header { + margin-bottom: 4em; +} + h1, h2, h3, h4 { border-style: none; text-decoration-line: none; @@ -34,7 +52,7 @@ h4 { font-size: 16px; } -li { +ul { list-style-type: square; } @@ -55,11 +73,54 @@ h6 + p > code:first-of-type { text-align: right; width: 100%; position: relative; - top: -2.5em; + top: -1.5em; } blockquote { - color: darkviolet; - border-left: 1px solid darkviolet; + color: #515194; + border-left: 1px solid #515194; padding-left: 1em; } + +#TOC { + position: fixed; + top: 0px; + height: calc(100%); + width: 28em; + margin-left: calc(100% - 30em); + overflow-y: scroll; + box-shadow: -10px 0px 10px lightgrey; +} + +#TOC ul { + list-style-type: none; + padding-left: 1em; +} + +#TOC li { + padding-bottom: 0.25em; + padding-top: 0.25em; +} + +#TOC a { + text-decoration: none; + color: dimgrey; +} + +#TOC a:hover { + text-decoration: underline; + color: dimgrey; +} + +p.caption { + margin-left: 6em; +} + +p.caption:before{ + font-weight: bold; + content: "Figure: " +} + +img { + max-width: 100%; +} \ No newline at end of file diff --git a/src/doc/deployment_view.md b/src/doc/deployment_view.md new file mode 100644 index 0000000..c25f608 --- /dev/null +++ b/src/doc/deployment_view.md @@ -0,0 +1,91 @@ + + +# Deployment + +This chapter describes the deployment of the system. Where the chapter ["Building Blocks"](building_block_view.md) only describes the components, their dependencies and interfaces, this chapter here discusses on which runtime environments the components are deployed, how they are networked and where to find the artifacts they need. + +> OFT: Unsurprisingly the deployment chart is the most important tool to layout the deployment. + +> OFT: Allow us a word of warning learned from painful experience through many projects. Don't try to describe the low level details of the system deployment in this document. Machine names, IP addresses, ports and such have a life cycle that is most definitely incompatible with a system architecture document. Also operators and DevOps teams usually do not accept that their freedom to change the deployment details as needed is reduced by a static architecture document. + +> OFT: The right level for a system architecture is to discuss general questions like: Relational or NoSQL database? Deploy in your own data center or on a public cloud? + +> OFT: Network segmentation is already a corner case where it could make sense to define it in the system architecture. + +> OFT: In any case make sure you work out this chapter in close collaboration with your operations or DevOps teams if you want it to have any relevance in the real world. + +> OFT: If your projects deployment setup is small enough it is a good idea to start with a complete overview, since readers are always going to ask for it. Unfortunately from a certain system size on there is no chance to depict everything that is important in one diagram while still keeping it readable. As always with UML modeling the way out is drill-down, splitting diagrams or a combination of both. + +![Deployment overview](uml/deployment/depl_overview.svg "Deployment overview") + +The diagram below shows how the AutoYummyBoxes, the backend and the external backends of the payment providers and paste factories are connected. + +> OFT: Note that only the network boundary that the project is responsible for is depicted here. While we can assume that for example the credit card institutes have their own data centers, the exact deployment does not matter here, since we cannot influence it anyway. For the project it is just an external System connected via the Internet. + +## AutoYummyBox Redundant Network Connections +`arch~ayb.box.redundant-network-connections~1` + +Each AutoYummyBox has an Internet connection via at least two distinct modems and network providers (e.g. DSL via network provider A and 3G via network provider B). + +Covers: + +* `ayb.box.availability~1` + +Needs: dsn + +## AutoYummyBox Backend Connection +`arch~ayb.backend-connection~1` + +Each AutoYummyBox has a network route to at least one AutoYummyBox Backend. + +Rationale: + +AutoYummyBoxes are designed to work offline for at least a day with the exception for the payment part. This allows us to reduce the number of necessary data centers in regions where connections to data centers are restricted. For example it is no problem to reroute a AutoYummyBox from the US to the EU, but we are not allowed to route to other regions from Elbonia. + +Comment: + +Since VirtuCoinBuddy payments are done via the AutoYummyBox Backend, only credit card payment is possible in case of connection problems. This is accepted behavior. + +Covers: + +* `ayb.box.availability~1` + +Needs: dsn + +> OFT: This is a typical example of a situation where documenting a decision in the architecture is a good idea. You made an important design decision based on the user requirement. It saves costs while sacrificing the availability of the backend connection, depending on offline capabilities instead. + +## AutoYummyBox Credit Card Provider Connection +`arch~ayb.box-credit-card-provider-connection~1` + +Each AutoYummyBox has network routes to at least two distinct backends of credit card institutes. + +Covers: + +* `ayb.box.availability~1` + +Needs: dsn + +## AutoYummyBox Internal Deployment + +> OFT: As discussed before you have to agree with the development teams where your responsibility as a system architect ends and their responsibility starts. For the sake of the example we are going to discuss the internal deployment of an embedded component. + +![AutoYummyBox internal deployment](uml/deployment/depl_autoyummybox.svg "AutoYummyBox internal deployment") + +> OFT: Compare the deployment diagram above to the component structure in section ["MachineApplication"](building_block_view/MachineApplication.md). You will notice that the associations don't have directions anymore. The deployment diagram is not the right place to depict component dependencies. + +> OFT: More importantly you can see the runtime environments (both in hardware and software) hinted in the diagram. + +The network and bus connections inside the AutoYummyBox are predefined by the hardware supplier. + +The product used as embedded database is intentionally not specified. Selecting one is at the discretion of the designers of the [MachineApplication](building_block_view/MachineApplication.md). + +> OFT: Note that it is a perfectly normal situation to have internal components deployed on project-external runtime environments. \ No newline at end of file diff --git a/src/doc/design_decisions.md b/src/doc/design_decisions.md new file mode 100644 index 0000000..d6762ff --- /dev/null +++ b/src/doc/design_decisions.md @@ -0,0 +1,75 @@ + + +# Design Decisions + +This section elaborates the most important design decisions. Criteria for whether decisions relevant enough to be discussed here — as opposed to mentioned in the other chapters of the architecture — are: + +* Does the decision make the system hard to change later? +* Will the decision be a constant source of controversy? +* Costs +* Risks + +## Vending Machine Related Decisions + +> OFT: Below we demonstrate typical (if admittedly constructed) situations that require design decisions on architectural level. The main goal of the whole chapter is to avoid having the same discussions over and over in your project. This is also why it is essential that the decision contexts are properly explained and the decision are justified in comprehensible fashion. + +### Which Embedded HTTP Client do we use? + +> OFT: Unless the context is common knowledge, start with a short explanation of the situation to set the stage. + +We need an HTTP client for the communication with our backends REST services. This decision is about which one we pick. + +The CreditCardReader we are using has a built-in HTTP Client from Wriggly Wombat Soft, a daughter company of the reader's manufacturer Wriggly Wombat Corporation. +The credit card reader is a component certified by the credit card industry. The embedded software on the device is proprietary and the part of the certified product. +Wriggly Wombat Soft gave us the opportunity to make a code quality assessment in exchange for signing an NDA. We found the overall quality of the software and the build process to be very high. +The manufacturer of the CreditCardReader forwards the per-machine license costs of the WrigglyWombatHttpClient to its customers. Software Updates are free-of-charge for the term defined in the contract with the Wriggly Wombat Corporation. + +Wriggly Wombat Soft agreed to fix any security vulnerabilities we find in the HTTP client within a timeframe of maximum two weeks for the duration of the contract. + +The CreditCardReader updates its internal embedded software autonomously — including the built-in HTTP client. Software versions can be read through the CreditCardReaders external interface. + +Wriggly Wombat Soft Announces regular updates five days in advance, critical security updates are installed immediately. + +> OFT: Not all design decisions need to be discussed in detail in the architecture. Especially if they concern only a single component. Therefore you should explain why you consider the decision to be architecture-relevant. + +This decision is architecture-relevant because it impacts: + +* system complexity +* reliability +* maintainability +* license costs +* liability + +We considered the following alternatives: + +1. Attaching to the WombatHttpClient from the outside. + + This Does not work since the interface is not exposed to the outside of the CreditCardReader. Modifications are out of the question since this would break the terms of use and void the certification. + +1. Choosing an HTTP client that differs from the one in the CreditCardReader. + + The benefits would be that we could pick a client of our choosing. The downside would be that we have twice the chance for vulnerabilities due to two different HTTP clients. In case we would choose a commercial client we also would have to pay license fees twice. + +> OFT: Wrap the actual decisions in specification items so that they become part of the tracing chain. + +#### MachineApplication uses WombatHttpClient +`arch~ayb.machineapplication-uses-wombathttpclient~1` + +The MachineApplication uses the Wriggly Wombat Soft HTTP client. + +Comment: + +To keep the two HTTP clients fully aligned, we will have to be ready to align our software updates for the AutoYummyBox with the software updates Wriggly Wombat Soft roles out. + +Needs: archrisk, dsn + +Tags: HttpClient diff --git a/src/main/resources/markdown/glossary.md b/src/doc/glossary.md similarity index 70% rename from src/main/resources/markdown/glossary.md rename to src/doc/glossary.md index cb72275..6797b46 100644 --- a/src/main/resources/markdown/glossary.md +++ b/src/doc/glossary.md @@ -1,3 +1,14 @@ + + # Glossary ## A @@ -18,4 +29,4 @@ Food vending machine with an internal 3D printer that creates dishes from [paste ### Paste Container -A *paste container* is a container holding the raw material ([paste](#paste)) for the 3D food printer. It has a built-in fill-level-sensor. \ No newline at end of file +A *paste container* is a container holding the raw material ([paste](#paste)) for the 3D food printer. It has a built-in fill-level-sensor. diff --git a/src/main/resources/markdown/introduction.md b/src/doc/introduction.md similarity index 69% rename from src/main/resources/markdown/introduction.md rename to src/doc/introduction.md index ebd3598..81954b7 100644 --- a/src/main/resources/markdown/introduction.md +++ b/src/doc/introduction.md @@ -1,3 +1,14 @@ + + # Introduction > OFT: start with a general introduction of your product / project here. Choose a detail level that allows first-time readers of your document whether or not the content is interesting for them. @@ -16,11 +27,42 @@ The target audience are persons involved with the construction of the system, te ### Notational Conventions -Requirements in this document are written in "Requirment enhanced Markdown format" which is the native specification format of [OpenFastTrace (OFT)](https://github.com/itsallcode/openfasttrace). If you want to learn more about this format please check the [OpenFastTrace User Guide](https://github.com/itsallcode/openfasttrace/blob/master/doc/user_guide.md). +Requirements in this document are written in "Requirement enhanced Markdown format" which is the native specification format of [OpenFastTrace (OFT)](https://github.com/itsallcode/openfasttrace). If you want to learn more about this format please check the [OpenFastTrace User Guide](https://github.com/itsallcode/openfasttrace/blob/master/doc/user_guide.md). Using this format allows you to scan the requirement chain using OFT to see if all requirements from the user-level [System Requirement Specification (SRS)](bibliography.md#srs) are covered. -The name part of the requirement IDs contains the prefix `ayb.` (for "AutoYummyBox") in order to avoid ID collisions when the specification is used in a wider scope cross-project. +The name part of the requirement IDs contains the prefix `ayb.` (for "AutoYummyBox") in order to avoid ID collisions when the specification is used in a wider scope cross-project. + +### Normative vs. Informative Passages + +This document contains two kinds of passages: normative and informative. + +Normative passages require the implementing party to adhere strictly to the letter of the specification. You can recognize normative parts by the fact that they are written as OFT specification items. Most importantly each has a unique requirement ID. + +The artifact type used for specification items in this document are: + +* `arch` -- regular architectural requirements +* `archrisk` -- technical risks +* `archdeci` -- top level design decisions + + Specification items also define in which artifact type they need to be covered. In this architecture document typically a Detailed Design (`dsn`). + +All passages that are not normative are informative, meaning that they contain background, explanations or references that help readers understand the document. They don't require coverage in other artifact types. + +### Language Conventions for Normative Passages + +This document uses natural language for normative passages. Specification items are formulated as if the contained requirement were already implemented. + +Example: + +> The FoodPrinter heats the paste nozzle up so that the applied paste has the target temperature defined in the recipe step currently executed. + +Notice that there are no artificial SHALL, SHOULD or MUSTs (like in documents adhering to [RFC 2119](bibliography.md#rfc2119) in this sentence and that it does not point to the future. + +This has two advantages: + +1. The text is more readable +2. It is true once the requirement is implemented ## Requirement Overview @@ -59,14 +101,14 @@ For a list of OFTAutoYummi's stakeholder contacts and their responsibilities ple ### Software Developers -The main audience for this software architecture are persons responsible for the design and implementation of the [building blocks](building_blocks.md). They have to base their detailed designs on the requirements stated in this document. +The main audience for this software architecture are persons responsible for the design and implementation of the [building blocks](building_block_view.md). They have to base their detailed designs on the requirements stated in this document. Recommended reading: * Introduction * [Context](context.md) * [Constraints](constraints.md) -* [Building Block View](building_blocks) +* [Building Block View](building_block_view.md) * [Runtime View](runtime.md) * [Concepts](concepts.md) * [Design Decisions](design_decisions.md) @@ -100,7 +142,7 @@ Recommended reading: Chapters that might also be interesting for this role: * [Context](context.md) -* [Building Block View](building_blocks) +* [Building Block View](building_block_view.md) * [Risks](risks.md) ### Testers @@ -112,7 +154,7 @@ Recommended reading: * Introduction * [Context](context.md) * [Constraints](constraints.md) -* [Building Block View](building_blocks) +* [Building Block View](building_block_view.md) * [Runtime View](runtime.md) * [Concepts](concepts.md) * [Quality Scenarios](quality_scenarios.md) @@ -125,5 +167,5 @@ Recommended reading: * Introduction * [Context](context.md) -* [Building Block View](building_blocks) -* [Deployment View](deployment) \ No newline at end of file +* [Building Block View](building_block_view.md) +* [Deployment View](deployment_view.md) diff --git a/src/doc/quality_scenarios.md b/src/doc/quality_scenarios.md new file mode 100644 index 0000000..8896bfd --- /dev/null +++ b/src/doc/quality_scenarios.md @@ -0,0 +1,91 @@ + + +# Quality Scenarios + +> OFT: Defining quality aspects of a system is often trickier than the structure, behavior and deployment. Quality scenarios are a way around this, because they focus on a "story" that gives you the context and describe how the system fulfills a quality aspect. + +> OFT: Since they are often user-centric, the bulk of your quality scenarios will be in your [System Requirement Specification SRS](bibliography.md#srs). When they are covered in this SwAD most coverage will result in requirements in other chapters. + +> OFT: What remains are mainly scenarios that hint tests from a technical perspective (like performance tests and their technical setup) and scenarios you want the designers of the components to cover. + +> OFT: You could argue to remove the chapter altogether from the SwAD and only cover it in the SRS. In the arc42 template the lines between user-level specification and system architecture are sometimes blurry though. + +> OFT: arc42 suggests to organize quality scenarios as leafs in a quality tree. + +![Quality tree](uml/class/cl_quality_tree.svg "Quality tree") + +> OFT: The quality tree above is an example without claiming to be complete or the only possible structure. For example some people might argue that scalability is not a subset of efficiency, while others would say the portability is just an aspect of maintainability. + +> OFT: Bottom line is that you have to find a tree that works for your project. + +> OFT: Also keep in mind that there is no strict need to cover branches in the tree for which you do not have user requirements. If your customer does not care for scalability of the system for example because load is too small to matter in the real world, then you should not invest time on this aspect. + +> OFT: What belongs here and what belongs into the other chapters? Does security go here, or safety? The answer unfortunately is: it depends. The distinction is easier to make if you think in terms of functional and non-functional requirements. + +> OFT: Security does have non-functional aspects and they are usually discussed in the [System Requirement Specification SRS](bibliography.md#srs). An example would be that you require private data to be encrypted so that given todays technology development the chances of breaking the encryption by brute force are negligible. On the other hand if you describe the algorithm for the same requirement in the SwAD that is most definitely a functional requirement. + +## Efficiency + +### Performance + +> OFT: We will take the performance branch of the tree as an example. First because it maps nicely to the top-level ["Quality Goals"](introduction.md#quality-goals) that we defined before, second there is a lot that can go wrong when defining them. + +> OFT: To determine what goes into the SwAD let's first discuss an example that belongs into the SRS. + +> OFT: `req~ayb.prepare-dish-within-three-minutes~1`: "After a Customer payed, AutoYummyBox takes a maximum of three minutes to prepare any dish and serve it in the output chute." + +> OFT: As you can see the scenario is user-centric and does not contain concrete technical aspects. It therefore is the right abstraction level for the SRS not the SwAD. + +> OFT: Now let make a scenario for the SwAD in as a contrast. + +#### Maximum Dish List Download Duration +`arch~ayb.maximum-dish-list-download-duration~1` + +Measured with a network connection of at least 1 MBit effective throughput and an end-to-end latency of no longer than 10 ms, the Cook component takes a maximum of 10 seconds to download the complete dish list including recipes from the CookingBook component in at least 95% of all cases. + +Rationale: + +In case the dish list is outdated when Customers order a dish, this is the maximum amount of time the dish list download is allowed to contribute to the overall preparation time. + +Covers: + +* `req~ayb.prepare-dish-within-three-minutes~1` + +Needs: dsn + +Tags: Cook, CookingBook + +> OFT: You can see that the description of this scenario is quite clunky. This is often the case with performance criteria for a number of reasons. + +> OFT: a) the environment influences your system in ways that you cannot control. In the example above the 95% rule tries to account for the fact that networks are unreliable. + +> OFT: b) some preconditions must be met in order for the quality aspect to be achievable (bandwidth, latency). + +> OFT: What this scenario does is that it outlines a test that developers and system testers should run against the system to see if the quality criteria is met. + +## Usability + +> OFT: One of the most important system aspects and one of the most neglected. Writing usability requirements requires a usability expert. Consider delegating this task to one if you aren't one yourself. + +> OFT: Again the bulk of the requirements will appear in the SRS: `req~ayb.average_time_to_find_out_how_to_order_a_dish~1`: "On average it takes untrained Users not longer than two minutes to order and pay a dish given only the instructions displayed on the AutoYummyBox." + +> OFT: It should be clear how to validate this quality criteria. Although in practice you will run out of untrained users quite fast. + +> OFT: Nevertheless this is not a technical quality scenario. If you are now thinking about building trace mechanisms into the system to get that kind of statistics: very good. But the resulting requirements are functional requirements, not quality scenarios. + +> OFT: Writing this I have a hard time coming up with an example of a usability scenario that is technical rather than user-centric -- which is probably the nature of usability. In conclusion this section is probably really better left to the SRS completely. + +### Resource Usage + +> OFT: ... + +> OFT: Again we are not going into more detail in this example. here diff --git a/src/doc/risks.md b/src/doc/risks.md new file mode 100644 index 0000000..200c7a5 --- /dev/null +++ b/src/doc/risks.md @@ -0,0 +1,73 @@ + + +# Risks + +> OFT: No one likes this chapter — and that is a clear sign that it is very important. Writing your risks down forces you to think about the choices you have. + +> OFT: Is there a chance to change the architecture to completely avoid the risk? + +> OFT: If not, what options do you have to mitigate the risks? + +> OFT: What will it cost you if a risk becomes reality? What does it cost you to prevent it? + +This chapter lists the technical and organizational risks that either influence architectural decisions or are caused by them. + +Risks are often the direct consequence of constraints, so please check the chapter ["Constraints"](constraints.md) for background information. + +> OFT: A question that we often were confronted with is whether it is a good idea to keep risk in the architecture document. After all most projects have a central risk list that also contains progress and status information. Collecting risks here means duplication to a certain extend. + +> OFT: On the other hand there are risks that you as an architect cannot ignore and it is good to keep them as close to your architecture as possible. After all they share the same life cycle. + +> OFT: What worked best for us so far is detailing the risks where the arise, i.e. in the [System Requirement Specification (SRS)](bibliography.md#srs), in the architecture and the detailed designs. We then only referenced them in the project's global risk list so that we could do the task planning and progress tracking outside of the specification documents. + +> OFT: If there are risks that cannot be mitigated, we strongly recommend you bring them to the attention of project management. Project management must then decide on whether to approve additional efforts and costs to remove the risk or to accept the risk and the associated responsibility. Your job as a professional architect is to outline the options project management together with the consequences. + +## Security Risks + +### Unpatched HTTP Client Vulnerabilities +`archrisk~ayb.unpatched-http-client-vulnerabilities` + +The guaranteed time-to-fix for known vulnerabilities in the Wriggly Wombat Soft HTTP client we are using in the [MachineApplication](components/MachineApplication.md) is two weeks counted from the day a vulnerability is first reported. Worst case this means that our product suffers from an unpatched vulnerability for the whole two weeks. + +> OFT: This admittedly constructed example demonstrates why project members in general and project management in particular tend to avoid thinking too much about risks. This risk is a potential show-stopper for the whole product. As a professional architect you have to make the risk transparent. Project management needs to calculate and decide whether it is in total cheaper to accept the risk with all consequences or to spend time, effort and money to mitigate or remove it. + +> OFT: The example risk was picked to show that there are risks that cannot be fully removed. No matter what you do, the time-to-fix will never be zero, especially when an external supplier is involved. + +Consequences: + +* Depending on the severity of the vulnerability consequences range from remote Denial-of-Service (DoS) over data leakage to remote infection of the AutoYummyBox with malicious code. +* Since the HTTP client is also an integral part of the [CreditCardReader](components/CreditCardReader.md) the worst thing that could happen is leakage of our customers' credit card information. + +The following mitigations are possible: + +1. Raise the awareness of critical vulnerabilities at our supplier (case-by-case) + + We will do this but there is no guarantee this will speed up the fix. + +1. Offer a patch (case-by-case) + + We have the source code but we are neither allowed nor able to exchange the HTTP client in the [CreditCardReader](components/CreditCardReader.md). + Also it is questionable whether we are faster to create a patch than the original maker of the HTTP client. + +1. Compartmentalize the vulnerability in our components (case-by-case) + + We will do this as a last resort for critical vulnerabilities if we come to the conclusion that the security risk can be mitigated with reasonable effort. + Also keep in mind that workarounds often create new attack surfaces. + We have no chance to compartmentalize the vulnerability inside of the CreditCardReader. + +Comment: + +This risk was accepted by project management on 2018-03-02. + +Covers: + +* `arch~ayb.machineapplication-uses-wombathttpclient~1` diff --git a/src/doc/runtime_view.md b/src/doc/runtime_view.md new file mode 100644 index 0000000..11a704b --- /dev/null +++ b/src/doc/runtime_view.md @@ -0,0 +1,35 @@ + + +# Runtime View + +This chapter describes the system behavior at runtime. + +> OFT: This chapter will by far contain the most specification items of the whole document. After all system behavior is what counts most in your customers' eyes. + +> OFT: We recommend that you structure this chapter according to the high-level features that you defined in your [System Requirement Specification (SRS)](bibliography.md#srs). + +> OFT: Since the sections in this chapter tend to get quite large we also recommend that you split up the chapter into separate files, one for each feature. + +> OFT: When designing features keep in mind that there should be not more that fit on a single page product sheet — after you subtracted the space for images and general product description. As a rule of thumb three to ten top-level features are a good number. + +* [Ordering Dishes](runtime/ordering_dishes.md) +* [Preparing Dishes](runtime/preparing_dishes.md) +* [Paying With Credit Card](runtime/paying_with_credit_card.md) +* Paying With VirtuCoinBuddy +* Cleaning AutoYummyBoxes +* Keeping the boxes well-stocked +* Monitoring the boxes +* ... + +> OFT: We stop the feature enumeration at this point, since we are sure you got the concept. + +> OFT: From our experience it helps a lot if you provide behavioral UML diagrams in this chapter. PlantUML has offers everything you need: [sequence](http://plantuml.com/sequence-diagram), [activity](http://plantuml.com/activity-diagram-beta), [state](http://plantuml.com/state-diagram),[timing](http://plantuml.com/timing-diagram) diff --git a/src/doc/runtime_view/ordering_dishes.md b/src/doc/runtime_view/ordering_dishes.md new file mode 100644 index 0000000..6aee56c --- /dev/null +++ b/src/doc/runtime_view/ordering_dishes.md @@ -0,0 +1,79 @@ + + +## Ordering Dishes + +> OFT: Readers are lazy, so it is best not to assume that they read the feature description in the SRS. You should at least + +This section explains how [Customers](../introduction#customer) order dishes at the AutoYummyBox. This includes finding out which dishes AutoYummiBox can [prepare](preparing_dishes.md) given the available [pastes](../glossary.md#paste) and their remaining amounts. + +> OFT: Next we recommend that you outline what happens in a behavioral chart. If unsure which one to pick, start with a sequence chart. + +> OFT: Which level of granularity should you choose here? Since we are writing a Software Architectural Design (SwAD) document and assume that development teams are responsible for the detailed design of the sub-level-1 components, you should show interactions between the components here. Going deeper unnecessarily takes away design freedom from the development teams. + +> OFT: The diagram below has three different responsible parties: the Customer (who does not have to implement anything), the MachineApplication which we assume is in the responsibility of a dedicated development team and the PasteContainer which is a delivery you get from a supplier. Your job as a system architect is to make sure all teams have the necessary information to get their parts running together as one system in the end. + +![Ordering dishes](uml/sequence/seq_ordering_dishes.svg "Ordering dishes") + +> OFT: For comparison here the detailed design that shows the inner workings of the MachineApplication. + +
+![Ordering dishes -- detailed design](uml/sequence/seq_ordering_dishes_detailed_design.svg "Ordering dishes -- detailed design") +
+ +> OFT: As you can see there is a lot of internal details that does not necessarily need to appear in the SwAD. + +> OFT: Next we are going to list the runtime requirements of the feature. If you are not sure about the level of granularity, simply use the diagram and write one requirement for each message and/or loop. + +### User Requests Dish List +`arch~ayb.user-requests-dish-list~1` + +The MachineApplication allows users to request a list of currently available dishes. + +Covers: + +* `req~ayb.dish-list~1` + +Needs: dsn + +Tags: MachineApplication + +### MachineApplication Creates Paste Inventory +`arch~ayb.machineapplication_creates_inventory~1` + +The MachineApplication queries all installed PasteContainers for paste type and fill grade to create a paste inventory. + +Covers: + +* `req~ayb.dish-list~1` + +Needs: dsn + +Tags: MachineApplication + +> OFT: The above requirement example is one that often leads to debates, especially with quality engineers and hardcore requirement engineers. They will argue that it is not atomic and instead consists of at least three different requirements: A) querying paste type, B) querying fill grade, C) creating the inventory + +> OFT: The painful truth is that if a requirement is atomic a matter of perspective and more importantly whether strict adherence to "everything is atomic" is even useful. + +> OFT: Our colleague Poldi once told me that he draws the line at splitting requirements to the point where they are likely to be individually changed. This advice turned out to be a perfect compromise between detail level and effort. + +### MachineApplication Calculates Available Dishes +`arch~ayb.machine-application-calculates-available-dishes~1` + +The Machine Application compares all internally kept recipes with the currently available paste types and amounts to create a list of currently available dishes. + +Covers: + +* `req~ayb.dish-list~1` + +Needs: dsn + +Tags: MachineApplication diff --git a/src/doc/runtime_view/paying_with_credit_card.md b/src/doc/runtime_view/paying_with_credit_card.md new file mode 100644 index 0000000..85074b2 --- /dev/null +++ b/src/doc/runtime_view/paying_with_credit_card.md @@ -0,0 +1,14 @@ + + +## Paying With Credit Card + +> OFT: empty on purpose in this example document. \ No newline at end of file diff --git a/src/doc/runtime_view/preparing_dishes.md b/src/doc/runtime_view/preparing_dishes.md new file mode 100644 index 0000000..b35bc0f --- /dev/null +++ b/src/doc/runtime_view/preparing_dishes.md @@ -0,0 +1,14 @@ + + +## Preparing Dishes + +> OFT: empty on purpose in this example document. \ No newline at end of file diff --git a/src/main/resources/markdown/solution_strategy.md b/src/doc/solution_strategy.md similarity index 84% rename from src/main/resources/markdown/solution_strategy.md rename to src/doc/solution_strategy.md index 1808738..ab2b5ac 100644 --- a/src/main/resources/markdown/solution_strategy.md +++ b/src/doc/solution_strategy.md @@ -1,3 +1,14 @@ + + # Solution Strategy > OFT: This chapter is a tricky one. The original arc42 template states that you should outline your main architectural decisions here, for example how you plan to reach your quality goals. @@ -10,4 +21,4 @@ > OFT: Third the job of a system or software architecture is to keep as many decision options open for as long as possible. If you draw the lines to early and to strictly you are removing freedom from the designers that could have given you a better overall solution. -> OFT: Our recommendation is to remove this chapter unless you have uncountermandable decisions that everyone needs to get over before starting to work on a solution. A prime example would be if your company enforces a strict book of standards for technical systems that does not allow for solutions outside of that box. In this case you can either deal with it and find the best remaining solution within the confines of these regulations, spend your time trying to get the book of standards adapted to your needs or leave for a company that understands the necessity of picking the right tool for the job. \ No newline at end of file +> OFT: Our recommendation is to remove this chapter unless you have uncountermandable decisions that everyone needs to get over before starting to work on a solution. A prime example would be if your company enforces a strict book of standards for technical systems that does not allow for solutions outside of that box. In this case you can either deal with it and find the best remaining solution within the confines of these regulations, spend your time trying to get the book of standards adapted to your needs or leave for a company that understands the necessity of picking the right tool for the job. diff --git a/src/license/cc-by-4.0/header.txt b/src/license/cc-by-4.0/header.txt deleted file mode 100644 index f7fa4f1..0000000 --- a/src/license/cc-by-4.0/header.txt +++ /dev/null @@ -1,9 +0,0 @@ -(c) This work is based on the arc42 architecture template . -Created by Dr. Peter Hruschka & Dr. Gernot Starke. - -(c) Examples, explanations and extensions from itsallcode.org (https://itsallcode.org). -Created by Sebastian Bär and Christoph Pirkl. - -OpenFastTrace architecture template is licensed under a Creative Commons Attribution 4.0 International License. - -You should have received a copy of the license along with this work. If not, see http://creativecommons.org/licenses/by/4.0/ \ No newline at end of file diff --git a/src/license/cc-by-4.0/license.txt b/src/license/cc-by-4.0/license.txt deleted file mode 100644 index 5de6479..0000000 --- a/src/license/cc-by-4.0/license.txt +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2018 It's all code - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/src/license/cc-by-sa-4.0/header.txt b/src/license/cc-by-sa-4.0/header.txt new file mode 100644 index 0000000..12ac2c8 --- /dev/null +++ b/src/license/cc-by-sa-4.0/header.txt @@ -0,0 +1,2 @@ +This document is based on https://arc42.org by Dr. G. Starke & Dr. P. Hruschka +with modifications and additions from itsallcode.org, licensed under CC-BY-SA 4.0 \ No newline at end of file diff --git a/src/license/cc-by-sa-4.0/license.txt b/src/license/cc-by-sa-4.0/license.txt new file mode 100644 index 0000000..16de504 --- /dev/null +++ b/src/license/cc-by-sa-4.0/license.txt @@ -0,0 +1,427 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + + including for purposes of Section 3(b); and + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. \ No newline at end of file diff --git a/src/license/licenses.properties b/src/license/licenses.properties new file mode 100644 index 0000000..f917b36 --- /dev/null +++ b/src/license/licenses.properties @@ -0,0 +1 @@ +cc-by-sa-4.0=Creative Commons Attribution-ShareAlike 4.0 International \ No newline at end of file diff --git a/src/main/lua/link_converter.lua b/src/main/lua/link_converter.lua new file mode 100644 index 0000000..ecd1699 --- /dev/null +++ b/src/main/lua/link_converter.lua @@ -0,0 +1,27 @@ +local function is_html (format) + return format == 'html' or format == 'html4' or format == 'html5' +end + +function Link(link) + if is_html then + target = link.target + if string.find(target, "^https?://") then + -- leave links to project-external resources alone + else + hashTagPos = string.find(target, "#") + if hashTagPos then + target = string.sub(target, hashTagPos) + else + if string.find(target, "%.md$") or string.find(target, "%.markdown") then + target = string.gsub(target, "(.*)[/\\]", "") + target = string.gsub(target, "[_ ]", "-") + target = string.gsub(target, "%.md$", "") + target = string.gsub(target, "%.markdown$", "") + target = "#" .. target + end + end + end + link.target = target + end + return link +end \ No newline at end of file diff --git a/src/main/lua/pdf_image_path_converter.lua b/src/main/lua/pdf_image_path_converter.lua new file mode 100644 index 0000000..65be392 --- /dev/null +++ b/src/main/lua/pdf_image_path_converter.lua @@ -0,0 +1,8 @@ +function Image(image) + src = image.src + + src = "../../target/" .. src + image.src = src + + return image +end diff --git a/src/main/lua/replace_with_metadata.lua b/src/main/lua/replace_with_metadata.lua new file mode 100644 index 0000000..31f3631 --- /dev/null +++ b/src/main/lua/replace_with_metadata.lua @@ -0,0 +1,19 @@ +local vars = {} + +function get_vars(meta) + for k, v in pairs(meta) do + if v then + vars["$" .. k .. "$"] = v + end + end +end + +function replace(element) + if vars[element.text] then + return pandoc.Span(vars[element.text]) + else + return element + end +end + +return {{Meta = get_vars}, {Str = replace}} \ No newline at end of file diff --git a/src/main/resources/html/header.html b/src/main/resources/html/header.html deleted file mode 100644 index 5e9f982..0000000 --- a/src/main/resources/html/header.html +++ /dev/null @@ -1,7 +0,0 @@ - - - - titleToken - - - \ No newline at end of file diff --git a/src/main/resources/markdown/bibliography.md b/src/main/resources/markdown/bibliography.md deleted file mode 100644 index 51c1f8d..0000000 --- a/src/main/resources/markdown/bibliography.md +++ /dev/null @@ -1,21 +0,0 @@ -# Bibliography - -> OFT: The bibliography provides an overview over all external document and web site sources that you used when creating this architecture. Make sure to credit the authors. - -> OFT: One of the most important things is that you should add links to the original sources so that readers can find the information quickly. Keep in mind that not all readers have access to all the systems you have access to. A hint on how to apply for access is a nice gesture. - -## Specifications - -* SRS: "OFTAutoYummi - System Requirement Specification", *S. Baer, Chr. Pirkl*, 2018, [itsallcode.org](https://itsallcode.org) - -## Standards - -> OFT: List here any standards that you refer to in your documents. For example IETF RFCs or ISO standards. - -## Documents - -* OAY-ORGA: "OFTAutoYummi Organization", *J. Doe*, 2018 - -## Web Sites - -> When your refer to web sites remember to add the date when you accessed them so that readers are not disappointed when they find out the content you referred to is gone. \ No newline at end of file diff --git a/src/main/resources/markdown/building_blocks/MachineApplication.md b/src/main/resources/markdown/building_blocks/MachineApplication.md deleted file mode 100644 index f156845..0000000 --- a/src/main/resources/markdown/building_blocks/MachineApplication.md +++ /dev/null @@ -1 +0,0 @@ -# MachineApplication diff --git a/src/main/resources/uml/actors/Customer.plantuml b/src/main/resources/uml/actors/Customer.plantuml deleted file mode 100644 index 75edd3a..0000000 --- a/src/main/resources/uml/actors/Customer.plantuml +++ /dev/null @@ -1,3 +0,0 @@ -@startuml -actor "Customer" <> as Customer -@enduml \ No newline at end of file diff --git a/src/main/resources/uml/components/MachineApplication.plantuml b/src/main/resources/uml/components/MachineApplication.plantuml deleted file mode 100644 index afcf038..0000000 --- a/src/main/resources/uml/components/MachineApplication.plantuml +++ /dev/null @@ -1,3 +0,0 @@ -@startuml -component MachineApplication [[../../building_blocks/MachineApplication.html]] -@enduml \ No newline at end of file diff --git a/src/main/resources/uml/diagrams/clean.skin b/src/main/resources/uml/diagrams/clean.skin deleted file mode 100644 index e2b5641..0000000 --- a/src/main/resources/uml/diagrams/clean.skin +++ /dev/null @@ -1,7 +0,0 @@ -@startuml -skinparam monochrome true -skinparam style strictuml - -hide empty methods -hide empty attributes -@enduml \ No newline at end of file diff --git a/src/uml/actors/Customer.plantuml b/src/uml/actors/Customer.plantuml new file mode 100644 index 0000000..9d7b597 --- /dev/null +++ b/src/uml/actors/Customer.plantuml @@ -0,0 +1 @@ +actor "Customer" as Customer <> \ No newline at end of file diff --git a/src/main/resources/uml/actors/MachineMaintainer.plantuml b/src/uml/actors/MachineMaintainer.plantuml similarity index 100% rename from src/main/resources/uml/actors/MachineMaintainer.plantuml rename to src/uml/actors/MachineMaintainer.plantuml diff --git a/src/main/resources/uml/actors/Technician.plantuml b/src/uml/actors/Technician.plantuml similarity index 100% rename from src/main/resources/uml/actors/Technician.plantuml rename to src/uml/actors/Technician.plantuml diff --git a/src/main/resources/uml/components/AAProvider.plantuml b/src/uml/components/AAProvider.plantuml similarity index 100% rename from src/main/resources/uml/components/AAProvider.plantuml rename to src/uml/components/AAProvider.plantuml diff --git a/src/main/resources/uml/components/AutoYummyBox.plantuml b/src/uml/components/AutoYummyBox.plantuml similarity index 100% rename from src/main/resources/uml/components/AutoYummyBox.plantuml rename to src/uml/components/AutoYummyBox.plantuml diff --git a/src/uml/components/MachineApplication.plantuml b/src/uml/components/MachineApplication.plantuml new file mode 100644 index 0000000..93d7bd9 --- /dev/null +++ b/src/uml/components/MachineApplication.plantuml @@ -0,0 +1,3 @@ +@startuml +component MachineApplication [[../../building_block_view/MachineApplication.html]] +@enduml \ No newline at end of file diff --git a/src/main/resources/uml/components/MachineManager.plantuml b/src/uml/components/MachineManager.plantuml similarity index 100% rename from src/main/resources/uml/components/MachineManager.plantuml rename to src/uml/components/MachineManager.plantuml diff --git a/src/main/resources/uml/components/MachineMasterDataProvider.plantuml b/src/uml/components/MachineMasterDataProvider.plantuml similarity index 100% rename from src/main/resources/uml/components/MachineMasterDataProvider.plantuml rename to src/uml/components/MachineMasterDataProvider.plantuml diff --git a/src/main/resources/uml/components/PasteFactoryService.plantuml b/src/uml/components/PasteFactoryService.plantuml similarity index 100% rename from src/main/resources/uml/components/PasteFactoryService.plantuml rename to src/uml/components/PasteFactoryService.plantuml diff --git a/src/main/resources/uml/components/PaymentProvider.plantuml b/src/uml/components/PaymentProvider.plantuml similarity index 100% rename from src/main/resources/uml/components/PaymentProvider.plantuml rename to src/uml/components/PaymentProvider.plantuml diff --git a/src/main/resources/uml/components/PaymentProviderAdapter.plantuml b/src/uml/components/PaymentProviderAdapter.plantuml similarity index 100% rename from src/main/resources/uml/components/PaymentProviderAdapter.plantuml rename to src/uml/components/PaymentProviderAdapter.plantuml diff --git a/src/uml/components/foodprinter/FoodPrinter.plantuml b/src/uml/components/foodprinter/FoodPrinter.plantuml new file mode 100644 index 0000000..940c308 --- /dev/null +++ b/src/uml/components/foodprinter/FoodPrinter.plantuml @@ -0,0 +1,3 @@ +@startuml +component FoodPrinter <> +@enduml \ No newline at end of file diff --git a/src/uml/components/foodprinter/FoodPrinterController.plantuml b/src/uml/components/foodprinter/FoodPrinterController.plantuml new file mode 100644 index 0000000..74e0296 --- /dev/null +++ b/src/uml/components/foodprinter/FoodPrinterController.plantuml @@ -0,0 +1,3 @@ +@startuml +component FoodPrinterController +@enduml \ No newline at end of file diff --git a/src/main/resources/uml/components/PasteContainer.plantuml b/src/uml/components/foodprinter/PasteContainer.plantuml similarity index 100% rename from src/main/resources/uml/components/PasteContainer.plantuml rename to src/uml/components/foodprinter/PasteContainer.plantuml diff --git a/src/uml/components/foodprinter/PasteContainerConnector.plantuml b/src/uml/components/foodprinter/PasteContainerConnector.plantuml new file mode 100644 index 0000000..0537a0d --- /dev/null +++ b/src/uml/components/foodprinter/PasteContainerConnector.plantuml @@ -0,0 +1,3 @@ +@startuml +component PasteContainerConnector +@enduml \ No newline at end of file diff --git a/src/uml/components/http/HttpClient.plantuml b/src/uml/components/http/HttpClient.plantuml new file mode 100644 index 0000000..4383e05 --- /dev/null +++ b/src/uml/components/http/HttpClient.plantuml @@ -0,0 +1,3 @@ +@startuml +component HttpClient <> +@enduml \ No newline at end of file diff --git a/src/uml/components/payment/CreditCardConnector.plantuml b/src/uml/components/payment/CreditCardConnector.plantuml new file mode 100644 index 0000000..c4060b7 --- /dev/null +++ b/src/uml/components/payment/CreditCardConnector.plantuml @@ -0,0 +1,3 @@ +@startuml +component CreditCardConnector +@enduml \ No newline at end of file diff --git a/src/uml/components/payment/CreditCardReader.plantuml b/src/uml/components/payment/CreditCardReader.plantuml new file mode 100644 index 0000000..63c8d89 --- /dev/null +++ b/src/uml/components/payment/CreditCardReader.plantuml @@ -0,0 +1,3 @@ +@startuml +component CreditCardReader <> <> +@enduml \ No newline at end of file diff --git a/src/uml/components/payment/PaymentClient.plantuml b/src/uml/components/payment/PaymentClient.plantuml new file mode 100644 index 0000000..4de141a --- /dev/null +++ b/src/uml/components/payment/PaymentClient.plantuml @@ -0,0 +1,3 @@ +@startuml +component PaymentClient <> +@enduml \ No newline at end of file diff --git a/src/uml/components/payment/PaymentHandler.plantuml b/src/uml/components/payment/PaymentHandler.plantuml new file mode 100644 index 0000000..5762126 --- /dev/null +++ b/src/uml/components/payment/PaymentHandler.plantuml @@ -0,0 +1,3 @@ +@startuml +component PaymentHandler +@enduml \ No newline at end of file diff --git a/src/uml/components/vendingmachine/Cook.plantuml b/src/uml/components/vendingmachine/Cook.plantuml new file mode 100644 index 0000000..8517c7f --- /dev/null +++ b/src/uml/components/vendingmachine/Cook.plantuml @@ -0,0 +1,3 @@ +@startuml +component Cook +@enduml \ No newline at end of file diff --git a/src/uml/components/vendingmachine/MachineBackendConnector.plantuml b/src/uml/components/vendingmachine/MachineBackendConnector.plantuml new file mode 100644 index 0000000..b2ce01a --- /dev/null +++ b/src/uml/components/vendingmachine/MachineBackendConnector.plantuml @@ -0,0 +1,3 @@ +@startuml +component MachineBackendConnector +@enduml \ No newline at end of file diff --git a/src/uml/components/vendingmachine/MachineController.plantuml b/src/uml/components/vendingmachine/MachineController.plantuml new file mode 100644 index 0000000..8da8801 --- /dev/null +++ b/src/uml/components/vendingmachine/MachineController.plantuml @@ -0,0 +1,3 @@ +@startuml +component MachineController +@enduml \ No newline at end of file diff --git a/src/uml/components/vendingmachine/UserInterface.plantuml b/src/uml/components/vendingmachine/UserInterface.plantuml new file mode 100644 index 0000000..a616ba2 --- /dev/null +++ b/src/uml/components/vendingmachine/UserInterface.plantuml @@ -0,0 +1,3 @@ +@startuml +component UserInterface +@enduml \ No newline at end of file diff --git a/src/uml/diagrams/class/cl_dishes.plantuml b/src/uml/diagrams/class/cl_dishes.plantuml new file mode 100644 index 0000000..c7746ba --- /dev/null +++ b/src/uml/diagrams/class/cl_dishes.plantuml @@ -0,0 +1,56 @@ +@startuml +!include ../clean.skin + +class Menu + +class Dish { + # name : String + # price : MonetaryAmount +} + +class Recipe + +class Step { + # ingredientAmount : float + # targetTemperature : float +} + +class Ingredient { + # name : String +} + +class 3DShape + +class Paste { + # productNumber : String +} + +class IngredientDeclaration { + # name : String + # allergen : boolean +} + +class NutritionFact { + # type : NutritionFactType + # amountPercent : float +} + +enum NutritionFactType <> { + FAT + SUGAR + PROTEIN + VITAMIN_A + VITAMIN_B + VITAMIN_C +} + +Menu *-r- "1..*" Dish : avaiblable\ndishes +Dish --> Recipe : prepared according to +Recipe *-- "1..*" Step +Step -l-> 3DShape +Step -r-> Ingredient +Ingredient -d-> "1..*" Paste : compatible +Paste -l-> "*" IngredientDeclaration : declare +Paste *-d- "*" NutritionFact +NutritionFact -l-> NutritionFactType +@enduml \ No newline at end of file diff --git a/src/uml/diagrams/class/cl_quality_tree.plantuml b/src/uml/diagrams/class/cl_quality_tree.plantuml new file mode 100644 index 0000000..3e7e429 --- /dev/null +++ b/src/uml/diagrams/class/cl_quality_tree.plantuml @@ -0,0 +1,17 @@ +@startuml +!include ../clean.skin +left to right direction + +class Utility + +Utility --> Usability +Utility --> Efficiency +Utility --> Reliability +Utility --> Maintainability +Utility --> Portability +Efficiency --> Performance +Efficiency --> "Resource Usage" +Efficiency --> Scalability +Reliability --> Availability + +@enduml \ No newline at end of file diff --git a/src/uml/diagrams/clean.skin b/src/uml/diagrams/clean.skin new file mode 100644 index 0000000..6a2c92b --- /dev/null +++ b/src/uml/diagrams/clean.skin @@ -0,0 +1,13 @@ +@startuml +skinparam style strictuml +skinparam monochrome true +skinparam Component { + FontColor<> DimGrey + StereotypeFontColor<> DimGrey + BackgroundColor<> #fcfcfc +} +skinparam shadowing false + +hide empty methods +hide empty attributes +@enduml \ No newline at end of file diff --git a/src/uml/diagrams/component/comp.skin b/src/uml/diagrams/component/comp.skin new file mode 100644 index 0000000..751afd5 --- /dev/null +++ b/src/uml/diagrams/component/comp.skin @@ -0,0 +1,2 @@ +!include ../clean.skin +!pragma horizontalLineBetweenDifferentPackageAllowed \ No newline at end of file diff --git a/src/main/resources/uml/diagrams/component/comp_circular_dependencies.plantuml b/src/uml/diagrams/component/comp_circular_dependencies.plantuml similarity index 84% rename from src/main/resources/uml/diagrams/component/comp_circular_dependencies.plantuml rename to src/uml/diagrams/component/comp_circular_dependencies.plantuml index c9a6438..3887f50 100644 --- a/src/main/resources/uml/diagrams/component/comp_circular_dependencies.plantuml +++ b/src/uml/diagrams/component/comp_circular_dependencies.plantuml @@ -1,5 +1,5 @@ @startuml -!include ../clean.skin +!include comp.skin component A component B diff --git a/src/main/resources/uml/diagrams/component/comp_context.plantuml b/src/uml/diagrams/component/comp_context.plantuml similarity index 96% rename from src/main/resources/uml/diagrams/component/comp_context.plantuml rename to src/uml/diagrams/component/comp_context.plantuml index 797f400..de33130 100644 --- a/src/main/resources/uml/diagrams/component/comp_context.plantuml +++ b/src/uml/diagrams/component/comp_context.plantuml @@ -1,5 +1,5 @@ @startuml -!include ../clean.skin +!include comp.skin !include ../../actors/Customer.plantuml !include ../../actors/MachineMaintainer.plantuml diff --git a/src/uml/diagrams/component/comp_machine_application.plantuml b/src/uml/diagrams/component/comp_machine_application.plantuml new file mode 100644 index 0000000..86e84a8 --- /dev/null +++ b/src/uml/diagrams/component/comp_machine_application.plantuml @@ -0,0 +1,62 @@ +@startuml +!include comp.skin + +package org.itsallcode { + package vendingmachine { + !include ../../components/vendingmachine/MachineController.plantuml + !include ../../components/vendingmachine/UserInterface.plantuml + !include ../../components/vendingmachine/MachineBackendConnector.plantuml + !include ../../components/vendingmachine/Cook.plantuml + MachineController -r-> MachineBackendConnector + MachineController -r-> Cook + Cook -r-> MachineBackendConnector + } + + package foodprinter { + !include ../../components/foodprinter/PasteContainerConnector.plantuml + !include ../../components/foodprinter/FoodPrinterController.plantuml + !include ../../interfaces/foodprinter/FoodPrinterIF.plantuml + !include ../../interfaces/foodprinter/PasteContainerIF.plantuml + FoodPrinterController -u-( FoodPrinterIF + PasteContainerConnector -u-( PasteContainerIF + } + + package payment { + !include ../../components/payment/CreditCardConnector.plantuml + !include ../../components/payment/PaymentHandler.plantuml + PaymentHandler -l-> CreditCardConnector + } + + UserInterface -r-> MachineController + MachineController -u-> FoodPrinterController + MachineController -u-> PasteContainerConnector + MachineController -d-> PaymentHandler +} + +!include ../../components/http/HttpClient.plantuml +!include ../../components/foodprinter/PasteContainer.plantuml +!include ../../components/foodprinter/FoodPrinter.plantuml +component CreditCardReader <> <> { + component "WrigglyWombatHttpClient" <> as WombatHttpClient +} +note "We keep the two embedded\nHTTP client instances aligned." as N1 + +N1 .r. HttpClient +N1 .l. WombatHttpClient + +!include ../../components/payment/PaymentClient.plantuml +!include ../../interfaces/payment/CreditCardReaderIF.plantuml +!include ../../interfaces/payment/PaymentClientIF.plantuml +!include ../../interfaces/http/HttpClientIF.plantuml + +FoodPrinter -d- FoodPrinterIF +PasteContainer -d- PasteContainerIF +CreditCardReader -u- CreditCardReaderIF +PaymentClient -l- PaymentClientIF +HttpClient -u- HttpClientIF +CreditCardConnector -d-( CreditCardReaderIF +PaymentHandler -d-( PaymentClientIF +PaymentClient -r-( HttpClientIF +MachineBackendConnector -d-( HttpClientIF + +@enduml \ No newline at end of file diff --git a/src/main/resources/uml/diagrams/component/comp_overview.plantuml b/src/uml/diagrams/component/comp_overview.plantuml similarity index 90% rename from src/main/resources/uml/diagrams/component/comp_overview.plantuml rename to src/uml/diagrams/component/comp_overview.plantuml index 37894f0..2065a7f 100644 --- a/src/main/resources/uml/diagrams/component/comp_overview.plantuml +++ b/src/uml/diagrams/component/comp_overview.plantuml @@ -1,7 +1,7 @@ @startuml -!include ../clean.skin +!include comp.skin -!include ../../components/PasteContainer.plantuml +!include ../../components/foodprinter/PasteContainer.plantuml !include ../../components/AutoYummyBox.plantuml !include ../../components/MachineApplication.plantuml !include ../../components/PaymentProvider.plantuml diff --git a/src/main/resources/uml/diagrams/component/comp_units_components_and_compositions.plantuml b/src/uml/diagrams/component/comp_units_components_and_compositions.plantuml similarity index 95% rename from src/main/resources/uml/diagrams/component/comp_units_components_and_compositions.plantuml rename to src/uml/diagrams/component/comp_units_components_and_compositions.plantuml index d66159b..10acc83 100644 --- a/src/main/resources/uml/diagrams/component/comp_units_components_and_compositions.plantuml +++ b/src/uml/diagrams/component/comp_units_components_and_compositions.plantuml @@ -1,5 +1,5 @@ @startuml -!include ../clean.skin +!include comp.skin skinparam linetype ortho component "Software Unit" as Unit diff --git a/src/uml/diagrams/deployment/depl.skin b/src/uml/diagrams/deployment/depl.skin new file mode 100644 index 0000000..4f0cac6 --- /dev/null +++ b/src/uml/diagrams/deployment/depl.skin @@ -0,0 +1,3 @@ +!include ../clean.skin +skinparam CloudBorderColor LightGrey +skinparam CloudFontColor Grey \ No newline at end of file diff --git a/src/uml/diagrams/deployment/depl_autoyummybox.plantuml b/src/uml/diagrams/deployment/depl_autoyummybox.plantuml new file mode 100644 index 0000000..90ea4a7 --- /dev/null +++ b/src/uml/diagrams/deployment/depl_autoyummybox.plantuml @@ -0,0 +1,64 @@ +@startuml +!include depl.skin +'skinparam linetype ortho + +node CreditCardReaderNode <><> +node FoodPrinterNode <> +node PasteContainerNode <><> + +node EmbeddedARMBoard <> { + + node "BoardExentsion" { + node WirelessModem <> + node DSLModem <> + 'DSLModem -[hidden]d- WirelessModem + } + + node EmbeddedRTOS <> { + !include ../../components/vendingmachine/MachineController.plantuml + !include ../../components/vendingmachine/UserInterface.plantuml + !include ../../components/vendingmachine/MachineBackendConnector.plantuml + !include ../../components/vendingmachine/Cook.plantuml + !include ../../components/foodprinter/PasteContainerConnector.plantuml + !include ../../components/foodprinter/FoodPrinterController.plantuml + !include ../../components/payment/CreditCardConnector.plantuml + together { + !include ../../components/http/HttpClient.plantuml + !include ../../components/payment/PaymentClient.plantuml + } + !include ../../components/payment/PaymentHandler.plantuml + + database EmbeddedDB <> { + artifact Recipe + artifact Payment + artifact PasteInventory + } + + MachineController -r- MachineBackendConnector + MachineController -d- Cook + MachineController -d- PasteInventory + MachineController -u- FoodPrinterController + MachineController -u- PasteContainerConnector + MachineController -r- PaymentHandler + Cook -l- MachineBackendConnector + Cook -l- Recipe + PaymentHandler -u- CreditCardConnector + PaymentHandler -d- Payment + PaymentHandler -r- PaymentClient + UserInterface -r- MachineController + MachineBackendConnector -- HttpClient + PaymentClient -r- HttpClient + } + + + HttpClient -d- "2" WirelessModem : SPI + HttpClient -d- "2" DSLModem : SPI + +} + + +FoodPrinterController -u- FoodPrinterNode : Ethernet +PasteContainerConnector -u- "15" PasteContainerNode : I²C +CreditCardConnector -u- CreditCardReaderNode : SPI + +@enduml \ No newline at end of file diff --git a/src/uml/diagrams/deployment/depl_overview.plantuml b/src/uml/diagrams/deployment/depl_overview.plantuml new file mode 100644 index 0000000..f532017 --- /dev/null +++ b/src/uml/diagrams/deployment/depl_overview.plantuml @@ -0,0 +1,20 @@ +@startuml +!include depl.skin + +!include ../../nodes/AutoYummyBox.plantuml +!include ../../nodes/PasteFactory.plantuml + +cloud "DataCenter" { + node Backend +} + + +!include ../../nodes/CreditCardProvider.plantuml +!include ../../nodes/VirtuCoinBuddyProvider.plantuml + +AutoYummyBoxNode "*" -d- Backend +AutoYummyBoxNode "*" -d- "2..*" CreditCardProviderNode +Backend "*" -r- "2..*" CreditCardProviderNode : " " +Backend "*" -l- "2..*" VirtuCoinBuddyProviderNode : " " +Backend "*" -d- "2..*" PasteFactoryNode +@enduml \ No newline at end of file diff --git a/src/uml/diagrams/sequence/seq.skin b/src/uml/diagrams/sequence/seq.skin new file mode 100644 index 0000000..bf59577 --- /dev/null +++ b/src/uml/diagrams/sequence/seq.skin @@ -0,0 +1,5 @@ +!include ../clean.skin +hide footbox +skinparam ParticipantPadding 10 +skinparam BoxPadding 10 +skinparam SequenceBoxBackgroundColor WhiteSmoke \ No newline at end of file diff --git a/src/uml/diagrams/sequence/seq_container_inventory.plantuml b/src/uml/diagrams/sequence/seq_container_inventory.plantuml new file mode 100644 index 0000000..e7dcb7a --- /dev/null +++ b/src/uml/diagrams/sequence/seq_container_inventory.plantuml @@ -0,0 +1,10 @@ +@startuml +!include seq.skin +!include ../../participants/foodprinter/PasteContainerConnector.plantuml +!include ../../participants/foodprinter/PasteContainer.plantuml + +MachineController -> PasteContainerConnector : getInventory() +loop + PasteContainerConnector -> PasteContainer : getPasteType() + +@enduml \ No newline at end of file diff --git a/src/uml/diagrams/sequence/seq_ordering_dishes.plantuml b/src/uml/diagrams/sequence/seq_ordering_dishes.plantuml new file mode 100644 index 0000000..aaecac7 --- /dev/null +++ b/src/uml/diagrams/sequence/seq_ordering_dishes.plantuml @@ -0,0 +1,27 @@ +@startuml +!include seq.skin + +!include ../../actors/Customer.plantuml +!include ../../participants/MachineApplication.plantuml +!include ../../participants/foodprinter/PasteContainer.plantuml + +Customer -> MachineApplication : listDishes() +activate MachineApplication + +loop each pasteContainer + MachineApplication -> PasteContainer : getPasteType() + activate PasteContainer + PasteContainer -->> MachineApplication : pasteType + deactivate PasteContainer + MachineApplication -> PasteContainer : getFillLevel() + activate PasteContainer + PasteContainer -->> MachineApplication : fillLevel + deactivate PasteContainer +end loop + +MachineApplication -> MachineApplication : calculateAvailableDishes(pasteInventory) +activate MachineApplication +deactivate MachineApplication +MachineApplication -->> Customer : dishList +deactivate MachineApplication +@enduml \ No newline at end of file diff --git a/src/uml/diagrams/sequence/seq_ordering_dishes_detailed_design.plantuml b/src/uml/diagrams/sequence/seq_ordering_dishes_detailed_design.plantuml new file mode 100644 index 0000000..1fe3331 --- /dev/null +++ b/src/uml/diagrams/sequence/seq_ordering_dishes_detailed_design.plantuml @@ -0,0 +1,51 @@ +@startuml +!include seq.skin + +!include ../../actors/Customer.plantuml +box "MachineApplication" + !include ../../participants/vendingmachine/UserInterface.plantuml + !include ../../participants/vendingmachine/MachineController.plantuml + !include ../../participants/vendingmachine/Cook.plantuml + !include ../../participants/foodprinter/PasteContainerConnector.plantuml +end box +!include ../../participants/foodprinter/PasteContainer.plantuml + +Customer -> UserInterface : listDishes() +activate UserInterface +UserInterface -> MachineController : listDishes() +activate MachineController +MachineController -> PasteContainerConnector : getInventory() +activate PasteContainerConnector + +loop each pasteContainer + PasteContainerConnector -> PasteContainer : getPasteType() + activate PasteContainer + PasteContainer -->> PasteContainerConnector : pasteType + deactivate PasteContainer + PasteContainerConnector -> PasteContainer : getFillLevel() + activate PasteContainer + PasteContainer -->> PasteContainerConnector : fillLevel + deactivate PasteContainer +end loop + +PasteContainerConnector -->> MachineController : pasteInventory +deactivate PasteContainerConnector +MachineController -> Cook : filterDishes(pasteInventory) +activate Cook + +loop each recipe + Cook -> Cook : canPrepare(recipe,\npasteInvertory) + activate Cook + deactivate Cook +end loop + +Cook -->> MachineController : dishes +deactivate Cook +MachineController -->> UserInterface : dishes +deactivate MachineController +UserInterface -> UserInterface : renderDishList(dishes) +activate UserInterface +deactivate UserInterface +UserInterface -->> Customer : dishList +deactivate UserInterface +@enduml \ No newline at end of file diff --git a/src/uml/interfaces/foodprinter/FoodPrinterIF.plantuml b/src/uml/interfaces/foodprinter/FoodPrinterIF.plantuml new file mode 100644 index 0000000..a757bbb --- /dev/null +++ b/src/uml/interfaces/foodprinter/FoodPrinterIF.plantuml @@ -0,0 +1,3 @@ +@startuml +interface "FoodPrinter" <> as FoodPrinterIF +@enduml \ No newline at end of file diff --git a/src/uml/interfaces/foodprinter/PasteContainerIF.plantuml b/src/uml/interfaces/foodprinter/PasteContainerIF.plantuml new file mode 100644 index 0000000..dfc3134 --- /dev/null +++ b/src/uml/interfaces/foodprinter/PasteContainerIF.plantuml @@ -0,0 +1,3 @@ +@startuml +interface "PasteContainer" as PasteContainerIF <> +@enduml \ No newline at end of file diff --git a/src/uml/interfaces/http/HttpClientIF.plantuml b/src/uml/interfaces/http/HttpClientIF.plantuml new file mode 100644 index 0000000..253bae7 --- /dev/null +++ b/src/uml/interfaces/http/HttpClientIF.plantuml @@ -0,0 +1,3 @@ +@startuml +interface "HttpClient" <> as HttpClientIF +@enduml \ No newline at end of file diff --git a/src/uml/interfaces/payment/CreditCardReaderIF.plantuml b/src/uml/interfaces/payment/CreditCardReaderIF.plantuml new file mode 100644 index 0000000..8aab2f3 --- /dev/null +++ b/src/uml/interfaces/payment/CreditCardReaderIF.plantuml @@ -0,0 +1,3 @@ +@startuml +interface "CreditCardReader" <> as CreditCardReaderIF +@enduml \ No newline at end of file diff --git a/src/uml/interfaces/payment/PaymentClientIF.plantuml b/src/uml/interfaces/payment/PaymentClientIF.plantuml new file mode 100644 index 0000000..8c58749 --- /dev/null +++ b/src/uml/interfaces/payment/PaymentClientIF.plantuml @@ -0,0 +1,3 @@ +@startuml +interface "PaymentClient" <> as PaymentClientIF +@enduml \ No newline at end of file diff --git a/src/uml/nodes/AutoYummyBox.plantuml b/src/uml/nodes/AutoYummyBox.plantuml new file mode 100644 index 0000000..7c4d72a --- /dev/null +++ b/src/uml/nodes/AutoYummyBox.plantuml @@ -0,0 +1 @@ +node "AutoYummyBox" as AutoYummyBoxNode \ No newline at end of file diff --git a/src/uml/nodes/CreditCardProvider.plantuml b/src/uml/nodes/CreditCardProvider.plantuml new file mode 100644 index 0000000..0e0bc79 --- /dev/null +++ b/src/uml/nodes/CreditCardProvider.plantuml @@ -0,0 +1 @@ +node "CreditCardProvider" <> as CreditCardProviderNode \ No newline at end of file diff --git a/src/main/resources/uml/nodes/OftAutoYummy.plantuml b/src/uml/nodes/OftAutoYummy.plantuml similarity index 100% rename from src/main/resources/uml/nodes/OftAutoYummy.plantuml rename to src/uml/nodes/OftAutoYummy.plantuml diff --git a/src/main/resources/uml/nodes/PasteFactory.plantuml b/src/uml/nodes/PasteFactory.plantuml similarity index 100% rename from src/main/resources/uml/nodes/PasteFactory.plantuml rename to src/uml/nodes/PasteFactory.plantuml diff --git a/src/main/resources/uml/nodes/PaymentProvider.plantuml b/src/uml/nodes/PaymentProvider.plantuml similarity index 100% rename from src/main/resources/uml/nodes/PaymentProvider.plantuml rename to src/uml/nodes/PaymentProvider.plantuml diff --git a/src/uml/nodes/VirtuCoinBuddyProvider.plantuml b/src/uml/nodes/VirtuCoinBuddyProvider.plantuml new file mode 100644 index 0000000..0960c09 --- /dev/null +++ b/src/uml/nodes/VirtuCoinBuddyProvider.plantuml @@ -0,0 +1 @@ +node "VirtuCoinBuddyProvider" <> as VirtuCoinBuddyProviderNode \ No newline at end of file diff --git a/src/uml/participants/MachineApplication.plantuml b/src/uml/participants/MachineApplication.plantuml new file mode 100644 index 0000000..7820cdc --- /dev/null +++ b/src/uml/participants/MachineApplication.plantuml @@ -0,0 +1,3 @@ +@startuml +participant MachineApplication +@enduml \ No newline at end of file diff --git a/src/uml/participants/foodprinter/FoodPrinter.plantuml b/src/uml/participants/foodprinter/FoodPrinter.plantuml new file mode 100644 index 0000000..75ee549 --- /dev/null +++ b/src/uml/participants/foodprinter/FoodPrinter.plantuml @@ -0,0 +1,3 @@ +@startuml +participant FoodPrinter <> +@enduml \ No newline at end of file diff --git a/src/uml/participants/foodprinter/FoodPrinterController.plantuml b/src/uml/participants/foodprinter/FoodPrinterController.plantuml new file mode 100644 index 0000000..dd9ef67 --- /dev/null +++ b/src/uml/participants/foodprinter/FoodPrinterController.plantuml @@ -0,0 +1,3 @@ +@startuml +participant FoodPrinterController +@enduml \ No newline at end of file diff --git a/src/uml/participants/foodprinter/PasteContainer.plantuml b/src/uml/participants/foodprinter/PasteContainer.plantuml new file mode 100644 index 0000000..9a84f17 --- /dev/null +++ b/src/uml/participants/foodprinter/PasteContainer.plantuml @@ -0,0 +1,3 @@ +@startuml +participant PasteContainer <> <> +@enduml \ No newline at end of file diff --git a/src/uml/participants/foodprinter/PasteContainerConnector.plantuml b/src/uml/participants/foodprinter/PasteContainerConnector.plantuml new file mode 100644 index 0000000..1827cfd --- /dev/null +++ b/src/uml/participants/foodprinter/PasteContainerConnector.plantuml @@ -0,0 +1,3 @@ +@startuml +participant PasteContainerConnector +@enduml \ No newline at end of file diff --git a/src/uml/participants/vendingmachine/Cook.plantuml b/src/uml/participants/vendingmachine/Cook.plantuml new file mode 100644 index 0000000..496ea1a --- /dev/null +++ b/src/uml/participants/vendingmachine/Cook.plantuml @@ -0,0 +1,3 @@ +@startuml +participant Cook +@enduml \ No newline at end of file diff --git a/src/uml/participants/vendingmachine/MachineBackendConnector.plantuml b/src/uml/participants/vendingmachine/MachineBackendConnector.plantuml new file mode 100644 index 0000000..807022a --- /dev/null +++ b/src/uml/participants/vendingmachine/MachineBackendConnector.plantuml @@ -0,0 +1,3 @@ +@startuml +participant MachineBackendConnector +@enduml \ No newline at end of file diff --git a/src/uml/participants/vendingmachine/MachineController.plantuml b/src/uml/participants/vendingmachine/MachineController.plantuml new file mode 100644 index 0000000..d44674a --- /dev/null +++ b/src/uml/participants/vendingmachine/MachineController.plantuml @@ -0,0 +1,3 @@ +@startuml +participant MachineController +@enduml \ No newline at end of file diff --git a/src/uml/participants/vendingmachine/UserInterface.plantuml b/src/uml/participants/vendingmachine/UserInterface.plantuml new file mode 100644 index 0000000..3c27205 --- /dev/null +++ b/src/uml/participants/vendingmachine/UserInterface.plantuml @@ -0,0 +1 @@ +participant UserInterface \ No newline at end of file