crystal-facet-uml Architecture

About this Document:
(C) We acknowledge that this document uses material from the arc 42 architecture template, http://www.arc42.de. Created by Dr. Peter Hruschka & Dr. Gernot Starke.

This Document C0161

describes
- the challenge to be solved
- the selected solution
- the decisions and considered alternatives

Introduction and Goals

crystal-facet-uml creates sysml/uml diagrams to document system and software architecture.
As software architect, you create a set of diagrams describing use-cases, requirements, structural views, behavioral and deployment views.
This diagram shows the use-cases that crystal-facet-uml addresses.

Design consistent architecture diagrams C0008

The main goal of crystal facet uml is to create a set of consistent uml diagrams. Diagrams help in desinging a system that satisfies a set of requirements and decomposes the system into smaller entities.
Consistency encompasses:
- Consistent relations between objects
- Consistent naming of objects
- Consistent locations of objects in diagrams

check what items to integrate --> SW Integrator R0036

understand interfaces to test --> SW Integration Tester R0037

cluster items of same lifecycle --> Configuration Manager R0038

discuss what to create --> SW Developer R0039

primary actor --> SW Architect R0773

SW Architect C0046

create diagrams --> crystal-facet-uml application R0649

Configuration Manager C0047

SW Developer C0048

A software developer understands the requirements and architecture; creates the software parts and performs reviews and unit-tests.

SW Integrator C0049

SW Integration Tester C0050

Understand Problem C0158

Understand
- Use Cases
- Requirements
- Quality Goals

actor --> SW Architect R0774

crystal-facet-uml application C0178

--> Design consistent architecture diagrams R0652

Use Cases on Diagrams

This diagram lists the main features of crystal facet uml.

Show Classifiers C0009

Classifiers are drawn to diagrams one classifier is visible in one or multiple diagrams

--> Show multiple instances in same diagram R0058

--> Mark Classifiers R0061

--> Classifier has relations R0062

--> Classifier is implicit instance R0795

--> Classifier is explicit instance R0796

Classifier is contained (child) C0010

A Classifier can either exist stand-alone or be a sub-element of another classifier.

Show multiple instances in same diagram C0011

One and the same classifier can be shown in a diagram multiple times (either as class/type or as instance)

Classifier has relations C0012

A classifier can have zero, one or many relations; these may be of one or of differnet types. Circular dependencies may be forbidden if semantics undefined.

--> Classifier is contained (child) R0063

Mark Classifiers C0013

A classifier can be highlighted in one or several diagrams. The highlighting may be different in different diagrams where the classifier is shown.

highlight: F0007

grey out: F0008

Classifier is explicit instance C0014

A classifier can be an explicitly modelled instance of another classifier

Classifier is implicit instance C0015

A classifier can represent an anonymous (implicit) instance without defining an explicit instance relation

Diagrams are hierarchical C0016

There is one root diagram. All other diagrams shall have a parent diagram.

Draw Diagrams C0031

--> Show Classifiers R0057

--> Diagrams are hierarchical R0794

crystal-facet-uml application C0178

--> Classifier is explicit instance R0785

--> Classifier is contained (child) R0786

--> Classifier is implicit instance R0787

--> Classifier has relations R0788

--> Show Classifiers R0789

--> Mark Classifiers R0790

--> Show multiple instances in same diagram R0791

--> Diagrams are hierarchical R0792

--> Draw Diagrams R0793

Use Cases on Data Model

During development, new use cases are identified.

Use identical classifier in multiple diagrams C0233

Provide means to use the identical classifier in multiple diagrams

Search Classifiers, find diagrams C0259

All model elements must be visible C0467

Whatever elements are stored in the model, these must be visible in some diagram. Otherwise 1) these cannot be reviewed and
2) their intention is unclear.

Design consistent architecture diagrams C0008

The main goal of crystal facet uml is to create a set of consistent uml diagrams. Diagrams help in desinging a system that satisfies a set of requirements and decomposes the system into smaller entities.
Consistency encompasses:
- Consistent relations between objects
- Consistent naming of objects
- Consistent locations of objects in diagrams

--> All model elements must be visible R0746

--> Use identical classifier in multiple diagrams R0747

crystal-facet-uml application C0178

--> Design consistent architecture diagrams R0652

--> Search Classifiers, find diagrams R0782

--> Use identical classifier in multiple diagrams R0783

--> All model elements must be visible R0784

Export Use Cases

Export diagrams C0232

Export diagrams for use in architecture Documents.

Export document C0320

--> Export diagrams R0456

Export model C0319

The model can be exported in a machine-readable format.

Export (Model and/or Diagrams) C0347

--> Export diagrams R0495

--> Export document R0496

--> Export model R0497

crystal-facet-uml application C0178

--> Export model R0777

--> Export document R0779

--> Export diagrams R0780

--> Export (Model and/or Diagrams) R0781

Import/Sync Use Cases

data exchange with external scripts C0370

--> Export model R0608

--> Import model R0611

git support C0371

The model shall be stored in git in a way that git blame shows changed data entries, git merge can automatically merge git mergetool allows to manually merge

--> Export model R0609

--> Import model R0610

Export model C0319

The model can be exported in a machine-readable format.

Import model C0408

The model can be imported from a machine-readable data format.
Supported modes are:

- Import all elements to an empty database
- Import only new elements, ignore existing and deleted elements (or notify on modifications)
Unsupported modes are:

- Import new elements, overwrite existing elements, ignore deleted elements
- Import new elements, overwrite existing elements, delete missing elements
- 3-Way merge
The unsupported use cases have to be solved by external scripts if needed. A possible solution may be to a) export all elements, b) modify the export, c) import all elements to a new, empty database.

crystal-facet-uml application C0178

--> data exchange with external scripts R0775

--> git support R0776

--> Export model R0777

--> Import model R0778

Constraints

Standards: UML, SysML C0162

crystal-facet-uml shall draw diagrams that are compliant (subset) to UML or SysML.

Output: png, svg, pdf, ps, txt / db, xhtml, xmi C0163

crystal-facet-uml shall produce output suitable to be processed by text layout engines:
- latex
- docbook
- doxygen
- html

Interoperability C0189

crystal-facet-uml has its strenghts. Providing a full-featured text layout engine is not one of them.
Therefore it is important to be interoperable with text layout engines like
- latex
- docbook
- markdown, asciidoc, doxygen

UML/SysML Overview

This diagram shows an overview on UML and aims to explain what parts are available in crystal-facet-uml and how this is mapped to the crystal-facet-uml database.

MOF (M3) C0111

UML (M2) C0112

--> MOF (M3) R0152

User Model (M1) C0113

--> UML (M2) R0151

Objects of Reality (M0) C0114

--> User Model (M1) R0150

SysML (M2) C0190

--> MOF (M3) R0248

<<include>> --> UML (M2) R0249

MOF Overview

This diagram shows a selection of MOF meta classes.

MOF::Class C0115

MOF::Feature C0116

MOF::Association C0117

This diagram shows some example classes of the MOF Meta Model.

MOF (M3) C0111

--> MOF::Class R0153

--> MOF::Feature R0154

--> MOF::Association R0155

Base classes of UML

This diagram shows the base classes of the UML

UML (M2) C0112

--> UML::Image R0690

--> UML::Comment R0157

--> UML::Relationship R0158

--> UML::DirectedRelationship R0159

--> UML::Element R0156

--> UML::Classifier R0177

--> UML::Feature R0178

UML::Element C0118

ownedComment --> UML::Comment R0160

ownedElement --> UML::Element R0161

UML::Comment C0119

--> UML::Element R0162

annotatedElement (0..*) --> UML::Element R0439

UML::Relationship C0120

--> UML::Element R0163

UML::DirectedRelationship C0121

--> UML::Relationship R0164

UML::Classifier C0125

UML::Feature C0129

featuringClassifier --> UML::Classifier R0176

UML::Image C0441

--> UML::Element R0691

UML Classifier Ancestors

description: see http://www.omg.org/spec/UML/2.5

UML::TemplateableElement C0122

description: see http://www.omg.org/spec/UML/2.5

--> UML::Element R0170

UML::Type C0123

description: see http://www.omg.org/spec/UML/2.5

--> UML::PackageableElement R0173

UML::Namespace C0124

description: see http://www.omg.org/spec/UML/2.5

--> UML::NamedElement R0172

UML::Classifier C0125

--> UML::Namespace R0165

--> UML::TemplateableElement R0166

--> UML::Type R0167

--> UML::RedefinableElement R0168

UML::RedefinableElement C0126

description: see http://www.omg.org/spec/UML/2.5

--> UML::NamedElement R0169

UML::NamedElement C0127

description: see http://www.omg.org/spec/UML/2.5

--> UML::Element R0171

UML::Element C0118

ownedElement --> UML::Element R0161

UML::PackageableElement C0128

description: see http://www.omg.org/spec/UML/2.5

--> UML::NamedElement R0174

UML Structural Elements (Non-Classifiers)

UML::PackageableElement C0128

description: see http://www.omg.org/spec/UML/2.5

--> UML::NamedElement R0174

UML::Namespace C0124

description: see http://www.omg.org/spec/UML/2.5

--> UML::NamedElement R0172

UML::TemplateableElement C0122

description: see http://www.omg.org/spec/UML/2.5

UML::Package C0252

--> UML::PackageableElement R0343

--> UML::Namespace R0342

--> UML::TemplateableElement R0344

UML::NamedElement C0127

description: see http://www.omg.org/spec/UML/2.5

UML::Artifact C0253

--> UML::DeployedArtifact R0345

UML::DeployedArtifact C0254

--> UML::NamedElement R0346

UML::DeploymentTarget C0255

--> UML::NamedElement R0347

UML::Node C0256

--> UML::DeploymentTarget R0348

UML Structure: Classifier Descendants

UML::Classifier C0125

UML::Interface C0137

--> UML::Classifier R0188

UML::StructuredClassifier C0138

--> UML::Classifier R0189

UML::EncapsulatedClassifier C0139

--> UML::StructuredClassifier R0190

UML::Class C0140

--> UML::EncapsulatedClassifier R0191

--> UML::BehavioredClassifier R0192

UML::BehavioredClassifier C0141

--> UML::Classifier R0193

UML::Component C0142

--> UML::Class R0194

UML::Stereotype C0442

--> UML::Class R0692

icon --> UML::Image R0693

UML::Image C0441

UML::Node C0256

--> UML::Class R0694

UML Classifier Behavioral Descendants

UML::Activity C0145

--> UML::Behavior R0196

UML::Behavior C0144

--> UML::Class R0197

UML::Class C0140

--> UML::EncapsulatedClassifier R0191

--> UML::BehavioredClassifier R0192

UML::BehavioredClassifier C0141

--> UML::Classifier R0193

UML::StructuredClassifier C0138

--> UML::Classifier R0189

UML::EncapsulatedClassifier C0139

--> UML::StructuredClassifier R0190

UML::Classifier C0125

--> UML::RedefinableElement R0168

UML::Actor C0147

--> UML::BehavioredClassifier R0199

UML::State C0143

--> UML::RedefinableElement R0195

UML::RedefinableElement C0126

description: see http://www.omg.org/spec/UML/2.5

