Architectural Description Tool

Context

This tools aims to describe the global jSeduite infrastructure. The first usage is to automatically generate diagrams from the description. Others application can use this representation to automate the generation of bundles, …

The underlying engine is the Prolog inference engine, which provides a very efficient backend for this kind of job.

Describing the architecture

The architecture description file is named jSeduite.pl, in the $JSEDUITE_HOME/architecture/description folder.

You'll describe the jSeduite architecture by expressing a set of logical facts. The facts syntax is really simple, and the only thing you have to know is you can't use a name which starts by an upper case character.

The following list contains all available facts, and the corresponding semantic :

Entities:
- library(X) ⇔ X is a library
- table(X) ⇔ X is a table inside the jSeduite database
- view(X) ⇔ X is a view inside the jSeduite database (table includes view)
- webservice(X) ⇔ X is defined as a black box web service inside jSeduite
- orchestration(X) ⇔ X is an orchestration (webservice includes orchestration)
Links:
- depends(X,Y) ⇔ library(X), library(Y), X uses a method defined in Y
- references(A,B) ⇔ table(A), table(B) and A defines a reference to B
- provides(X,O) ⇔ webservice(X) and X provides an operation named O
- uses(X,Y) ⇔ webservice(X), table(Y) and X retrieve data from Y
- loads(X,Y) ⇔ webservice(X), library(Y), X use functionalities from Y
- usesAsPartner(X,Y) ⇔ orchestration(X), webservice(Y), Y is a partner of X

Extracting diagrams

The arch_gen.sh shell script can generate graphviz diagrams from this representation.

Computing the big picture into out.png:
- ./arch_gen.sh
Computing the big picture into f.png:
- ./arch_gen.sh f.png
Computing a predefined diagram:
- ./arch_gen.sh orchestrations.png orch_arch
- ./arch_gen.sh webservices.png orch_arch
Computing a dependencies graph:
- ./arch_gen.sh cachedFeedReader.png “dgraph([cachedFeedReader])”

Extracting dependency graph from Website

The arch_gen.php script bind prolog to php and allow dynamic generation of dependency graph.

Installing the script

You'll just have to retrieve the raw script from here: arch_gen.php.

As the web script will automagically synchronize its descriptor from the SVN repository, the www user MUST be able to write data inside the folder you're using.

Then, open the script and specialize it for your own web server, by editing the three following constants:

define("SWIPL","/opt/local/bin/swipl");
define("NEATO","/sw/bin/neato");
define("FONT_PATH","/System/Library/Fonts");

SWIPL ⇒ path of the SWI prolog interpreter
NEATO ⇒ path of the neato command
FONT_PATH ⇒ path where usual fonts are stored on your system

Running the script

Assuming you've deploy the script inside a folder available at the URL http://server.domain/arch_gen.php:

Dynamically inside a web browser:
- Just use the following url: http://server.domain/arch_gen.php?target=entity
From a plain HTML page:

<div align="center" >
  <img src="http://server.domain/arch_gen.php?target=entity" />
</div>

From a dokuwiki page:
- External images are well supported inside dokuwiki, *Excepting** when the URL contains optional arguments. So, you'll need to allow html code from the admin interface, and then use the following syntax:

<html>
  <div align="center" >
    <img src="http://server.domain/arch_gen.php?target=entity" />
  </div>
</html>

For this website, the script is reachable here: http://www.jseduite.org/webarch_gen/arch_gen.php?target=