Describing and visualizing the database usage model

Currently we are using HSQLDB as our database. It is running in a docker container in server mode. For tests it is possible to configure an embedded database.

The REST server, that accesses the database, is build straight-forward:

• a REST service retrieves data from the payload of the request and then calls ...
• a workflow object, that encapsulates everything from consistency checking to the way the data is processed. The workflows use many ...
• DAOs (data access objects) that transfer data from and to the database by using ...
• DTOs (data transfer objects). As an object-relational framework we use Hiberate, thus the DTOs are Hibernate-managed classes.

To allow external programmers to understand, modify and extend this architecture (without destroying its architecture, hopefully :-), we need a detailed documentation

• explaining the rationale of this architecture,
• describing the architecture itself and
• giving hints what should be done when modifying its components and what not.

The database schema we use should be described in great detail,

• especially our distinction between a technical key (the primary key) and natural key (business key, enforced by unique constraints) in all tables
• the relation between our indexes and the SQL queries we expect, that use the indexes (maybe we can improve the schema ...)

It would be great, but _not _required, if the documentation described

• other object-relational frameworks, that could do the job comparably good. We restricted ourselfes to the core concepts of Hibernate, thus there _are _alternatives.
• other database server, that could replace HSQLDB. We are not planning this, but believe, that our restriction to that subset of SQL, that are supported by almost all database implementation, is a sign of flexible code. The use of an object-relation framework is a good basis for that, of course.