UML::UseCase C0146

--> UML::BehavioredClassifier R0198

UML Feature Ancestors

UML::Element C0118

ownedElement --> UML::Element R0161

UML::RedefinableElement C0126

description: see http://www.omg.org/spec/UML/2.5

--> UML::NamedElement R0169

UML::NamedElement C0127

description: see http://www.omg.org/spec/UML/2.5

--> UML::Element R0171

UML::Classifier C0125

--> UML::RedefinableElement R0168

UML::Feature C0129

--> UML::RedefinableElement R0175

featuringClassifier --> UML::Classifier R0176

UML Feature Descendants

UML::Feature C0129

UML::StructuralFeature C0130

--> UML::Feature R0179

UML::BehavioralFeature C0131

--> UML::Feature R0180

UML::Property C0132

--> UML::StructuralFeature R0182

UML::Operation C0133

--> UML::BehavioralFeature R0181

UML::NamedElement C0127

description: see http://www.omg.org/spec/UML/2.5

UML::LifeLine C0134

--> UML::NamedElement R0183

UML::Port C0135

--> UML::Property R0184

UML Relationships

UML::DirectedRelationship C0121

UML::Usage C0480

--> UML::DirectedRelationship R0800

UML::Abstraction C0481

--> UML::DirectedRelationship R0798

UML::Deployment C0482

--> UML::DirectedRelationship R0799

Selected classes of SysML

SysML (M2) C0190

--> ConstraintProperty R0250

ConstraintProperty C0191

Context And Scope

version control system C0165

requirements engineering C0166

source code documentation C0167

user documentation C0168

high quality layouted documentation C0169

There are good layout engines to create high quality pdf pages, like:
- latex
- docbook

tests C0170

unit-tests, integration tests, qualification tests, regression tests

project management C0171

risk management C0172

configuration management C0173

--> version control system R0229

SW Architect C0046

create diagrams --> crystal-facet-uml application R0649

Configuration Manager C0047

do --> configuration management R0230

SW Developer C0048

A software developer understands the requirements and architecture; creates the software parts and performs reviews and unit-tests.

do --> source code documentation R0233

SW Integrator C0049

SW Integration Tester C0050

do --> tests R0234

crystal-facet-uml application C0178

provide input --> high quality layouted documentation R0650

Solution Strategy

During operation, crystal-facet-uml runs as application based on the libraries sqlite and gtk.

crystal-facet-uml application C0178

sqlite3 C0007

SQL database

gtk3/gtk4 C0005

Toolkit which provides
- Windows and Widgets
- User Input handling

technical strategy C0185

crystal-facet-uml shall be portable, therefore as few as possible 3rd party libraries shall be linked against:
- To store the data, the sqlite database is used.
- To interact with the user, gtk is used.

--> crystal-facet-uml application R0244

--> gtk3/gtk4 R0245

--> sqlite3 R0246

user interface strategy C0186

The user shall
- focus on the semantics of the diagrams, not on the layout
- be able to order classifiers left-to-right and top-to-bottom
- be forced to use the same elements in different diagrams
crystal-facet-uml shall
- auto-layout classifier locations and sizes,
- auto-layout features and relationships
- hide the meta-model from the user

--> crystal-facet-uml application R0247

Development View: Tools

This diagram shows the tools for designing, implementing, documenting, configuring and building the software.

git C0022

version control system

manages --> c + doxygen + docbook R0054

cmake C0023

cmake and cpack are meta-build files which generate e.g. make files, rpm and deb package files.

make: build dependency handler: F0001

gcc/mingw: compiler: F0003

pack items --> deb, rpm R0312

c + doxygen + docbook C0024

c code and doxygen are the source code and documentation formats

feeds --> cmake R0007

crystal facet uml C0025

- drafts the software design (using this crystal facet uml tool which is under construction)

defines --> c + doxygen + docbook R0006

deb, rpm C0234

sign: F0057

Building Block View

This diagram shows the layering of the main software modules.
Concept for Multithreading: In general, all modules shall work in a multithreaded environment.
- The gui module requires own data structures in order to be thread-safe and relies on the base libraries gtk, gdk which need to support multi-threading,
- The pencil module requires own data structures in order to be thread safe and relies on the base libraries pango and cairo which need to support multi-threading.
- The data module does not need own data structures, it comes with a module-wide lock in the database_t structure.
- The ctrl module requires own data structures in order to be thread safe. This limitation would need to be changed if a multi-threaded gui should access a single ctrl and data instance. (Currently, the software is single-threaded)

gui C0001

- allows a user - to select the database - to export diagrams - to modify the uml-model

uses --> ctrl R0009

uses --> data/storage R0010

layout/draw --> pencil R0530

export --> io R0532

pencil C0002

- renders diagrams to cairo drawing contexts
- highlights uml-elements as requested by the gui module

pencil_diagram_maker: F0084

uses --> data/storage R0011

ctrl C0003

- provides write access to the database
- ensures consistency of the uml-model, e.g. no circular contains-relations, no lifelines if no corresponding diagramelement exists

uses --> data/storage R0012

data/storage C0004

- provides read access to ctrl, pencil and gui components
- provides write acccess to only the ctrl component
- ensures low-level consistency of database: all referenced objects exist.
- sends notifications on changes

crystal-facet-uml application C0178

--> gui R0239

--> pencil R0240

--> ctrl R0241

--> data/storage R0242

--> io R0255

--> data R0314

io C0195

file output: IF: F0075

file input: IF: F0095

clipboard in: IF: F0074

clipboard out: IF: F0096

export_trigger: F0085

uses --> data/storage R0258

uses --> ctrl R0392

layout/draw --> pencil R0531

data C0235

--> data/storage R0313

data: Black Box View

data/storage C0004

- provides read access to ctrl, pencil and gui components
- provides write acccess to only the ctrl component
- ensures low-level consistency of database: all referenced objects exist.
- sends notifications on changes

data C0235

--> data/storage R0313

data: White Box View

This diagram shows the main classes in the data package.

data_database C0037

- wraps the sqlite database
- knows the current status and filename
- opens and closes the database
- manages the list of listeners and notifies changes

data_database _reader C0038

- reads data from the database

has --> data_database R0028

data_database _writer C0039

- writes changes to the database
- ensures low-level consistency of the database, e.g. all foreign keys point to existing rows (referential integrity)
- retrieves the old, changed values for the undo/redo list

uses --> data_database _reader R0027

has --> data_database R0029

data/storage C0004

- provides read access to ctrl, pencil and gui components
- provides write acccess to only the ctrl component
- ensures low-level consistency of database: all referenced objects exist.
- sends notifications on changes

--> data_database _writer R0040

--> data_database _reader R0041

--> data_database R0042

data C0235

--> data/storage R0313

Database Structure

This diagram shows the tables and relationships of the database.

classifiers C0080

id: int64_t: F0012

main_type: enum: F0017

stereotype: F0018

name: F0019

description: F0020

--> features R0210

relationships C0081

id: int64_t: F0014

main_type: enum: F0021

name: F0022

description: F0023

from --> classifiers R0096

to --> classifiers R0097

from --> features R0205

to --> features R0206

diagramelements C0082

id: int64_t: F0016

display_flags: F0031

--> diagrams R0100

--> classifiers R0101

focused_feature --> features R0204

to select one of possibly several lifelines

features C0083

id: int64_t: F0013

main_type: enum: F0024

key (name): F0025

value (type): F0026

description: F0027

diagrams C0084

id: int64_t: F0015

diagram_type: enum: F0028

name: F0029

description: F0030

parent --> diagrams R0099

data/storage C0004

- provides read access to ctrl, pencil and gui components
- provides write acccess to only the ctrl component
- ensures low-level consistency of database: all referenced objects exist.
- sends notifications on changes

--> diagrams R0266

--> diagramelements R0267

--> classifiers R0268

--> relationships R0269

--> features R0270

JSON Storage Format

git merge C0361

git mergetool (manual) C0362

git blame C0363

Disambiguation of non-unique IDs C0368

Disambiguation of non-unique IDs of
- classifiers
- features
- relationships
- diagrams
- diagramelements

--> git merge R0516

human readable foreign keys C0369

Foreign keys shall be human readable. Therefore not only uuids but also the classifier names are stated in the json files.

--> git mergetool (manual) R0518

data exchange with external scripts C0370

git support C0371

The model shall be stored in git in a way that git blame shows changed data entries, git merge can automatically merge git mergetool allows to manually merge

--> git blame R0519

--> git merge R0520

--> git mergetool (manual) R0521

line-based data entries C0372

--> git support R0523

Constant order for unchanged parts C0420

When merging two text files that have parts in common (the unchanged parts), then it is important that these unchanged parts occur in the same order in both files. (Implemented in 1.45.0)

--> git merge R0641

data: Runtime View

thread-1 C0241

open --> data_database R0320

init(:data_database) --> r1 :data_data base_reader R0326

init(:data_database, r1) --> data_database _writer R0324

get_diagram --> r1 :data_data base_reader R0332

get_classifier --> r1 :data_data base_reader R0333

set_feature --> data_database _writer R0334

destroy --> data_database _writer R0325

destroy --> r1 :data_data base_reader R0329

close --> data_database R0321

thread-2 C0242

init(:data_database) --> r2 :data_data base_reader R0327

get_diagram --> r2 :data_data base_reader R0330

get_classifier --> r2 :data_data base_reader R0331

destroy --> r2 :data_data base_reader R0328

data_database C0037

- wraps the sqlite database
- knows the current status and filename
- opens and closes the database
- manages the list of listeners and notifies changes

data_database _writer C0039

- writes changes to the database
- ensures low-level consistency of the database, e.g. all foreign keys point to existing rows (referential integrity)
- retrieves the old, changed values for the undo/redo list

get_feature --> r1 :data_data base_reader R0335

get_database_ptr --> data_database R0340

--> thread-1 R0337

r1 :data_data base_reader C0244

get_database_ptr --> data_database R0338

--> data_database _writer R0336

r2 :data_data base_reader C0245

