{"id":23282776,"url":"https://github.com/itsallcode/openfasttrace-architecture-template","last_synced_at":"2025-08-21T13:33:42.455Z","repository":{"id":80229561,"uuid":"141965444","full_name":"itsallcode/openfasttrace-architecture-template","owner":"itsallcode","description":"Template for system and software architecture done with OpenFastTrace","archived":false,"fork":false,"pushed_at":"2024-01-14T18:46:37.000Z","size":122,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-07T18:07:03.780Z","etag":null,"topics":["arc42","architecture","markdown","pandoc","plantuml","requirement-specifications","requirements-engineering","requirements-tracing","template","tutorial"],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-sa-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itsallcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-07-23T05:27:59.000Z","updated_at":"2024-05-07T18:07:03.781Z","dependencies_parsed_at":"2023-09-17T16:47:09.510Z","dependency_job_id":null,"html_url":"https://github.com/itsallcode/openfasttrace-architecture-template","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsallcode%2Fopenfasttrace-architecture-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsallcode%2Fopenfasttrace-architecture-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsallcode%2Fopenfasttrace-architecture-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsallcode%2Fopenfasttrace-architecture-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsallcode","download_url":"https://codeload.github.com/itsallcode/openfasttrace-architecture-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230519222,"owners_count":18238841,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arc42","architecture","markdown","pandoc","plantuml","requirement-specifications","requirements-engineering","requirements-tracing","template","tutorial"],"created_at":"2024-12-20T00:29:46.061Z","updated_at":"2024-12-20T00:29:46.758Z","avatar_url":"https://github.com/itsallcode.png","language":"CSS","readme":"# OpenFastTrace Architecture Template\n\nTemplate for system and software architecture done with OpenFastTrace.\n\n## Acknowledgments\n\nThe architecture documents structure is based the the [arc42](https://arc42.org) architecture template by Dr. Gernot Starke, Dr. Peter Hruschka.\n\nThe [arc42 template](https://github.com/arc42/arc42-template) is offered under the [CC-BY-SA](LICENSE.txt). Please keep attributions in all derived works.\n\nThis build automatically includes license headers in the Markdown files for that reasons. See [\"Automatic License Headers\"](#automatic-license-headers) for details.\n\n## Change Log\n\n* [Change log](doc/changelog.md)\n\n## Installation\n\n### On Debian / Ubuntu Linux\n\nIf 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).\n\n```bash\napt install plantuml pandoc\n```\n\nSince 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.\n\n```bash\napt install plantuml pandoc texlive-latex-base texlive-fonts-recommended librsvg2-bin\n```\n\n### On Fedora Linux\n\n```bash\nyum install plantuml pandoc texlive-schema-full librsvg2-tools\n```\n\n## Project Layout\n\nThe directory structure below shows the most important parts of the project layout and what they mean.\n\n```\nproject root\n  |-- launch                     Eclipse launch configurations\n  |\n  |-- src\n  |    |-- assembly              Configuration for creating archives (TAR, ZIP)\n  |    |\n  |    |-- doc                   Markdown sources of the specification\n  |    |    |-- css              CSS for the HTML output\n  |    |   ...\n  |    |\n  |    |-- license               License and license headers\n  |    |\n  |    |-- main\n  |    |    '-- lua              Lua filters for Pandoc\n  |    |\n  |    '-- uml                   PlantUML sources for the UML model\n  |         |-- actors         \n  |         |-- classes\n  |         |-- diagrams         Sources for the UML diagrams\n  |         |     |-- activity\n  |         |     |-- class\n  |         |    ...\n  |        ...\n  |\n  |-- target\n  |    |-- \u003cspec-name\u003e.html      Generated HTML output of the specification\n  |    '-- \u003cspec-name\u003e.pdf       Generated PDF\n ...\n  '-- pom.xml                    Maven project configuration\n```\n\n**\u0026#9888; 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.** \n\n\n## Authoring\n\nFor authoring any text editor will work.\n\nWe 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).\n\nRead 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.\n\n### Stripping the OFT Comments\n\nThe 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).\n\nOr you can use command line tools like `sed`. Run the script below on the root directory of the architecture template.\n\n```bash\nfind src/doc -name '*.md' -exec sed -i -e '/^\u003e\\s*OFT:.*/d' {} \\;\n```\n\n## Building\n\n### Build Dependencies\n\n| Dependency                                                                              | Purpose                | License                                                                |\n|-----------------------------------------------------------------------------------------|------------------------|------------------------------------------------------------------------|\n| [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) |\n| [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) |              |\n| [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) |\n| [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)         |\n| [Maven](https://maven.apache.org/)                                                      | Build                  | [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) |\n| [Pandoc](https://pandoc.org)                                                            | Document rendering     | [GPL v3.0](http://www.gnu.org/licenses/quick-guide-gplv3.html)         |\n| [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) |\n\n### Configuration\n\nYou can find the configuration for the build in the [Maven `pom.xml` file](pom.xml) of this project.\n\nTo configure the build variables like document name and version number change the properties:\n\n```xml\n\u003cproject xmlns=\"http://maven.apache.org/POM/4.0.0\"\n  \u003c!-- ... --\u003e\n  \u003cproperties\u003e\n    \u003c!-- ... --\u003e\n    \u003cspec.version\u003e${project.version}\u003c/spec.version\u003e\n    \u003cspec.date\u003e${maven.build.timestamp}\u003c/spec.date\u003e\n    \u003cspec.title\u003eAutoYummiBox ${spec.version} - Software Architectural Design\u003c/spec.title\u003e\n    \u003cspec.authors\u003eS. Bär, M. Thielcke\u003c/spec.authors\u003e\n    \u003cspec.filename\u003eSwAD-AutoYummiBox\u003c/spec.filename\u003e\n    \u003cspec.files\u003earchitecture.md introduction.md context.md\n      ...\n      glossary.md bibliography.md\u003c/spec.files\u003e\n  \u003c/properties\u003e\n  \u003c!-- ... --\u003e\n\u003c/project\u003e\n```\n\nThe `spec.files` property must contain all files you want to render into the specification in the order in which that must be concatenated.\n\n#### Defaults\n\nThe 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.\n\nThe 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).\n\nWhile 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.\n\n**\u0026#9888; If you introduce new files, don't forget to list them there!**\n\n### Automatic License Headers\n\nThe 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.\n\nRun the following Maven command to create or update the file headers:\n\n```bash\nmvn license:update-project-license license:update-file-header\n```\n\n### Conversion\n\nThe 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.\n\nOn 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.\n\nCheck 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.\n\n    src/main/lua/link_converter.lua\n\nThe filter is applied via the `--lua-filters` command line switch.\n\n### Running the Build\n\nIf you only want to render the document and UML source into HTML and images run:\n\n```bash\nmvn compile\n```\n\nTo create archives from the rendered documents run:\n\n```bash\nmvn package\n```\n\n## Validation\n\nIt is a good idea to check the links in your document from time to time.\n\n### Under Debian / Ubuntu\n\nInstall the `linkchecker` package:\n\n```bash\napt install linkchecker\n```\n\nCheck the links in the generated HTML docuements:\n\n```bash\nlinkchecker --check-extern target/*.html\n```\n\nIf you remove the command line switch `--check-extern` only local links are checked. \n\n## Continuous Integration\n\nThis 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.\nThe build process itself is defined within `Jenkinsfile` and consists of these stages:\n- checkout : Get the source from repo\n- build docker : Create the Docker image to be used during build execution (only once if it doesn't exist locally)\n- render html : render a HTML file from sources\n- render pdf : render a PDF file from source\n\nThe 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`.\n\n### Build without Docker\n\nIf 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. \n- [docker/Dockerfile](docker/Dockerfile) can be used as template for the setup of the required tools.\n- the Jenkins agents should be labeled accordingly (i.e. pandoc)\n- `Jenkinsfile` : label needs to match agent-labels (i.e. pandoc)\n- `Jenkinsfile` : the \"build docker\" stage has to be removed\n- `Jenkinsfile` : the \"run docker\"-part has to be removed from sh-executions\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsallcode%2Fopenfasttrace-architecture-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsallcode%2Fopenfasttrace-architecture-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsallcode%2Fopenfasttrace-architecture-template/lists"}