diff --git a/docs/Makefile b/docs/Makefile index c30c50a..b97c753 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1 +1,2 @@ include ../../swh-docs/Makefile.sphinx +-include Makefile.local diff --git a/docs/Makefile.local b/docs/Makefile.local new file mode 100644 index 0000000..3bc7efd --- /dev/null +++ b/docs/Makefile.local @@ -0,0 +1,16 @@ +sphinx/html: images +sphinx/clean: clean-images +assets: images + +images: + make -C images/ +clean-images: + make -C images/ clean + + +.PHONY: images clean-images + + +# Local Variables: +# mode: makefile +# End: diff --git a/docs/design.md b/docs/design.md index 8dab5c9..d96083e 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,237 +1,253 @@ # Software Heritage virtual filesystem (SwhFS) --- Design notes ```{warning} this document describes design notes for the Software Heritage virtual filesystem (SwhFS), which is still under active development and hence **not yet available** for general use. ``` The [Software Heritage](https://www.softwareheritage.org/) {ref}`data model ` is a [Direct Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) with nodes of different types that correspond to source code artifacts such as directories, commits, etc. Using this [FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace) module (*SwhFS* for short) you can locally mount, and then navigate as a (virtual) file system, parts of the archive identified by {ref}`Software Heritage identifiers ` (SWHIDs). To retrieve information about the source code artifacts, SwhFS interacts over the network with the Software Heritage archive via its {ref}`Web API `. +## Architecture + +SwhFS in context ([C4](https://en.wikipedia.org/wiki/C4_model) context +diagram): + +```{image} images/arch-context.svg +:align: center +``` + +Main components of SwhFS (C4 container diagram): + +```{image} images/arch-container.svg +:align: center +``` + + ## Command-line interface $ swh fs mount [SWHID]... will mount the Software Heritage archive at the local ``, the *SwhFS mount point*. From there, the user will be able to lazily load and navigate the archive using SWHID at entry points. If one or more SWHIDs are also specified, the corresponding objects will be pre- fetched from the archive at mount-time and available at `/archive/`. For more details see the {ref}`CLI documentation `. ## Mount point The SwhFS mount point contain: - `archive/`: initially empty, this directory is lazily populated with one entry per accessed SWHID, having actual SWHIDs as names. - `meta/`: initially empty, this directory contains one `.json` file for each `` entry under `archive/`. The JSON file contain all available meta information about the given SWHID, as returned by the Software Heritage Web API for that object. Note that, in case of pagination (e.g., snapshot objects with many branches) the JSON file will contain a complete version with all pages merged together. ```{todo} Consider sharding ``/`.json` files under `ab/cd/` dirs to avoid exploding the number of dir entries under `archive/` and `meta/` (cf. [T2694](https://forge.softwareheritage.org/T2694)) ``` ## File system representation SWHID are represented differently on the file-system depending on the associated node types in the Software Heritage graph. Details are given below, for each node type. ### `cnt` nodes (blobs) Content leaves (AKA blobs) are represented on disks as regular files, containing the corresponding bytes, as archived. Note that permissions are associated to blobs only in the context of directories. Hence, when accessing blobs from the top-level `archive/` directory, the permissions of the `archive/SWHID` file will be arbitrary and not meaningful (e.g., `0x644`). ### `dir` nodes (directories) Directory nodes are represented as directories on the file-system, containing one entry for each entry of the archived directory. Entry names and other metadata, including permissions, will correspond to the archived entry metadata. Note that SwhFS is mounted read-only, no matter what the permissions say. So it is possible that, in the context of a directory, a file is presented as writable, whereas actually writing to it will fail with `EPERM`. ### `rev` nodes (commits) Revision (AKA commit) nodes are represented on the file-system as directories with the following entries: - `root`: source tree at the time of the commit, as a symlink pointing into `archive/`, to a SWHID of type `dir` - `parents/` (note the plural): a virtual directory containing entries named `1`, `2`, `3`, etc., one for each parent commit. Each of these entry is a symlink pointing into `archive/`, to the SWHID file for the given parent commit - `parent` (note the singular): present if and only if the current commit has a single parent commit (which is the most common case). When present it is a symlink pointing into `archive/` to the SWHID for the sole parent commit - `history`: a virtual directory containing all the parents commit until the root commit. Entries are listed as symlinks with the SWHID as directory name, pointing into `archive/SWHID`, and are returned in a topological ordering similar to `git log` ordering. - `meta.json`: metadata for the current node, as a symlink pointing to the relevant `meta/.json` file ### `rel` nodes (releases) Release nodes are represented on the file-system as directories with the following entries: - `target`: target node, as a symlink to `archive/` - `target_type`: type of the target SWHID, as a 3-letter code - `root`: present if and only if the release points to something that (transitively) resolves to a directory. When present it is a symlink pointing into `archive/` to the SWHID of the given directory - `meta.json`: metadata for the current node, as a symlink pointing to the relevant `meta/.json` file ### `snp` nodes (snapshots) Snapshot nodes are represented on the file-system as directories with on entry for each branch in the snapshot. Branch names are mangled by replacing... ```{todo} decide how to do branch name escaping and describe it here ``` Each entry is a symlink pointing into `archive/` to the branch target SWHID. ## Caching SwhFS retrieves both metadata and file contents from the Software Heritage archive via the network. In order to obtain reasonable performances several caches are used to minimize network transfer. Caches are stored on disk in SQLite DB(s) located under `$XDG_CACHE_HOME/swh/fuse/`. ```{todo} - potential improvement: store blobs larger than a threshold on disk as files rather than in SQLite, e.g., under `$XDG_CACHE_HOME/swh/fuse/objects/` ``` All caches are persistent (i.e., they survive the restart of the SwhFS process) and global (i.e., they are shared by concurrent SwhFS processes). We assume that no cache *invalidation* is necessary, due to intrinsic properties of the Software Heritage archive, such as integrity verification and append-only archive changes. To clean the caches one can just remove the corresponding files from disk. ### Metadata cache SWHID → JSON metadata The metadata cache map each SWHID to the complete metadata of the referenced object. This is analogous to what is available in `meta/.json` file (and generally used as data source for returning the content of those files). Cache location on-disk: `$XDG_CACHE_HOME/swh/fuse/metadata.sqlite` ### Blob cache cnt SWHID → bytes The blob cache map SWHIDs of type `cnt` to the bytes of their archived content. In general, each SWHID that has an entry in the blob cache also has a matching entry in the metadata cache for other blob attributes (e.g., checksums, size, etc.). The blob cache entry for a given content object is populated, at the latest, the first time the object is `open()`-d. It might be populated earlier on due to prefetching, e.g., when a directory pointing to the given content is listed for the first time. Cache location on-disk: `$XDG_CACHE_HOME/swh/fuse/blob.sqlite` ### Dentry cache dir SWHID → directory entries The dentry (directory entry) cache map SWHIDs of type `dir` to the directory entries they contain. Each entry comes with its name as well as file attributes (i.e., all its needed to perform a detailed directory listing). Additional attributes of each directory entry should be looked up on a entry by entry basis, possibly hitting the metadata cache. The dentry cache for a given dir is populated, at the latest, when the content of the directory is listed. More aggressive prefetching might happen. For instance, when first opening a dir a recursive listing of it can be retrieved from the remote backend and used to recursively populate the dentry cache for all (transitive) sub-directories. ### Parents cache rev SWHID → parent SWHIDs The parents cache map SWHIDs of type `rev` to the list of their parent commits. The parents cache for a given rev is populated, at the latest, when the content of the revision virtual directory is listed. More aggressive prefetching might happen. For instance, when first opening a rev virtual directory a recursive listing of all its ancestor can be retrieved from the remote backend and used to recursively populate the parents cache for all ancestors. ### History cache rev SWHID → ancestor SWHIDs The history cache map SWHIDs of type `rev` to a list of `rev` SWHIDs corresponding to all its revision ancestors, sorted in reverse topological order. As the parents cache, the history cache is lazily populated and can be prefetched. To efficiently store the ancestor lists, the history cache represents ancestors as graph edges (a pair of two SWHID nodes), meaning the history cache is shared amongst all revisions parents. diff --git a/docs/images/Makefile b/docs/images/Makefile new file mode 100644 index 0000000..c415f79 --- /dev/null +++ b/docs/images/Makefile @@ -0,0 +1,21 @@ +PUMLs = $(wildcard *.puml) +PDFs = $(patsubst %.puml,%.pdf,$(PUMLs)) +PNGs = $(patsubst %.puml,%.png,$(PUMLs)) +SVGs = $(patsubst %.puml,%.svg,$(PUMLs)) + +all: $(PNGs) $(PDFs) $(SVGs) + +%.pdf: %.puml + plantuml -Tpdf $< + +%.png: %.puml + plantuml -Tpng $< + +%.svg: %.puml + plantuml -Tsvg $< + + +.PHONY: clean + +clean: + rm -f $(PDFs) $(PNGs) $(SVGs) diff --git a/docs/images/arch-container.pdf b/docs/images/arch-container.pdf new file mode 100644 index 0000000..e2e26d3 Binary files /dev/null and b/docs/images/arch-container.pdf differ diff --git a/docs/images/arch-container.png b/docs/images/arch-container.png new file mode 100644 index 0000000..dabd96d Binary files /dev/null and b/docs/images/arch-container.png differ diff --git a/docs/images/arch-container.puml b/docs/images/arch-container.puml new file mode 100644 index 0000000..9fb2cfc --- /dev/null +++ b/docs/images/arch-container.puml @@ -0,0 +1,23 @@ +@startuml arch-container +' !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml +!include c4-plantuml/C4_Container.puml + +' title Container diagram for the Software Heritage virtual filesystem (SwhFS) +left to right direction + +Person(user, "User") +Container(fuse, "FUSE", "kernel", "Delegates filesystem implementation to user space") + +System_Boundary(swhfs_bound, "SwhFS") { + Container(swh_fuse, "swh.fuse", "pyfuse3, libfuse, FUSE", "Provides a filesystem view of Software Heritage objects") + ContainerDb(cache, "Cache", "SQLite or in-memory", "Local cache for objects and metadata") + Rel(swh_fuse, cache, "Reads objects and metadata", "SQL") +} + +System_Ext(archive, "Software Heritage archive") + +Rel(user, fuse, "Access", "Filesystem") +Rel(fuse, swh_fuse, "Calls user space daemon", "FUSE API") +Rel(swh_fuse, archive, "Retrieves objects and metadata", "REST API") + +@enduml diff --git a/docs/images/arch-container.svg b/docs/images/arch-container.svg new file mode 100644 index 0000000..8ff85f4 --- /dev/null +++ b/docs/images/arch-container.svg @@ -0,0 +1,174 @@ +«boundary»SwhFS[System]«container»swh.fuse[pyfuse3, libfuse, FUSE]Provides a filesystem view ofSoftware Heritage objects«container»Cache[SQLite or in-memory]Local cache for objects andmetadata«person»User«container»FUSE[kernel]Delegates filesystemimplementation to userspace«external_system»Software HeritagearchiveReads objects andmetadata[SQL]Access[Filesystem]Calls user spacedaemon[FUSE API]Retrieves objectsand metadata[REST API] \ No newline at end of file diff --git a/docs/images/arch-context.pdf b/docs/images/arch-context.pdf new file mode 100644 index 0000000..ee12b60 Binary files /dev/null and b/docs/images/arch-context.pdf differ diff --git a/docs/images/arch-context.png b/docs/images/arch-context.png new file mode 100644 index 0000000..ecad0cc Binary files /dev/null and b/docs/images/arch-context.png differ diff --git a/docs/images/arch-context.puml b/docs/images/arch-context.puml new file mode 100644 index 0000000..22fb244 --- /dev/null +++ b/docs/images/arch-context.puml @@ -0,0 +1,15 @@ +@startuml arch-context +' !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Context.puml +!include c4-plantuml/C4_Context.puml + +' title System context diagram for the Software Heritage virtual filesystem (SwhFS) +left to right direction + +Person(user, "User") +System(swhfs, "Software Heritage virtual filesystem\n(SwhFS)") +System_Ext(archive, "Software Heritage archive") + +Rel(user, swhfs, "Accesses", "Filesystem") +Rel(swhfs, archive, "Retrieves objects and metadata", "REST API") + +@enduml diff --git a/docs/images/arch-context.svg b/docs/images/arch-context.svg new file mode 100644 index 0000000..11651aa --- /dev/null +++ b/docs/images/arch-context.svg @@ -0,0 +1,136 @@ +«person»User«system»Software Heritagevirtual filesystem(SwhFS)«external_system»Software HeritagearchiveAccesses[Filesystem]Retrieves objectsand metadata[REST API] \ No newline at end of file diff --git a/docs/images/c4-plantuml/C4.puml b/docs/images/c4-plantuml/C4.puml new file mode 100644 index 0000000..d28711a --- /dev/null +++ b/docs/images/c4-plantuml/C4.puml @@ -0,0 +1,106 @@ +' C4-PlantUML, version 1.0.0 +' https://github.com/RicardoNiepel/C4-PlantUML + +' Colors +' ################################## + +!define ELEMENT_FONT_COLOR #FFFFFF + +' Styling +' ################################## + +!define TECHN_FONT_SIZE 12 + +skinparam defaultTextAlignment center + +skinparam wrapWidth 200 +skinparam maxMessageSize 150 + +skinparam rectangle { + StereotypeFontSize 12 + shadowing false +} + +skinparam database { + StereotypeFontSize 12 + shadowing false +} + +skinparam Arrow { + Color #666666 + FontColor #666666 + FontSize 12 +} + +skinparam rectangle<> { + Shadowing false + StereotypeFontSize 0 + FontColor #444444 + BorderColor #444444 + BorderStyle dashed +} + +' Layout +' ################################## + +!definelong LAYOUT_AS_SKETCH +skinparam backgroundColor #EEEBDC +skinparam handwritten true +skinparam defaultFontName "Comic Sans MS" +center footer Warning: Created for discussion, needs to be validated +!enddefinelong + +!define LAYOUT_TOP_DOWN top to bottom direction +!define LAYOUT_LEFT_RIGHT left to right direction + +' Boundaries +' ################################## + +!define Boundary(e_alias, e_label) rectangle "==e_label" <> as e_alias +!define Boundary(e_alias, e_label, e_type) rectangle "==e_label\n[e_type]" <> as e_alias + +' Relationship +' ################################## + +!define Rel_(e_alias1, e_alias2, e_label, e_direction="") e_alias1 e_direction e_alias2 : "===e_label" +!define Rel_(e_alias1, e_alias2, e_label, e_techn, e_direction="") e_alias1 e_direction e_alias2 : "===e_label\n//[e_techn]//" + +!define Rel(e_from,e_to, e_label) Rel_(e_from,e_to, e_label, "-->") +!define Rel(e_from,e_to, e_label, e_techn) Rel_(e_from,e_to, e_label, e_techn, "-->") + +!define Rel_Back(e_to, e_from, e_label) Rel_(e_to, e_from, e_label, "<--") +!define Rel_Back(e_to, e_from, e_label, e_techn) Rel_(e_to, e_from, e_label, e_techn, "<--") + +!define Rel_Neighbor(e_from,e_to, e_label) Rel_(e_from,e_to, e_label, "->") +!define Rel_Neighbor(e_from,e_to, e_label, e_techn) Rel_(e_from,e_to, e_label, e_techn, "->") + +!define Rel_Back_Neighbor(e_to, e_from, e_label) Rel_(e_to, e_from, e_label, "<-") +!define Rel_Back_Neighbor(e_to, e_from, e_label, e_techn) Rel_(e_to, e_from, e_label, e_techn, "<-") + +!define Rel_D(e_from,e_to, e_label) Rel_(e_from,e_to, e_label, "-DOWN->") +!define Rel_D(e_from,e_to, e_label, e_techn) Rel_(e_from,e_to, e_label, e_techn, "-DOWN->") +!define Rel_Down(e_from,e_to, e_label) Rel_D(e_from,e_to, e_label) +!define Rel_Down(e_from,e_to, e_label, e_techn) Rel_D(e_from,e_to, e_label, e_techn) + +!define Rel_U(e_from,e_to, e_label) Rel_(e_from,e_to, e_label, "-UP->") +!define Rel_U(e_from,e_to, e_label, e_techn) Rel_(e_from,e_to, e_label, e_techn, "-UP->") +!define Rel_Up(e_from,e_to, e_label) Rel_U(e_from,e_to, e_label) +!define Rel_Up(e_from,e_to, e_label, e_techn) Rel_U(e_from,e_to, e_label, e_techn) + +!define Rel_L(e_from,e_to, e_label) Rel_(e_from,e_to, e_label, "-LEFT->") +!define Rel_L(e_from,e_to, e_label, e_techn) Rel_(e_from,e_to, e_label, e_techn, "-LEFT->") +!define Rel_Left(e_from,e_to, e_label) Rel_L(e_from,e_to, e_label) +!define Rel_Left(e_from,e_to, e_label, e_techn) Rel_L(e_from,e_to, e_label, e_techn) + +!define Rel_R(e_from,e_to, e_label) Rel_(e_from,e_to, e_label, "-RIGHT->") +!define Rel_R(e_from,e_to, e_label, e_techn) Rel_(e_from,e_to, e_label, e_techn, "-RIGHT->") +!define Rel_Right(e_from,e_to, e_label) Rel_R(e_from,e_to, e_label) +!define Rel_Right(e_from,e_to, e_label, e_techn) Rel_R(e_from,e_to, e_label, e_techn) + +' Layout Helpers +' ################################## + +!define Lay_D(e_from, e_to) e_from -[hidden]D- e_to +!define Lay_U(e_from, e_to) e_from -[hidden]U- e_to +!define Lay_R(e_from, e_to) e_from -[hidden]R- e_to +!define Lay_L(e_from, e_to) e_from -[hidden]L- e_to \ No newline at end of file diff --git a/docs/images/c4-plantuml/C4_Component.puml b/docs/images/c4-plantuml/C4_Component.puml new file mode 100644 index 0000000..7b99420 --- /dev/null +++ b/docs/images/c4-plantuml/C4_Component.puml @@ -0,0 +1,55 @@ +' !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml +' uncomment the following line and comment the first to use locally +!include C4_Container.puml + +' Scope: A single container. +' Primary elements: Components within the container in scope. +' Supporting elements: Containers (within the software system in scope) plus people and software systems directly connected to the components. +' Intended audience: Software architects and developers. + +' Colors +' ################################## + +!define COMPONENT_BG_COLOR #85BBF0 + +' Styling +' ################################## + +skinparam rectangle<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor #000000 + BackgroundColor COMPONENT_BG_COLOR + BorderColor #78A8D8 +} + +skinparam database<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor #000000 + BackgroundColor COMPONENT_BG_COLOR + BorderColor #78A8D8 +} + +' Layout +' ################################## + +!definelong LAYOUT_WITH_LEGEND +hide stereotype +legend right +|= |= Type | +| | person | +| | external person | +| | system | +| | external system | +| | container | +| | component | +endlegend +!enddefinelong + +' Elements +' ################################## + +!define Component(e_alias, e_label, e_techn) rectangle "==e_label\n//[e_techn]//" <> as e_alias +!define Component(e_alias, e_label, e_techn, e_descr) rectangle "==e_label\n//[e_techn]//\n\n e_descr" <> as e_alias + +!define ComponentDb(e_alias, e_label, e_techn) database "==e_label\n//[e_techn]//" <> as e_alias +!define ComponentDb(e_alias, e_label, e_techn, e_descr) database "==e_label\n//[e_techn]//\n\n e_descr" <> as e_alias diff --git a/docs/images/c4-plantuml/C4_Container.puml b/docs/images/c4-plantuml/C4_Container.puml new file mode 100644 index 0000000..77f5d8b --- /dev/null +++ b/docs/images/c4-plantuml/C4_Container.puml @@ -0,0 +1,59 @@ +' !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Context.puml +' uncomment the following line and comment the first to use locally +!include C4_Context.puml + +' Scope: A single software system. +' Primary elements: Containers within the software system in scope. +' Supporting elements: People and software systems directly connected to the containers. +' Intended audience: Technical people inside and outside of the software development team; including software architects, developers and operations/support staff. + +' Colors +' ################################## + +!define CONTAINER_BG_COLOR #438DD5 + +' Styling +' ################################## + +skinparam rectangle<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor ELEMENT_FONT_COLOR + BackgroundColor CONTAINER_BG_COLOR + BorderColor #3C7FC0 +} + +skinparam database<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor ELEMENT_FONT_COLOR + BackgroundColor CONTAINER_BG_COLOR + BorderColor #3C7FC0 +} + +' Layout +' ################################## + +!definelong LAYOUT_WITH_LEGEND +hide stereotype +legend right +|= |= Type | +| | person | +| | external person | +| | system | +| | external system | +| | container | +endlegend +!enddefinelong + +' Elements +' ################################## + +!define Container(e_alias, e_label, e_techn) rectangle "==e_label\n//[e_techn]//" <> as e_alias +!define Container(e_alias, e_label, e_techn, e_descr) rectangle "==e_label\n//[e_techn]//\n\n e_descr" <> as e_alias + +!define ContainerDb(e_alias, e_label, e_techn) database "==e_label\n//[e_techn]//" <> as e_alias +!define ContainerDb(e_alias, e_label, e_techn, e_descr) database "==e_label\n//[e_techn]//\n\n e_descr" <> as e_alias + +' Boundaries +' ################################## + +!define Container_Boundary(e_alias, e_label) Boundary(e_alias, e_label, "Container") diff --git a/docs/images/c4-plantuml/C4_Context.puml b/docs/images/c4-plantuml/C4_Context.puml new file mode 100644 index 0000000..0ea0eaa --- /dev/null +++ b/docs/images/c4-plantuml/C4_Context.puml @@ -0,0 +1,102 @@ +' !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4.puml +' uncomment the following line and comment the first to use locally +!include C4.puml + +' Scope: A single software system. +' Primary elements: The software system in scope. +' Supporting elements: People and software systems directly connected to the software system in scope. +' Intended audience: Everybody, both technical and non-technical people, inside and outside of the software development team. + +' Colors +' ################################## + +!define PERSON_BG_COLOR #08427B +!define EXTERNAL_PERSON_BG_COLOR #686868 +!define SYSTEM_BG_COLOR #1168BD +!define EXTERNAL_SYSTEM_BG_COLOR #999999 + +' Styling +' ################################## + +skinparam rectangle<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor ELEMENT_FONT_COLOR + BackgroundColor PERSON_BG_COLOR + BorderColor #073B6F +} + +skinparam rectangle<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor ELEMENT_FONT_COLOR + BackgroundColor EXTERNAL_PERSON_BG_COLOR + BorderColor #8A8A8A +} + +skinparam rectangle<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor ELEMENT_FONT_COLOR + BackgroundColor SYSTEM_BG_COLOR + BorderColor #3C7FC0 +} + +skinparam rectangle<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor ELEMENT_FONT_COLOR + BackgroundColor EXTERNAL_SYSTEM_BG_COLOR + BorderColor #8A8A8A +} + +skinparam database<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor ELEMENT_FONT_COLOR + BackgroundColor SYSTEM_BG_COLOR + BorderColor #3C7FC0 +} + +skinparam database<> { + StereotypeFontColor ELEMENT_FONT_COLOR + FontColor ELEMENT_FONT_COLOR + BackgroundColor EXTERNAL_SYSTEM_BG_COLOR + BorderColor #8A8A8A +} + +' Layout +' ################################## + +!definelong LAYOUT_WITH_LEGEND +hide stereotype +legend right +|= |= Type | +| | person | +| | external person | +| | system | +| | external system | +endlegend +!enddefinelong + +' Elements +' ################################## + +!define Person(e_alias, e_label) rectangle "==e_label" <> as e_alias +!define Person(e_alias, e_label, e_descr) rectangle "==e_label\n\n e_descr" <> as e_alias + +!define Person_Ext(e_alias, e_label) rectangle "==e_label" <> as e_alias +!define Person_Ext(e_alias, e_label, e_descr) rectangle "==e_label\n\n e_descr" <> as e_alias + +!define System(e_alias, e_label) rectangle "==e_label" <> as e_alias +!define System(e_alias, e_label, e_descr) rectangle "==e_label\n\n e_descr" <> as e_alias + +!define System_Ext(e_alias, e_label) rectangle "==e_label" <> as e_alias +!define System_Ext(e_alias, e_label, e_descr) rectangle "==e_label\n\n e_descr" <> as e_alias + +!define SystemDb(e_alias, e_label) database "==e_label" <> as e_alias +!define SystemDb(e_alias, e_label, e_descr) database "==e_label\n\n e_descr" <> as e_alias + +!define SystemDb_Ext(e_alias, e_label) database "==e_label" <> as e_alias +!define SystemDb_Ext(e_alias, e_label, e_descr) database "==e_label\n\n e_descr" <> as e_alias + +' Boundaries +' ################################## + +!define Enterprise_Boundary(e_alias, e_label) Boundary(e_alias, e_label, "Enterprise") +!define System_Boundary(e_alias, e_label) Boundary(e_alias, e_label, "System") diff --git a/docs/images/c4-plantuml/LICENSE b/docs/images/c4-plantuml/LICENSE new file mode 100644 index 0000000..ea7d489 --- /dev/null +++ b/docs/images/c4-plantuml/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2018 Ricardo Niepel + +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.