In the current implementation, the software runs single-threaded.
If running multiple threads, a possible implementation is that the data_database object exists just once and provides an sqlite3 connection object in SQLITE_CONFIG_SERIALIZED mode (see https://sqlite.org/threadsafe.html ) Every thread gets its own readers and writers (to separate the statements-with-bound-variables and statement-string-buffers)
There is a chance that thread-2 performs multiple independant queries while thread-1 performs a write transaction. This is expected to not cause a problem, given the current sequences of statements.

get_database_ptr --> data_database R0339

Locks needed here C0425

The data_database_writer can handle only one client-thread at a time.

--> data_database _writer R0659

ctrl: Black Box View

ctrl C0003

- provides write access to the database
- ensures consistency of the uml-model, e.g. no circular contains-relations, no lifelines if no corresponding diagramelement exists

uses --> data/storage R0012

data C0235

--> data/storage R0313

data/storage C0004

- provides read access to ctrl, pencil and gui components
- provides write acccess to only the ctrl component
- ensures low-level consistency of database: all referenced objects exist.
- sends notifications on changes

ctrl: White Box View

This diagram shows the main classes in the ctrl package.

ctrl_controller C0040

- changes the database contents
- maintains the undo redo list

has --> ctrl_consistency_checker R0030

has --> ctrl_undo_redo_list R0213

has --> ctrl_ classifier_ controller R0216

has --> ctrl_ diagram_ controller R0218

ctrl_consistency_checker C0041

- checks and repairs a database

ctrl C0003

- provides write access to the database
- ensures consistency of the uml-model, e.g. no circular contains-relations, no lifelines if no corresponding diagramelement exists

--> ctrl_controller R0043

--> ctrl_consistency_checker R0044

--> ctrl_multi_step_changer R0605

--> ctrl_ classifier_ trigger R0221

--> consistency R0732

--> ctrl_ diagram_ controller R0217

--> ctrl_ classifier_ controller R0215

--> ctrl_undo_redo_list R0211

--> ctrl_ diagram_ trigger R0212

ctrl_undo_redo_list C0153

manages a list of actions to be undone or/and redone.
When performing undo or redo operations, this is done directly to the data_database_writer_t, not to the ctrl_controller which could start an endless-recursion.

db_writer: F0113

db_reader: F0114

ctrl_ diagram_ trigger C0154

ensures that application level policies on the model are adhered whenever diagrams are modified.

post_update_diagram_type: F0109

post_create_diagramelement: F0110

post_delete_diagramelement: F0111

--> consistency R0733

ctrl_ classifier_ controller C0155

performs changes on classifier, feature and relationship tables

calls --> ctrl_ classifier_ trigger R0738

ctrl_ diagram_ controller C0156

performs changes on diagram and diagramelement tables

calls --> ctrl_ diagram_ trigger R0219

ctrl_ classifier_ trigger C0157

ensures that application level policies on the model are adhered whenever classifiers are modified.

post_delete_feature: F0112

after deleting a lifeline, all references from diagramelements have to be removed.

--> consistency R0734

ctrl_multi_step_changer C0407

performs multi-step operations:

- delete a set of objects
- try create either with proposed or with auto-generated id

calls --> ctrl_ diagram_ controller R0606

calls --> ctrl_ classifier_ controller R0607

consistency C0469

calls --> ctrl_ classifier_ controller R0735

ctrl: consistency

consis tency_ drop_ invisibles C0468

This class cares about deleting model elements that are not visible anymore.

--> ARC_NO_INVISIBLE_CLASSIFIERS R0749

--> ARC_NO_INVISIBLE_RELATIONSHIPS R0750

consis tency_ lifeline C0470

This class cares about creating and deleting lifelines depending on the surrounding diagram type.

--> ARC_LIFELINES_AT_INTERACTIONS R0745

consistency C0469

--> consis tency_ drop_ invisibles R0736

--> consis tency_ lifeline R0737

ARC_LIFELINES_AT_INTERACTIONS C0476

Lifelines shall exist for all elements in interaction diagrams. Lifelines shall not exist for any element in non-interaction diagrams.
Rationale: Lifelines shall be managed (created/deleted) by crystal-facet-uml automatically. Lifelines are visible only in interaction diagrams, so they have to be deleted in non-interaction diagrams.

--> All model elements must be visible R0748

All model elements must be visible C0467

Whatever elements are stored in the model, these must be visible in some diagram. Otherwise 1) these cannot be reviewed and
2) their intention is unclear.

ctrl C0003

- provides write access to the database
- ensures consistency of the uml-model, e.g. no circular contains-relations, no lifelines if no corresponding diagramelement exists

--> consis tency_ drop_ invisibles R0729

--> consistency R0732

ARC_NO_INVISIBLE_CLASSIFIERS C0477

When there is no diagram showing a classifier, this classifier shall not exist.

--> All model elements must be visible R0751

ARC_NO_INVISIBLE_RELATIONSHIPS C0478

When there is no diagram showing a relationship, this relationship shall not exist.

--> All model elements must be visible R0752

consistency sequence

ctrl_ diagram_ controller C0156

performs changes on diagram and diagramelement tables

post_update_diagram_type --> ctrl_ diagram_ trigger R0758

--> consis tency_ lifeline R0761

--> consis tency_ lifeline R0771

--> gui R0767

ctrl_ classifier_ controller C0155

performs changes on classifier, feature and relationship tables

post_delete_feature --> ctrl_ classifier_ trigger R0756

--> consis tency_ lifeline R0764

--> consis tency_ lifeline R0770

ctrl_ diagram_ trigger C0154

ensures that application level policies on the model are adhered whenever diagrams are modified.

delete_lifelines --> consis tency_ lifeline R0753

create_lifelines --> consis tency_ lifeline R0754

--> ctrl_ diagram_ controller R0766

ctrl_ classifier_ trigger C0157

ensures that application level policies on the model are adhered whenever classifiers are modified.

unlink_lifeline --> consis tency_ lifeline R0755

--> ctrl_ classifier_ controller R0763

consis tency_ drop_ invisibles C0468

This class cares about deleting model elements that are not visible anymore.

consis tency_ lifeline C0470

This class cares about creating and deleting lifelines depending on the surrounding diagram type.

delete_feature --> ctrl_ classifier_ controller R0759

update_diagramelement_focused_feature_id --> ctrl_ diagram_ controller R0760

--> ctrl_ classifier_ trigger R0762

--> ctrl_ diagram_ trigger R0765

create_feature --> ctrl_ classifier_ controller R0768

update_diagramelement_focused_feature_id --> ctrl_ diagram_ controller R0769

--> ctrl_ diagram_ trigger R0772

gui C0001

- allows a user - to select the database - to export diagrams - to modify the uml-model

update_diagram_type --> ctrl_ diagram_ controller R0757

re-entrance by recursion C0479

--> consis tency_ lifeline R0797

pencil: Black Box View

pencil C0002

- renders diagrams to cairo drawing contexts
- highlights uml-elements as requested by the gui module

pencil_diagram_maker: F0084

uses --> data/storage R0011

data C0235

--> data/storage R0313

data/storage C0004

- provides read access to ctrl, pencil and gui components
- provides write acccess to only the ctrl component
- ensures low-level consistency of database: all referenced objects exist.
- sends notifications on changes

pencil: White Box View

This diagram shows the main classes in the pencil package.

pencil_diagram_maker C0032

- coordinates layouting and drawing of a diagram
- implements kind of front controller pattern: all requests from gui to pencil are addressed to the pencil_diagram_maker

uses --> pencil_xxx_layouter R0023

uses --> pencil_xxx_painter R0024

pencil_xxx_layouter C0033

- layouts multiple elements within the bounds of a diagram
- can convert abstract order-values to x/y coordinates and vice versa

modifies --> pencil_layout_data R0022

asks for sizes --> pencil_xxx_painter R0034

pencil_xxx_painter C0034

- knows the bounding boxes of single elements
- draws single graphical elements

requires --> pencil_layout_data R0025

use --> pencil.draw R0702

data_visible_set C0035

- caches data from the database needed to draw a diagram

pencil_layout_data C0036

- stores locations of layouted elements (in the current diagram)

references --> data_visible_set R0021

pencil C0002

- renders diagrams to cairo drawing contexts
- highlights uml-elements as requested by the gui module

pencil_diagram_maker: F0084

--> pencil.draw R0282

--> pencil_diagram_maker R0049

--> pencil_xxx_painter R0051

--> data_visible_set R0052

--> pencil_layout_data R0053

--> pencil_xxx_layouter R0056

--> pencil.layout R0265

--> pencil_diagram_maker R0651

pencil.layout C0196

pencil.draw C0205

Encapulates drawing routines for
- geometric objects
- labels
- symbols/icons

pencil detailed structure

pencil_xxx_painter C0034

- knows the bounding boxes of single elements
- draws single graphical elements

--> pencil_diagram_painter R0137

--> pencil_feature_painter R0138

--> pencil_relationship_painter R0139

--> pencil_classifier_composer R0136

requires --> pencil_layout_data R0025

pencil_xxx_layouter C0033

- layouts multiple elements within the bounds of a diagram
- can convert abstract order-values to x/y coordinates and vice versa

--> pencil_classifier_layouter R0133

--> pencil_relationship_layouter R0135

--> pencil_layouter R0132

--> pencil_feature_layouter R0134

modifies --> pencil_layout_data R0022

asks for sizes --> pencil_xxx_painter R0034

pencil_layout_data C0036

- stores locations of layouted elements (in the current diagram)

references --> data_visible_set R0021

data_visible_set C0035

- caches data from the database needed to draw a diagram

pencil_layouter C0098

- layouts multiple elements within the bounds of a diagram
- layouting is implemented in two steps: 1) defining a grid which associates abstract ordering data to diagram coordinates and 2) assigning elements to coordinates

--> pencil_classifier_layouter R0632

--> pencil_feature_layouter R0633

--> pencil_relationship_layouter R0634

pencil_classifier_layouter C0099

pencil_feature_layouter C0100

pencil_relationship_layouter C0101

pencil_classifier_composer C0102

pencil_diagram_painter C0103

--> pencil_classifier_composer R0635

--> pencil_feature_painter R0636

--> pencil_relationship_painter R0637

pencil_feature_painter C0104

pencil_relationship_painter C0105

pencil.layout package

pencil.layout C0196

--> layout_feature R0262

--> layout _visible_classifier R0263

--> layout_diagram R0261

--> layout _relationship R0264

layout_diagram C0200

bounds: rect: F0044

draw_area: rect: F0045

layout_feature C0201

bounds: rect: F0049

label_box: rect: F0053

--> features R0281

layout _visible_classifier C0202

bounds: rect: F0048

space: rect: F0050

label_box: rect: F0052

--> visible_classifier R0280

--> layout_feature R0294

layout _relationship C0203

visible: enum: F0046

shape: connector: F0047

label_box: rect: F0051

data --> relationships R0272

from --> layout _visible_classifier R0273

to --> layout _visible_classifier R0274

from --> layout_feature R0275

to --> layout_feature R0293

classifiers C0080

id: int64_t: F0012

main_type: enum: F0017

stereotype: F0018

name: F0019

description: F0020

--> features R0210

features C0083

id: int64_t: F0013

main_type: enum: F0024

key (name): F0025

value (type): F0026

description: F0027

relationships C0081

id: int64_t: F0014

main_type: enum: F0021

name: F0022

description: F0023

from --> classifiers R0096

to --> classifiers R0097

from --> features R0205

to --> features R0206

visible_classifier C0204

--> classifiers R0278

pencil: Runtime View

This diagram shows the different entry points for layouting and rendering a diagram.

pencil::start C0269

--> gui/io select operations R0371

pencil::draw C0270

--> pencil::finish R0377

pencil::define grid C0271

implemented in pencil_diagram_maker

--> pencil::layout elements R0375

pencil::layout elements C0272

implemented in pencil_diagram_maker

--> pencil::draw R0376

gui/io select operations C0273

layout and draw everything --> pencil::define grid R0372

while dragging, layout and draw --> pencil::layout elements R0373

if layout know, draw only --> pencil::draw R0374

pencil::finish C0274

pencil::activities C0312

--> gui/io select operations R0440

--> pencil::start R0441

--> pencil::draw R0442

--> pencil::layout elements R0443

--> pencil::define grid R0444

--> pencil::finish R0445

Layouting Steps

