SemTrail was created because I had the need to document and structure a medium number interconnected requirements. Customer requirements and facts lead over a number of indirections to a concrete architecture.
It uses a LISP/Clojure-like DSL for describing requirements, facts, conclusions and similar using typed nodes. Interconnections are defined via edge that also have a type. This builds a semantic graph.
From the description file an internal model is build.
It uses Thymeleaf for generating the resulting web pages base don the passed internal model.
The current status is "it starts to work for me but I'll likely add some further small enhancements".
If you are interested, participate.
The project visualizes a trail from customer requirements to conceptual solutions and finally to concrete technological decisions. In principle, it is a semantic graph. Where each node is a requirement, a concept or a technical solution and each edge represents a deduction, a decision, a possible alternative or similar.
The similarity between "SemTrail" and "Chemtrail" was realized and found to be funny. Also, some architecture claims to have its origin in a path of concrete, well thought of decisions - but nobody never has seen them, neither are they documented.
Simply call it using
SemTrail <description file>.semtrail <template directory> <target directory>There are currently some quirks in the command line handling and resulting processing. So expect errors if you do not follow the expected syntax.
The current version using the default templates generates the following navigable pages:
| Page | Template | Content |
|---|---|---|
| All | index.html |
Tabular representation of all defined nodes |
| All (Map) | image.html |
Network-lke visualisation of all nodes and their connecting edges |
| \<Node type> | index.html |
For each node type a tabular representation of all node of this type |
| Starter | index.html |
A list of all nodes that "start" a directed graph |
| Leaves | index.html |
A list of all nodes that have only incoming edges |
| By #causes | index.html |
A list of all nodes sorted by the number of incoming edges |
| By #consequences | index.html |
A list of all nodes sorted by the number of outgoing edges |
| By #connected | index.html |
A list of all nodes sorted by the sum of incoming and outgoing edges |
| Orphans | index.html |
A list of nodes that have neither incoming nor outgoing edges |
| Missing Documentation | index.html |
A list of nodes that have no documentation |
Besides above pages a page for each node is generated using the node.html template.
The following additional template files are used for reusing and sharing content over all generated pages and should be referenced from above pages:
| File | Content |
|---|---|
footer.html |
Common footer of each page |
header.html |
Common header of each page |
navigation.html |
Common navigation component |
standard.css |
Common style sheet |
The template gets passed the following objects, depending on its meaning:
| Object | Type | Passed to | Description |
|---|---|---|---|
| model | Model | Always | The data parsed from the semtrail file |
| config | Config | Always | Additional configuration data |
| node | Node | Detail page of a node | The current node |
| nodes | List\<Node> | List of nodes | The (possibly filtered) list of nodes to display |
The Model class has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| nodeTypes | Map\<String,NodeType> | map of node type names to node types |
| edgeTypes | Map\<String,EdgeType> | map of edge type names to edge types |
| nodeMap | Map\<String,Node> | Mapping from node name to Node type instance |
The Config class has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| pages | List\<Page> | List of pages |
The Page class has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| page | Path | path of the generated page |
| label | String | label for the generated page |
| Attribute | Type | Description |
|---|---|---|
| type | String | The type name of the node type |
| name | String | The descriptive name of the node type |
| color | String | The color for the node |
| Attribute | Type | Description |
|---|---|---|
| type | String | The type name of the edge type |
| name | String | The descriptive name of the edge type |
| color | String | The color for the edge |
| Attribute | Type | Description |
|---|---|---|
| name | String | The name of the node |
| type | String | The name of the node type |
| doc | String | A documentation |
| fromNodes | Map\<String,Edge> | Map from edge name to Edge type instance for all incoming edges |
| toNodes | Map\<String,Edge> | Map from edge name to Edge type instance for all outgoing edges |
| Attribute | Type | Description |
|---|---|---|
| type | String | The type name |
| from | Node | The from Node |
| to | Node | The to Node |
| doc | String | A documentation |
TODO
The repository contains a simple Dockerfile as boiler plate example for hosting the generated static web pages using nginx. This is not a production ready example, only a simple show cases for tests. Make sure that you host static content with the base images you trust.
Build the docker container:
./build_docker.shThis copies the relevant files in to a maven-based base Image (maven:latest from docker.io), starts a maven build and generate the static pages for Semtrail.semtrail.
Afterwards it creates a nginx based image (framstag/semtrail:latest) with the above generated static content to serve.
Running the image:
./run_docker.shThis runs the nginx in the resulting Docker image under localhost:8080