pencil::layout elements C0272

implemented in pencil_diagram_maker

--> pencil::begin R0381

--> pencil::classifier_layouter layout_* R0378

--> pencil::feature_layouter do_layout R0379

--> pencil::feat_label_layouter do_layout R0388

--> pencil::relationship_layouter layout_* R0380

--> pencil::rel_label_layouter do_layout R0387

--> pencil::end R0382

--> Layouting Algorithm R0507

pencil::define grid C0271

implemented in pencil_diagram_maker

--> pencil::layout elements R0375

pencil::classifier_layouter layout_* C0275

--> pencil::feature_layouter do_layout R0384

pencil::feature_layouter do_layout C0276

--> pencil::relationship_layouter layout_* R0385

pencil::relationship_layouter layout_* C0277

--> pencil::feat_label_layouter do_layout R0389

pencil::begin C0278

--> pencil::classifier_layouter layout_* R0383

pencil::end C0279

pencil::rel_label_layouter do_layout C0280

--> pencil::end R0391

pencil::feat_label_layouter do_layout C0281

--> pencil::rel_label_layouter do_layout R0390

Layouting Algorithm C0358

pencil: Crosscutting Concepts

Whenever one of several layouting solutions shall be selected, the following algorithm applies.
This algorithm is a greedy algorithm which is efficient and finds a local maximum but may miss the overall optimum layout solution.

layouting:start C0353

--> propose processing order R0498

layouting:finish C0354

propose processing order C0355

For the list of elements to be layouted, define the processing order.

--> propose solutions R0501

propose solutions C0356

This step creates a set of possible solutions for 1 element to be layouted.

--> select solution R0499

select solution C0357

This step selects the most promising of solutions for 1 element to be layouted.

--> end of list? R0509

Layouting Algorithm C0358

--> end of list? R0508

--> propose processing order R0502

--> propose solutions R0503

--> select solution R0504

--> layouting:finish R0505

--> layouting:start R0506

end of list? C0359

finished --> layouting:finish R0510

more elements --> propose solutions R0511

io: Black Box View

The io module imports and exports data and diagrams. Either the filesystem or the clipboard are source and destination.
With the io_data_file_t class, this module provides a wrapper around a database of the data module that can import/export json files when opening/closing the database.

io C0195

file output: IF: F0075

file input: IF: F0095

clipboard in: IF: F0074

clipboard out: IF: F0096

export_trigger: F0085

uses --> data/storage R0258

layout/draw --> pencil R0531

pencil C0002

- renders diagrams to cairo drawing contexts
- highlights uml-elements as requested by the gui module

pencil_diagram_maker: F0084

uses --> data/storage R0011

data C0235

--> data/storage R0313

data/storage C0004

- provides read access to ctrl, pencil and gui components
- provides write acccess to only the ctrl component
- ensures low-level consistency of database: all referenced objects exist.
- sends notifications on changes

io: White Box View

This component implements input output functionality, currently:
- Export of diagram images

io C0195

file output: IF: F0075

file input: IF: F0095

clipboard in: IF: F0074

clipboard out: IF: F0096

export_trigger: F0085

--> image_format_writer R0283

--> io_data_file R0631

--> documents R0419

--> io_exporter R0285

--> io_importer R0369

start export --> io_exporter R0368

paste --> io_importer R0370

cut/copy --> io_exporter R0566

import/sync --> io_importer R0567

image_format_writer C0206

io_exporter C0208

cases about
- file names
- traversing the diagram tree

--> image_format_writer R0287

--> documents R0423

io_importer C0268

documents C0306

documents implements several strategies to traverse the model and diagram trees. For each found element, an element writer is called.

io_data_file C0416

database: F0101

controller: F0102

io_export components

io_export_diagram_traversal C0307

This class traverses the model in the database. The diagram traversal walks along the diagram tree starting at the root. There are other traversal classes implementing other strategies.

use --> io_element_writer R0527

documents C0306

documents implements several strategies to traverse the model and diagram trees. For each found element, an element writer is called.

--> io_export_flat_traversal R0642

--> io_export_diagram_traversal R0420

--> io_export_diagram_traversal R0422

--> io_export_model_traversal R0421

io_export_model_traversal C0207

cares about
- selecting the model elements to export

use --> io_element_writer R0528

xhtml_element_writer (and xml/docbook) C0209

cares about
- writing output-format specific meta data
- using right "writer" class to encode data

use --> txt_writer R0432

use --> md_filter R0433

use --> xml_writer R0434

--> io_element_writer R0526

md/txt/xmi/xml/json C0282

--> xmi_element_writer R0425

--> io_element_writer R0524

--> json_element_writer R0645

--> md_filter R0430

--> xml_writer R0429

--> txt_writer R0428

--> xhtml_element_writer (and xml/docbook) R0424

xmi_element_writer C0308

use --> xml_writer R0431

--> io_element_writer R0525

txt_writer C0309

xml_writer C0310

md_filter C0311

io_element_writer C0373

This is the abstract base class of different writer objects.

io_export_flat_traversal C0421

use --> io_element_writer R0644

json_element_writer C0422

--> io_element_writer R0648

data_model_traversal

Constant order for unchanged parts C0420

When merging two text files that have parts in common (the unchanged parts), then it is important that these unchanged parts occur in the same order in both files. (Implemented in 1.45.0)

io_export_flat_traversal C0421

--> Constant order for unchanged parts R0643

use --> io_element_writer R0644

documents C0306

documents implements several strategies to traverse the model and diagram trees. For each found element, an element writer is called.

--> io_export_flat_traversal R0642

--> io_export_diagram_traversal R0420

--> io_export_diagram_traversal R0422

--> io_export_model_traversal R0421

io_export_model_traversal C0207

cares about
- selecting the model elements to export

use --> io_element_writer R0528

io_export_diagram_traversal C0307

This class traverses the model in the database. The diagram traversal walks along the diagram tree starting at the root. There are other traversal classes implementing other strategies.

use --> io_element_writer R0527

io_element_writer C0373

This is the abstract base class of different writer objects.

md/txt/xmi/xml/json C0282

--> io_element_writer R0524

io: Runtime View

The io_exporter sets up the data pipe

xhtml_element_writer (and xml/docbook) C0209

cares about
- writing output-format specific meta data
- using right "writer" class to encode data

5.) document artifacts --> md/txt/xmi/xml/json R0413

md/txt/xmi/xml/json C0282

6.) character stream --> Output Stream R0414

Output Stream C0305

data_database _reader C0038

- reads data from the database

1b) diagram data --> io_exporter R0417

3b) diagrams and model --> io_export_diagram_traversal R0438

io_exporter C0208

cases about
- file names
- traversing the diagram tree

1a) query diagrams --> data_database _reader R0416

2.) trigger --> io_export_diagram_traversal R0435

io_export_diagram_traversal C0307

This class traverses the model in the database. The diagram traversal walks along the diagram tree starting at the root. There are other traversal classes implementing other strategies.

3a) query diagrams and model --> data_database _reader R0436

4.) model data --> xhtml_element_writer (and xml/docbook) R0437

gui: Black Box View

gui C0001

- allows a user - to select the database - to export diagrams - to modify the uml-model

uses --> ctrl R0009

layout/draw --> pencil R0530

pencil C0002

- renders diagrams to cairo drawing contexts
- highlights uml-elements as requested by the gui module

pencil_diagram_maker: F0084

ctrl C0003

- provides write access to the database
- ensures consistency of the uml-model, e.g. no circular contains-relations, no lifelines if no corresponding diagramelement exists

gui: White Box View

This diagram shows the main classes in the gui package.

gui_main_window C0042

- represents an application window

has --> gui_toolbox R0226

has --> gui_attributes_editor R0228

--> gui_search_request R0354

has --> sketch R0545

--> gui_simple_message_to_user R0640

gui_window_manager C0045

- starts and stops application windows

has (1..3) --> gui_main_window R0033

gui C0001

- allows a user - to select the database - to export diagrams - to modify the uml-model

--> gui_search_request R0353

--> sketch R0349

--> gui_simple_message_to_user R0639

--> gui_toolbox R0225

--> gui_attributes_editor R0227

--> gui_window_manager R0045

--> gui_main_window R0046

gui_toolbox C0159

controller for the buttons in the tool bar:
- performs the callbacks when the user presses buttons
- switches between search, nav, edit and create mode

notify_listeners: F0087

set_selected_tool: F0086

--> gui_toolbox R0533

--> gui_toolbox R0534

gui_attributes_editor C0160

This class manages 5 widgets.
It reads the data of the currently focused object into cache, it writes back changes to the database (via the controller), it updates the visible widgets when the focused object or the data changes.
A challenge for implementation is, that on one hand, it implements the callback functions for 5 gtk widgets (which look independant if ignoring the internal implementation), on the other hand, it manages just one cached focused object (update on user-interaction, reload on change events).

name_entry: GtkEntry *: F0039

stereotype: GtkEntry *: F0042

type_combo_box: GtkComboBox *: F0040

description_text_view: GtkTextView *: F0041

commit_button: GtkButton *: F0043

object_changed: F0088

--> gui_attributes_editor R0535

sketch C0257

This component is the view and controller for the central sketch widget.
This includes the tree navigation bar and the search result list on the left.

gui_search_request C0258

This class manages
- a text entry widget so that the user can enter a search text
- a button that starts the search.
When a search is started, the gui_search_runner is triggered to execute it.

search_runner: gui_search_runner_t: F0083

gui_simple_message_to_user C0419

This class is the controller for the status bar widgets

gui search blocks

search_entry C0260

run --> gui_search _runner R0355

gui_search _runner C0261

--> gui_sketch _result_list R0356

gui_sketch _result_list C0262

sketch C0257

This component is the view and controller for the central sketch widget.
This includes the tree navigation bar and the search result list on the left.

--> gui_sketch _result_list R0357

gui_toolbox C0159

controller for the buttons in the tool bar:
- performs the callbacks when the user presses buttons
- switches between search, nav, edit and create mode

notify_listeners: F0087

set_selected_tool: F0086

activate_callback --> search_entry R0358

--> gui_toolbox R0533

--> gui_toolbox R0534

gui event notifications

gui_toolbox C0159

controller for the buttons in the tool bar:
- performs the callbacks when the user presses buttons
- switches between search, nav, edit and create mode

notify_listeners: F0087

set_selected_tool: F0086

--> gui_toolbox R0533

--> gui_toolbox R0534

--> gui_sketch_area R0539

gui_attributes_editor C0160

This class manages 5 widgets.
It reads the data of the currently focused object into cache, it writes back changes to the database (via the controller), it updates the visible widgets when the focused object or the data changes.
A challenge for implementation is, that on one hand, it implements the callback functions for 5 gtk widgets (which look independant if ignoring the internal implementation), on the other hand, it manages just one cached focused object (update on user-interaction, reload on change events).

name_entry: GtkEntry *: F0039

stereotype: GtkEntry *: F0042

type_combo_box: GtkComboBox *: F0040

description_text_view: GtkTextView *: F0041

commit_button: GtkButton *: F0043

object_changed: F0088

--> gui_attributes_editor R0535

sketch C0257

This component is the view and controller for the central sketch widget.
This includes the tree navigation bar and the search result list on the left.

--> gui_sketch_area R0350

--> gui_sketch _card R0351

--> gui_sketch_nav_tree R0546

gui_sketch_nav_tree C0374

gui_sketch _card C0044

- maintains the data of one diagram
- displays one diagram

gui_sketch_area C0043

Manages the main drawing area:
- layouts its subwidgets,
- loads data-sets from the database,
- reacts on key+button events,
- handles data-change events,
- controls selection-set
- encapsulates quite complex logic for mouse events

notify_listeners: IP-socket: F0094

tool_changed_callback: F0091

--> gui_sketch_area R0538

--> gui_toolbox R0541

--> gui_sketch_area R0543

--> gui_attributes_editor R0544

gui: Runtime View

search C0263

navigate C0264

edit C0265

create C0266

gui search sequence

search_entry C0260

run --> gui_search _runner R0363

gui_search _runner C0261

show_result_list --> sketch R0364

gui_sketch _result_list C0262

SW Architect C0046

enter search string --> search_entry R0362

search_start_callback --> search_entry R0361

sketch C0257

This component is the view and controller for the central sketch widget.
This includes the tree navigation bar and the search result list on the left.

load_data --> gui_sketch _result_list R0365

load data --> gui_sketch _card R0367

gui_sketch _card C0044

- maintains the data of one diagram
- displays one diagram

gui: Crosscutting Concepts

Widget States C0321

--> data available R0458

--> not-yet-layouted R0463

--> uninitialized R0457

--> layouted R0459

uninitialized C0322

load data --> data available R0460

data available C0323

--> invalid layout R0466

--> layouted R0464

--> not-yet-layouted R0465

invalidate --> uninitialized R0469

layouted C0324

draw (drawing context) --> layouted R0462

not-yet-layouted C0325

do layout (drawing context) --> layouted R0468

invalid layout C0326

--> not-yet-layouted R0467

main: Black Box View

main.c C0073

calls --> main_commands R0630

main C0021

- starts the software
- evaluates command line parameters

--> main.c R0090

--> main_commands R0629

main_commands C0415

u8stream overview

This diagram shows small universal(u8) utility modules.

u8log C0019

- provides macros for event-logging and error-logging
- macros are typesafe (ts) so that e.g. integers are not acidentially passed to char* parameters
Logging functionality may be enabled even in RELEASE/NDEBUG code. Logs must not contain confidential data: These may be forwarded to syslog or the filesystem where access rights differ from the OS-process in which crystal-facet-uml runs.

u8trace C0020

- provides trace macros
- traces allow to reconstruct/follow the program flow
The macros shall be typesafe; The compiler shall complain if using wrong-typed parameters.
The trace functions are intended for debugging purposes only. They are disabled in RELEASE/NDEBUG code. Therefore it is valid to trace confidential information.

u8stream/ C0030

provides small, generic utility classes that are independant of the project

--> u8_error_info R0638

--> utf8stream R0623

--> u8 R0654

--> u8dir R0653

--> u8_error R0617

--> u8stream R0405

--> u8log R0620

--> u8trace R0621

--> utf8stringbuf R0699

--> u8list R0700

--> u8arena R0701

utf8stringbuf C0194

String library

u8stream C0302

u8arena C0410

This package provides functions to provide dynamic-sized data structures which are allocated within a fixed-size memory region.

u8_error C0411

An error mask representing one or multiple errors

u8list C0412

This package is a collection of functinos to handle variable-length lists in statically allocated fixed-sized buffers.

utf8stream C0414

readers and writers that stream unicode code points instead of bytes.

u8_error_info C0418

An error info struct representing one error with detailed information

u8dir C0423

u8 C0424

--> u8_error R0655

--> u8_error_info R0656

--> u8trace R0657

--> u8log R0658

u8stream: WhiteBox View

u8stream/ C0030

provides small, generic utility classes that are independant of the project

--> Simple Random R0554

--> Utf8 Writer R0550

--> u8stream R0405

--> u8list R0700

u8stream C0302

--> Output Stream R0408

--> Input Stream R0547

Output Stream C0305

Input Stream C0375

Utf8 Writer C0378

--> Output Stream R0553

Simple Random C0379

Pseudo random number generator, not suitable for security appliances.

u8list C0412

This package is a collection of functinos to handle variable-length lists in statically allocated fixed-sized buffers.

--> Array List R0624

--> Array Index Sorter R0625

Array List C0267

Array Index Sorter C0058

U8 base classes and macros

This diagram shows small universal(u8) utility modules.

u8trace C0020

- provides trace macros
- traces allow to reconstruct/follow the program flow
The macros shall be typesafe; The compiler shall complain if using wrong-typed parameters.
The trace functions are intended for debugging purposes only. They are disabled in RELEASE/NDEBUG code. Therefore it is valid to trace confidential information.

--> Info R0088

--> Timestamp R0089

--> End (function) R0087

--> Begin (function) R0086

Begin (function) C0069

Info C0071

Timestamp C0072

End (function) C0070

u8log C0019

- provides macros for event-logging and error-logging
- macros are typesafe (ts) so that e.g. integers are not acidentially passed to char* parameters
Logging functionality may be enabled even in RELEASE/NDEBUG code. Logs must not contain confidential data: These may be forwarded to syslog or the filesystem where access rights differ from the OS-process in which crystal-facet-uml runs.

--> Error R0064

--> Anomaly R0066

--> Event R0067

--> Warning R0065

Error C0052

An error is a condition that leads to an observalbe malfunction.

Event C0055

An event is a signal that is send to or received from external software parts.

Anomaly C0054

An anomaly is a condition that is expected to not cause a malfunction but that should be logged to easier analyze issues.
E.g. an unknown classifier type in the database may be caused by opening a database file that was created by a newer program version. This could lead to unexpected behavior but should not cause a malfunctioning of the program.

Warning C0053

A warning is issued when a condition may possibly lead to a malfunction.

u8 C0424

--> u8_error R0655

--> u8_error_info R0656

--> u8trace R0657

--> u8log R0658

u8_error C0411

An error mask representing one or multiple errors

u8_error_info C0418

An error info struct representing one error with detailed information

Stream

u8stream C0302

--> Output Stream R0408

--> Memory Output Stream R0407

--> File Output Stream R0406

--> Escaping Output Stream R0555

--> Stream Output Stream R0556

--> Input Stream R0547

--> File input stream R0549

--> Memory Input Stream R0548

Output Stream C0305

Memory Output Stream C0304

--> Output Stream R0409

File Output Stream C0303

--> Output Stream R0410

File input stream C0377

--> Input Stream R0552

Memory Input Stream C0376

--> Input Stream R0551

Input Stream C0375

Escaping Output Stream C0380

--> Output Stream R0557

Stream Output Stream C0381

Wrapper around posix output streams

--> Output Stream R0558

utf8stringbuf classes and dependencies

utf8stringbuf C0194

String library

--> utf8:codepoint iterator R0661

--> utf8:string R0662

--> uft8:stringview iterator R0665

--> storage classes R0667

--> view classes R0668

--> utf8:stringview R0664

--> utf8:stringview tokenizer R0666

--> utf8:stringbuf R0663

--> utf8:codepoint R0660

utf8:codepoint C0426

utf8:codepoint iterator C0427

provides --> utf8:codepoint R0677

iterates on --> utf8:string R0681

utf8:string C0428

The methods of this string take an instance as parameter, which is kind of a pointer to the underlying character array.

utf8:stringbuf C0429

The methods of this stringbuf take an instance as parameter, which is kind of a pointer to the underlying character array.

consumes / produces --> utf8:string R0676

use --> utf8:stringview R0683

utf8:stringview C0430

The methods of this stringview take an instance as parameter, which is kind of a pointer to the underlying character array.

selects --> utf8:string R0678

uft8:stringview iterator C0431

iterates on / provides --> utf8:stringview R0679

utf8:stringview tokenizer C0432

iterates on / provides --> utf8:stringview R0680

storage classes C0433

--> utf8:stringbuf R0669

--> utf8:codepoint R0674

--> utf8:string R0675

view classes C0434

--> uft8:stringview iterator R0670

--> utf8:stringview R0671

--> utf8:codepoint iterator R0672

--> utf8:stringview tokenizer R0673

External Libraries

This diagram shows the base libraries. crystal-facet-uml links to these dynamically.

gtk3/gtk4 C0005

Toolkit which provides
- Windows and Widgets
- User Input handling

depends on --> gdk R0001

--> atk R0316

--> gio R0318

sqlite3 C0007

SQL database

glib C0026

Platform abstraction layer

gdk C0027

Drawing library

uses --> cairo R0002

uses --> pango R0003

depends on --> glib R0004

cairo C0028

Library providing drawing primitives

pango C0029

Font rendering engine

atk C0236

Accessibility Toolkit, kind of IPC to make widgets interfaces accessible.

--> glib R0317

gio C0237

file system abstraction, distributed as part of glib

--> glib R0319

test_fw: Black Box View

This diagram shows the sw-components involved in unit-testing.

test_fw C0017

Test framework
- runs test cases
- reports test results

main/test C0018

Each SW-moldule may have a subfolder named unittest which contains a set of tests; these
- test the SW-module

--> test_main R0071

depends on --> test_fw R0005

--> data/test/unit R0076

--> pencil/test/* R0077

--> universal/test/unit R0078

--> ctrl/test/unit R0079

data/test/unit C0059

--> test_fw R0075

ctrl/test/unit C0060

--> test_fw R0072

test_main C0061

pencil/test/* C0062

--> test_fw R0074

universal/test/unit C0063

--> test_fw R0073

io/test/* C0210

--> test_fw R0291

utf8stringbuf/test/unit C0211

--> test_fw R0292

test_fw: White Box View

test_fw C0017

Test framework
- runs test cases
- reports test results

--> test_suite R0301

--> test_assert R0304

--> test_fixture R0305

--> test_runner R0302

--> test_result R0303

test_suite C0227

test_case: [list]: F0054

setup(): F0055

tear_down(): F0056

call --> test_assert R0309

test_runner C0228

aggregate --> test_result R0308

run_suite --> test_suite R0311

test_result C0229

test_assert C0230

test_fixture C0231

The set of preconditions and cleanup-routines

--> test_suite R0306

--> test_suite R0307

Runtime View

This diagram depicts the run modes of the software.

mode? C0064

start repair via command line --> run test /repair /export / import via CLI R0080

start GUI --> show GUI, no DB file selected R0081

show GUI, no DB file selected C0065

select DB file --> show GUI, show+alter DB R0082

run test /repair /export / import via CLI C0066

report and finish --> end R0085

end C0067

show GUI, show+alter DB C0068

switch DB file --> show GUI, show+alter DB R0083

select non-DB file --> show GUI, no DB file selected R0102

Try to open a non-sqlite 3 DB file.

start C0192

--> mode? R0251

GUI-mode C0193

--> show GUI, no DB file selected R0252

--> show GUI, show+alter DB R0253

quit --> end R0254

runmodes C0313

--> mode? R0446

--> start R0447

--> run test /repair /export / import via CLI R0448

--> end R0449

--> GUI-mode R0450

Deployment View

PC: Hardware C0175

The physical or virtual environment within the software runs.

--> Linux/Win: OS R0237

Linux/Win: OS C0176

The operating system that allows to run crystal-facet-uml.

--> JSON Data Exchange R0561

--> Other export formats R0564

--> Database File R0559

--> crystal-facet-uml process R0238

crystal-facet-uml process C0177

--> crystal-facet-uml application R0243

crystal-facet-uml application C0178

--> Database File R0560

im/export --> JSON Data Exchange R0563

export --> Other export formats R0565

Database File C0382

Data models of crystal-facet-uml are stored to and read from sqlite database files.

JSON Data Exchange C0383

Data models of crystal-facet-uml are stored to and read from json files.

--> Version Control System R0562

Version Control System C0384

Other export formats C0385

Data models of crystal-facet-uml are exported as rendered images and/or text-based data files.

Crosscutting Concepts

This chapter shows concepts that shall be applied through all parts of the software.

Crosscutting Concepts C0217

Trace, Log, Assert, Error Propagation, Memory Management

Assert

Program Assert C0220

Use "if(COND) {...} else {LOG("error");assert(false);}" statements to ensure code+data consistency towards other software modules, This makes code more robust if unexpected behavior occurs during operation.

Assert-Goal C0221

Maintainability:
- When modifying code, illegal modifcations shall be detected early
Analyzability:
- When receiving bug reports, an anomaly in the program/data flow shall be detected early
Reliability:
- Errors in one SW module shall not cause errors in other modules
Testability:
- Assert-paths in code shall be testable

--> Program Assert R0295

--> External Data Check R0298

--> Local Assert R0299

--> Test Environment Assert R0300

Local Assert C0224

Use "assert(COND);" statements to ensure code+data consistency within one software module, These are executed in DEBUG mode only.

External Data Check C0225

Use "if(COND) {...} else {LOG("error");}" statements to ensure code+data consistency towards external input, External input may possibly not follow any specification.

Test Environment Assert C0226

Use "TEST_ENVIRONMENT_ASSERT()" statement to ensure a valid test environment. Errors always terminate the test run.

Log, Trace

Trace-Goal C0223

Trace messages shall be activated for debugging to follow the program flow and visualize the processed data.

--> Trace R0297

Trace C0218

Performance:
- Deactivated trace messages shall not slow down the program by more than 1%.
- Activated trace messages shall not slow down the program by more than 10%.
- Operation performance (NDEBUG-mode) shall not be affected by trace messages.

Log-Goal C0222

Log Messages are written during operation to be able to analyze important events, anomalies and faults.

--> Log R0296

Log C0219

Security:
- Log messages must not contain confidential data

Memory Management

Stack Mem C0246

On stack, only small data structures (<10kB) shall be stored.

--> Degradation Mode R0471

Heap C0247

Only the external libraries may use the heap.

Static Allocations C0248

All data structures of crystal-facet-uml shall be statically allocated.

--> Degradation Mode R0470

Limited dynamic allocations C0297

Memory may be dynamically allocated from heap for non-base use cases. The program shall continue operation if no memory is available anymore. See Performance Efficiency (Time+Resource).

--> Degradation Mode R0472

Degradation Mode C0295

In case of low memory, the base functionality of crystal-facet-uml shall still work reliably.

Error Propagation

Error Codes C0249

When a failure is detected, it shall be logged. If a failure can be handled locally, this shall be done. Typically, an error is propagated from where it is detected to another location in the program where it can be handled. This is done using error codes.

Bitmask C0250

The error bitmask shall be designed in a way that a zero represents no error, that the bits define the error cause/type, that two errors can be merged into one error code using a bitwise or. Error codes are not netative because this makes evaluation of the bitmask difficult to understand.

Top Level Error-Categories

ERROR C0386

Error-Categories by Reaction C0387

--> CONTINUE R0575

--> USR_ERROR R0576

--> LOGIC_ERROR R0579

--> OP0_ERROR R0580

--> OP1_ERROR R0577

--> USR_ERROR R0578

--> OP1_ERROR R0573

--> NO_START R0581

--> TERMINATE R0582

CONTINUE C0388

--> ERROR R0569

NO_START C0389

--> ERROR R0568

TERMINATE C0390

--> ERROR R0570

USR_ERROR C0391

notify user: in statusbar: F0097

OP1_ERROR C0392

notify operator: via log: F0098

--> CONTINUE R0574

OP0_ERROR C0393

notify operator: F0099

--> NO_START R0572

LOGIC_ERROR C0394

notify developer: F0100

--> TERMINATE R0571

Logic Errors

LOGIC_ERROR C0394

notify developer: F0100

Error-Categories by Reaction C0387

--> LOGIC_ERROR R0579

STATE C0400

--> LOGIC_ERROR R0596

PARAMS C0401

--> LOGIC_ERROR R0595

DATA_CORRUPT C0402

--> LOGIC_ERROR R0594

Error-Categories by Cause C0399

--> PARAMS R0592

--> STATE R0591

--> DATA_CORRUPT R0593

Operations Error Categories

Error-Categories by Reaction C0387

--> OP0_ERROR R0580

--> OP1_ERROR R0577

--> OP1_ERROR R0573

OP1_ERROR C0392

notify operator: via log: F0098

OP0_ERROR C0393

notify operator: F0099

Error-Categories by Cause C0399

--> ENV_RUN R0603

--> SYSTEM_ACCESS R0602

--> TIME/SYNC R0601

--> ENV_START R0604

TIME/SYNC C0403

Timeout of remote calls or cyclic events

--> OP1_ERROR R0597

SYSTEM_ACCESS C0404

--> OP1_ERROR R0598

ENV_RUN C0405

Runtime Envionment

--> OP1_ERROR R0599

ENV_START C0406

Startup Envionment

--> OP0_ERROR R0600

User Errors

INPUT /SOURCE C0395

--> USR_ERROR R0584

OUTPUT /SINK C0396

--> USR_ERROR R0583

USER_ACCESS (r/w/x) C0397

--> USR_ERROR R0585

WRONG_MODE C0398

The request is not valid in the current situation.

--> USR_ERROR R0586

USR_ERROR C0391

notify user: in statusbar: F0097

Error-Categories by Reaction C0387

--> USR_ERROR R0576

--> USR_ERROR R0578

Error-Categories by Cause C0399

--> USER_ACCESS (r/w/x) R0588

--> INPUT /SOURCE R0590

--> OUTPUT /SINK R0589

--> WRONG_MODE R0587

Architectural Decisions

This diagram shows which major design decisions were taken.

Question, Alternatives, selected Decision C0085

--> How to store data persistently? R0103

--> How to structure persistent data? R0104

--> How can diagrams select the parts to show? R0105

--> How to traverse the model for XMI export? R0401

How to structure persistent data? C0086

The database structure shall be simple but also close to UML in oder to store an UML-Model

How to store data persistently? C0075

The UML Model shall be stored persistently.

How can diagrams select the parts to show? C0087

Each diagram shall show selected parts of the UML-Model, especially the scenario-based sequence, communication and timing diagrams.

How to traverse the model for XMI export? C0298

Alternatives on persistent Data Storage

This diagram shows fundamental design decisions of the crystal-facet-uml architecture.

XML DB C0074

The database is stored in XML format.
pro: text based, fits to svn and git repositories
con: all data needs to fit to RAM (or complex data handling), difficult to read for humans, especially for relations between data entries.

solves --> How to store data persistently? R0094

How to store data persistently? C0075

The UML Model shall be stored persistently.

Json DB C0076

The database is stored in Json format.
pro: text based, fits to svn and git repositories
con: all data needs to fit to RAM (or complex data handling)

solves --> How to store data persistently? R0093

SQLite DB C0077

The database is stored in sqlite3 format.
pro: the database cares on handling big amounts of data the database cares on reliability and consistency of data
con: binary files are not suitable for git repositories

solves --> How to store data persistently? R0091

Key-Value Pairs DB C0078

The database is stored as key-value pairs.
pro: allows automatic merges by git and svn
con: all data needs to fit to RAM (or complex data handling), difficult to express complex data entries or relations between these

solves --> How to store data persistently? R0092

SQLite is chosen C0079

Rationale: This alternative is most future-proof in case the database becomes large.

--> SQLite DB R0095

Json as second/optional storage format C0360

Rationale: A human-readable JSON based storage format allows to support the following use cases:

- git blame shall show who changed model elements
- git merge shall allow to automatically merge models
- git mergetool shall allow to manually merge models
- Data exchange with external scripts

--> Json DB R0512

Alternatives on data structure of UML-Model

How to structure persistent data? C0086

The database structure shall be simple but also close to UML in oder to store an UML-Model

Simple data structure C0088

The data is structured with focus on simplicity.
pro: Simple data structure. There are similarities to UML (M2 Meta-Model) and MOF (M3 Meta-Model).
con: takes into account that some things of UML cannot be represented

solves --> How to structure persistent data? R0110

Copy of the OMG UML Defintion Model C0089

The data is structured according to the UML meta model defined by OMG (see UML/SysML Overview).
pro: allows to model all UML elements easy conversion to XMI and back
con: the UML meta model is complex. Not suitable for a small diagram-drawing application like crystal-facet-uml.

solves --> How to structure persistent data? R0109

Simple structure is chosen C0091

The OMG UML definition model is quite complex and exceeds the possibilities of a small OSS program like crystal-facet-uml.

--> Simple data structure R0117

Details on simple data structure

This diagram shows the data structure of the "Simple data structure" alternative.

relationships C0081

id: int64_t: F0014

main_type: enum: F0021

name: F0022

description: F0023

from --> classifiers R0096

to --> classifiers R0097

from --> features R0205

to --> features R0206

classifiers C0080

id: int64_t: F0012

main_type: enum: F0017

stereotype: F0018

name: F0019

description: F0020

--> features R0210

features C0083

id: int64_t: F0013

main_type: enum: F0024

key (name): F0025

value (type): F0026

description: F0027

Simple data structure C0088

The data is structured with focus on simplicity.
pro: Simple data structure. There are similarities to UML (M2 Meta-Model) and MOF (M3 Meta-Model).
con: takes into account that some things of UML cannot be represented

--> relationships R0106

--> classifiers R0107

--> features R0108

Alternatives on UML-Model selection for Diagram

How can diagrams select the parts to show? C0087

Each diagram shall show selected parts of the UML-Model, especially the scenario-based sequence, communication and timing diagrams.

Classifier selection defines view C0090

Diagramelements define which classifiers are visible in which diagram. All features of a visible classifier are shown. All relationships are shown that have visible classifiers at both ends.
pro: simple selection rule
con: Problematic for diagrams that show possible scenarios and alternatives (e.g sequences). This solution assumes that the model is invariant for all diagrams, therefore all diagrams showing examples/scenarios have to show own instances of classes, not generic classes that are used in other diagrams.

solves --> How can diagrams select the parts to show? R0116

Classifier or Relationship selection def. view C0092

Depending on the diagram type, either classifiers determine what is visble or relationships determine what is visible.
pro: similar concept for diagrams that show options/alternatives/scenarios to diagrams that show invariants.
con: Bigger extension to existing structure in version 1.0.0 Algorithm to distinguish used from unused elements gets complicated

solves --> How can diagrams select the parts to show? R0118

Diagrams have filters C0096

Either diagrams filter ranges of x-order/y-order/list-order or diagrams filter by use-case (which requires that all relations belong to a use-case)
pro: small changes to existing database structure only
con: Unclear gui concept: How to make this filtering transparent to the user? How to copy/paste between diagrams? How to make invisible relationships visible?

solves --> How can diagrams select the parts to show? R0127

Classifier+Lifeline solution is chosen C0097

This solution allows with few additional relationships to provide a user friendly solution to scenario and example based diagrams.

--> Classifier and port/lifeline selection def view R0141

Classifier and port/lifeline selection def view C0106

solves --> How can diagrams select the parts to show? R0140

DATA_CLASSIFIER _TYPE_INTERACTION C0455

Diagramelements define which classifiers are visible in which diagram. All features of a visible classifier are shown. All relationships are shown that have visible classifiers at both ends. In contrast to Classifier and Port/Lifeline selection def view, this solution links lifelines (which are features) to both: their classifier and also to their interaction.
pro: similar simplicity as Classifier and Port/Lifeline selection def view. The model encodes all information even when ignoring the view classes. The solution is closer to the UML proposal The xmi export would not require exceptional handlings for interactions
con: Idea for this solution popped up after Classifier and Port/Lifeline selection def view was already implemented. There would be 1 more implicit object to manage automatically More error cases have to be handled

solves --> How can diagrams select the parts to show? R0713

Details on Classifier or Relationship Sel.

Depending on the diagram type, selection of contents is done on classifiers or relationships.

relationships C0081

id: int64_t: F0014

main_type: enum: F0021

name: F0022

description: F0023

from --> classifiers R0096

to --> classifiers R0097

from --> features R0205

to --> features R0206

classifiers C0080

id: int64_t: F0012

main_type: enum: F0017

stereotype: F0018

name: F0019

description: F0020

--> features R0210

features C0083

id: int64_t: F0013

main_type: enum: F0024

key (name): F0025

value (type): F0026

description: F0027

diagrams C0084

id: int64_t: F0015

diagram_type: enum: F0028

name: F0029

description: F0030

parent --> diagrams R0099

diagramrelationships C0095

for diagrams that show options/alternatives/scenarios

--> relationships R0126

--> diagrams R0130

Classifier or Relationship selection def. view C0092

Depending on the diagram type, either classifiers determine what is visble or relationships determine what is visible.
pro: similar concept for diagrams that show options/alternatives/scenarios to diagrams that show invariants.
con: Bigger extension to existing structure in version 1.0.0 Algorithm to distinguish used from unused elements gets complicated

--> diagramrelationships R0121

--> diagramelements_simple R0712

diagramelements_simple C0152

id: int64_t: F0034

display_flags: F0035

--> diagrams R0207

--> classifiers R0208

Details on Classifier Selected View

The simple solution is to not implement special mechanisms for scenario-based diagrams but to require that all shown classifiers in a scenario based diagram are explicit instances of the model-class.

Classifier selection defines view C0090

Diagramelements define which classifiers are visible in which diagram. All features of a visible classifier are shown. All relationships are shown that have visible classifiers at both ends.
pro: simple selection rule
con: Problematic for diagrams that show possible scenarios and alternatives (e.g sequences). This solution assumes that the model is invariant for all diagrams, therefore all diagrams showing examples/scenarios have to show own instances of classes, not generic classes that are used in other diagrams.

--> diagramelements_simple R0209

diagrams C0084

id: int64_t: F0015

diagram_type: enum: F0028

name: F0029

description: F0030

parent --> diagrams R0099

relationships C0081

id: int64_t: F0014

main_type: enum: F0021

name: F0022

description: F0023

from --> classifiers R0096

to --> classifiers R0097

from --> features R0205

to --> features R0206

classifiers C0080

id: int64_t: F0012

main_type: enum: F0017

stereotype: F0018

name: F0019

description: F0020

--> features R0210

features C0083

id: int64_t: F0013

main_type: enum: F0024

key (name): F0025

value (type): F0026

description: F0027

diagramelements_simple C0152

id: int64_t: F0034

display_flags: F0035

--> diagrams R0207

--> classifiers R0208

Classifier and Port/Lifeline selection def view

This (finally chosen and implemented) solution selects timing and sequence lifelines by a focused_feature link. To enhance usability, this cannot be selected but the program creates an own lifeline for every scenario-based diagram.

features C0083

id: int64_t: F0013

main_type: enum: F0024

key (name): F0025

value (type): F0026

description: F0027

classifiers C0080

id: int64_t: F0012

main_type: enum: F0017

stereotype: F0018

name: F0019

description: F0020

--> features R0210

relationships C0081

id: int64_t: F0014

main_type: enum: F0021

name: F0022

description: F0023

from --> classifiers R0096

to --> classifiers R0097

from --> features R0205

to --> features R0206

diagrams C0084

id: int64_t: F0015

diagram_type: enum: F0028

name: F0029

description: F0030

parent --> diagrams R0099

diagramelements C0082

id: int64_t: F0016

display_flags: F0031

--> diagrams R0100

--> classifiers R0101

focused_feature --> features R0204

to select one of possibly several lifelines

lifelines C0466

--> features R0726

DATA_CLASSIFIER _TYPE_INTERACTION

DATA_CLASSIFIER _TYPE_INTERACTION C0455

Diagramelements define which classifiers are visible in which diagram. All features of a visible classifier are shown. All relationships are shown that have visible classifiers at both ends. In contrast to Classifier and Port/Lifeline selection def view, this solution links lifelines (which are features) to both: their classifier and also to their interaction.
pro: similar simplicity as Classifier and Port/Lifeline selection def view. The model encodes all information even when ignoring the view classes. The solution is closer to the UML proposal The xmi export would not require exceptional handlings for interactions
con: Idea for this solution popped up after Classifier and Port/Lifeline selection def view was already implemented. There would be 1 more implicit object to manage automatically More error cases have to be handled

--> interaction classifier R0715

--> diagramelements_simple R0714

diagrams C0084

id: int64_t: F0015

diagram_type: enum: F0028

name: F0029

description: F0030

parent --> diagrams R0099

classifiers C0080

id: int64_t: F0012

main_type: enum: F0017

stereotype: F0018

name: F0019

description: F0020

--> features R0210

relationships C0081

id: int64_t: F0014

main_type: enum: F0021

name: F0022

description: F0023

from --> classifiers R0096

to --> classifiers R0097

from --> features R0205

to --> features R0206

features C0083

id: int64_t: F0013

main_type: enum: F0024

key (name): F0025

value (type): F0026

description: F0027

diagramelements_simple C0152

id: int64_t: F0034

display_flags: F0035

--> diagrams R0207

--> classifiers R0208

interaction classifier C0456

--> classifiers R0716

---> has lifeline /. <--- context --> lifelines R0727

lifelines C0466

--> features R0726

Use Cases to address

User interaction C0457

--> Consistency R0718

XMI Export C0458

Consistency C0459

Classifier selection C0460

Diagramelelements: know the lifelines that they represent: F0104

--> User interaction R0719

diagram to interaction C0461

An interaction classifier: must exist while diag is type interaction: F0105

An interaction classifier: must not exist otherwise: F0106

--> Consistency R0720

lifeline to interaction C0462

A lifeline: must exist when interaction exists and classifier type can have lifelines: F0107

A lifeline: must not exist otherwise: F0108

--> Consistency R0721

To Realize C0463

Todays solution Classifier and Port/Lifeline selection def view stores interaction information in diagramelements (as focused feature).
It would be cleaner if the model would be fully specified without diagrams and diagramelements.
But the user interaction use-case requires todays database fields to be present anyhow.

--> Classifier selection R0722

--> User interaction R0728

Alternatives on XMI export/model traverse

How to traverse the model for XMI export? C0298

traverse diagram tree C0300

as for other document exports, simply traverse the diagram tree in depth first order.
pro: simple to implement
con: the hierarchical xmi structure cannot be produced

--> How to traverse the model for XMI export? R0403

sort classifiers by number of parents C0301

traverse the list of classifiers, not the diagrams; export classifiers without parents first; export each classifier together with all children
pro: allows to export the expected xmi structure
con: difficult to implement, diagram descriptions are lost

--> How to traverse the model for XMI export? R0404

classifier list is iterated C0314

classifier list is
- sorted,
- iterated,
- containment parents are descended to children (since version 1.24.0)

--> sort classifiers by number of parents R0451

Interaction Diagrams

sort classifiers by number of parents C0301

traverse the list of classifiers, not the diagrams; export classifiers without parents first; export each classifier together with all children
pro: allows to export the expected xmi structure
con: difficult to implement, diagram descriptions are lost

How to generate the Interactions? C0315

Interactions are
- Sequence,
- Timing,
- Communication and
- Interaction Overview Diagrams

--> sort classifiers by number of parents R0452

Create an new "Interaction" Classifier C0316

This solution is in line with the UML specification: An interaction classifier encapsulates all messages belonging to this interaction. The interaction classifier can be referenced from multiple diagrams.

--> How to generate the Interactions? R0453

Traverse the corresponding diagram C0317

Traverse the corresponding diagram when encountering lifelines. This solution sticks to what the current gui can manage in an understandable way for the user.

--> How to generate the Interactions? R0454

planned solution C0318

pro:
- simpler to implement
- less redundancy in database con:
- less UML like
- no clear separation of model and diagrams
- no solution for interaction fragments

--> Traverse the corresponding diagram R0455

Quality Requirements

Quality Tree C0338

Quality Scenarios C0339

Ordering by Quality Attributes C0340

This section shows the quality requirement on crystal-facet-uml ordered by quality characteristics / attributes.

--> Quality Tree R0485

Ordering by Use Cases / Scenarios C0341

This section shows the quality requirement on crystal-facet-uml ordered by use cases / usage scenarios.

--> Quality Scenarios R0486

Quality Tree

This section shows quality requirements (structured into a quality tree)

Compatibility C0292

see Compatibility (Replace,Interop.,...).

Usability C0290

see Usability (Attactiveness,...).

Performace Efficiency C0289

see Performance Efficiency (Time+Resource).

Performance Efficiency (Time+Resource)

Performance of User Interface C0286

Reliability of Program operation C0287

Degradation Mode Scenario C0288

If memory resources are low, a degradation mode is acceptable if
- no data from the database is lost
- the focused diagram is displayed correctly
- the data export works reliably
- 3 undo operations are possible
In degradation mode, the following shortcomings are acceptable:
- not all diagrams on a screen are drawn completely
- the list of search results may be truncated
- the number of simultaneous open windows may be limited

--> Reliability of Program operation R0395

explains --> Degradation Mode R0396

Degradation Mode C0295

In case of low memory, the base functionality of crystal-facet-uml shall still work reliably.

--> Reliability of Program operation R0397

Reliability in Low-Memory Situations

Reliability of Program operation C0287

Degradation Mode Scenario C0288

If memory resources are low, a degradation mode is acceptable if
- no data from the database is lost
- the focused diagram is displayed correctly
- the data export works reliably
- 3 undo operations are possible
In degradation mode, the following shortcomings are acceptable:
- not all diagrams on a screen are drawn completely
- the list of search results may be truncated
- the number of simultaneous open windows may be limited

--> Reliability of Program operation R0395

When starting, if not enough memory, stop C0335

When starting, if not enough memory is available to operate, the program shall inform the user and stop.

--> Reliability of Program operation R0482

When opening a new window, if low-mem, cancel C0336

When opening a new main window, if low-mem, the program shall inform the user and cancel the operation.

--> Reliability of Program operation R0483

When searching, if low-mem, show only parts C0337

When searching, if not enough memory available for storing the search result list, the program shall indicate that some results are omitted and show only parts of the result list.

--> Reliability of Program operation R0484

When navigating, if low-mem, show placeholders C0342

When navigating, if low-mem, the program shall show placeholder rectangles where rendering of diagrams is not possible.

--> Reliability of Program operation R0487

When undoing, allow at least 3 undo operations C0343

When undoing/redoing past actions, the program shall perform at least 3 undo/redo operations before informing the user that undo/redo is not possible anymore.

--> Reliability of Program operation R0488

Other operations shall work reliable if OOM C0344

When the user operates the program, if low-mem, the program shall work reliably for all use cases where no exception is stated.

--> Reliability of Program operation R0489

Usability (Attactiveness,...)

Aesthetics of Auto-layouted diagrams C0291

Compatibility (Replace,Interop.,...)

Compatibility of Export-Formats C0293

Data migration at SW Updates C0294

Quality Scenarios

This section shows scenarios which are of special importance for the quallity requirements stated in Quality Tree.

Program Start and About Window C0345

Open a Model Database C0346

Export (Model and/or Diagrams) C0347

Navigate and Search and Open multiple Windows C0348

Modify / Create / Delete Diagrams and Elements C0349

Undo and Redo C0350

Check and Repair Database C0351

Program Start and About Window

Program Start and About Window C0345

--> When starting, if not enough memory, stop R0490

When starting, if not enough memory, stop C0335

When starting, if not enough memory is available to operate, the program shall inform the user and stop.

Open a Model Database

Open a Model Database C0346

Export Database Model / Diagrams

Export (Model and/or Diagrams) C0347

Navigate and Search and Open multiple Windows

Navigate and Search and Open multiple Windows C0348

--> When opening a new window, if low-mem, cancel R0529

--> When searching, if low-mem, show only parts R0492

--> When navigating, if low-mem, show placeholders R0493

When searching, if low-mem, show only parts C0337

When searching, if not enough memory available for storing the search result list, the program shall indicate that some results are omitted and show only parts of the result list.

When navigating, if low-mem, show placeholders C0342

When navigating, if low-mem, the program shall show placeholder rectangles where rendering of diagrams is not possible.

When opening a new window, if low-mem, cancel C0336

When opening a new main window, if low-mem, the program shall inform the user and cancel the operation.

Modify / Create / Delete Diagrams and Elements

Modify / Create / Delete Diagrams and Element C0352

Undo and Redo

Undo and Redo C0350

--> When undoing, allow at least 3 undo operations R0494

When undoing, allow at least 3 undo operations C0343

When undoing/redoing past actions, the program shall perform at least 3 undo/redo operations before informing the user that undo/redo is not possible anymore.

Check and Repair Database

Check and Repair Database C0351

Risks and Technical Debt

see Todo list C0187

A Todo-list exists in the git repository for things that shall be changed.

Static Memory Allocation C0188

Except for the libraries gtk and sqlite (sqlite is configured for dynamic allocations), crystal-facet-uml uses fixed-size arrays and strings for all displayed data.
One could change this - but for most use cases, valid upper memory limits can be stated.

Glossary

GUI Terms C0238

see GUI Terms.

Code Terms C0239

see Code Terms.

Structure C0240

The glossary is split into sections for contexts
- GUI terms
- Code terms
- Database terms

Database Terms C0285

see Database Terms.

GUI Terms

focused element (yellow corners) C0179

a focused element is the one element to which input is directed:
- changing name, stereotype, type or description is done on the focused element.

highlighted element (green color) C0181

the highlightes element is the one on which the mouse arrow hovers. In case of a mouse click, the highlighted elements gets the focused element.

selected element (pink corners) C0180

a selected element is an element that belongs to the selected set

Pencil Terms

This diagram explains terms used mainly in pencil module.

icon C0327

An icon is a small picture representing an element-type

--> symbol R0473

contour C0328

A contour is an outer line around an element. The exact shape of it depends on the elements type. Some elements do not have a contour.

--> symbol R0474

top-right-icon --> icon R0682

label C0329

A label is the text attached to the visual representation of an element. It consists of its name and optionally an stereotype.

symbol C0330

A symbol is a drawing/picture representing the type of an element

envelope C0333

the rectangular outer bounds of symbol, label and space

--> symbol R0478

--> space R0479

--> label R0480

space C0334

the rectangular area of all contained compartments (except the label-compartment)

image C0435

The image of a stereotype. This may replace either the stand-alone icon or the icon in the top right corner of a contour.

GUI/Pencil Terms

Label Compartment C0331

The rectangular area containing label and possibly an icon. It is the top-most compartment.

--> Compartment R0475

may have 0..1 --> icon R0476

has 1..1 --> label R0477

Compartment C0332

A compartment is an area in a classifier showing features of the classifier, e.g. tags, methods, attributes, use-cases

icon C0327

An icon is a small picture representing an element-type

label C0329

A label is the text attached to the visual representation of an element. It consists of its name and optionally an stereotype.

space C0334

the rectangular area of all contained compartments (except the label-compartment)

has 1..n --> Compartment R0481

Pencil Modes

Class C0443

standalone-icon C0444

<path d=" M 3,0 h 4 v 4 h -4 v -4 "/> <path stroke="#0088ff" fill="#cceeff" d=" M 1,4.5 h 8 v 2 h -8 v -2 "/> <path d=" M 2,7 h 2 m 2,0 h 2 v 2 h -2 m -2,0 h -2 v -2 "/>

--> Class R0695

--> icon-img R0697

contour-and-icon C0445

<path d=" M 1,2 h 8 v 6 h -8 v -6 M 6.5,3 h 1.5 v 1.5 h -1.5 v -1.5 "/> <path stroke="#0088ff" fill="#cceeff" d=" M 2,3 h 4 v 2 h -4 v -2 "/> <path d=" M 2,5.5 h 2 m 2,0 h 2 v 2 h -2 m -2,0 h -2 v -2 "/>

--> Class R0696

--> contour-img R0698

icon-img C0446

contour-img C0447

Code Terms

assertions C0184

- assert() from assert.h checks during runtime (in DEBUG-mode) if assumptions on the code are valid.
- TEST_ASSERT() checks during and after a test case execution if the test result fits the expectations.
- PROG_ASSERT() checks during a test case for errors in the testing environment.

logging C0182

In RELEASE/NDEBUG mode, the program logs only important events, anomalies, warnings and errors. These shall be as sparse as possible to not slow down performance or consume too much memory. Goal of logging is to be able to help analyze or reproduce a bug that occurred during operation.

tracing C0183

In DEBUG mode, the program writes abundant information to a trace channel. Goal of tracing is to follow the program flow as well as to visualize the data changes.

Database Terms

data_id C0283

A data-id is an identifier that refers to a table and a row-id in the database. It is unique within one database.

row_id C0284

A row-id is an identifier for a data row within one table. It is unique within a table but not within a database.

uuid C0417

A uuid identifies a data record. It is unique within a database, also between different versions/branches. It is unique even between different databases.

Stereotypes on Problem Space

context C0436

<path fill="#e0ffe0" stroke="#009955" d=" M 0, 6 c 0, -3.3 2.7, -6 6, -6 l 0, 2 c -2.2, 0, -4, 1.8, -4, 4 l -2, 0 M 10, 6 c 0, 2.2, -1.8, 4, -4, 4 l 0, 2 c 3.3, 0 6, -2.7 6, -6 l -2, 0 "/> <path fill="#e0e0e0" d=" M 4, 6 c 0, -1.1 0.9, -2 2, -2 c 1.1, 0 2, 0.9 2,2 c 0, 1.1, -0.9, 2, -2, 2 c -1.1, 0 -2, -0.9, -2, -2 "/>

--> cntx-img R0687

cntx-img C0439

meta-img C0440

metaclass C0437

<path fill="none" stroke="#000055" d=" l 2,0 m 1,0 l 2,0 m 1,0 l 2,0
l 0,2 m 0,1 l 0,2
l -2,0 m -1,0 l -2,0 m -1,0 l -2,0
l 0,-2 m 0,-1 l 0,-2 "/>

--> meta-img R0689

Stereotypes on Context C0438

--> context R0684

--> metaclass R0685

--> meta-img R0688

--> cntx-img R0686

Stereotypes on Requirements C0471

--> req R0739

--> req-img R0740

--> spec R0742

--> spec-img R0743

req C0472

<path stroke="none" fill="#ffff00" d=" M 3.2,0.2 L 7.5,2 L 3.2,3.8 Z "/> <path d=" M 3,9 L 3,0 L 8,2 L 3,4 "/>

--> req-img R0741

req-img C0473

spec C0474

<path stroke="none" fill="#ffaaee" d=" M 3.2,0.2 L 7.5,2 L 3.2,3.8 Z "/> <path d=" M 3,9 L 3,0 L 8,2 L 3,4 "/>

--> spec-img R0744

spec-img C0475

Stereotypes on Solution Space

Stereotypes on Decisions C0448

--> reason_decision R0703

--> decision_img R0706

--> reason_argument R0723

--> argument R0724

--> chosen_img R0707

--> reason_rejected R0708

--> reason_chosen R0705

--> rejected_img R0704

reason_decision C0449

<path d="m 8,12 l -4,7 1,1 6,0 1,-1 -4,-7 l 8,-4 9,0 l -4,7 1,1 6,0 1,-1 -4,-7 " /><path d="m 15,5 l 1,3 m 0,2 l 0,17 " />

--> decision_img R0709

rejected_img C0450

reason_chosen C0451

<path d="m 1,24 4,4 22,0 4,-4 " /><path stroke="#00aa00" d="m 8,17 c 0,-4.4375 3.5625,-8 8,-8 s 8,3.5625 8,8 s
-3.5625,8 -8,8 s -8,-3.5625 -8,-8 " /><path stroke="#00aa00" d="m 11,17 l 10,0 m -5,-5 l 0,10 " />

--> chosen_img R0710

decision_img C0452

chosen_img C0453

reason_rejected C0454

<path d="m 1,24 4,4 22,0 4,-4 " /><path stroke="#cc0000" d="m 8,17 c 0,-4.4375 3.5625,-8 8,-8 s 8,3.5625 8,8 s
-3.5625,8 -8,8 s -8,-3.5625 -8,-8 " /><path stroke="#cc0000" d="m 11,17 l 10,0 " />

--> rejected_img R0711

reason_argument C0464

<path fill="#eeff00" d=" M4,0 L6,0 L5.5,6.5 L4.5,6.5 Z M 4,8.5 C 4,7 6,7 6,8.5 C 6,10 4,10 4,8.5 "/>

--> argument R0725

argument C0465