Application Design and Architecture ↑

Author

Ariel Ortiz

Date

November 26, 2015

I explain here how to write the documentation for your final project. As an example, I provide a simple Greeter web application, which is just a glorified version of the classical Hello World program but running on the web and producing results in different natural languages.

The directory structure for the application and its documentation is as follows:

greeter/
      ├─ doc/                        Folder produced by RDoc.
      ├─ images/                     Folder for the documentation's image files.
      └─ src/                        Folder for the application's source code.
           ├─ public/                Folder for the server's public documents.
           │       └─ stylesheets/   Folder for the application's CSS files.
           ├─ models/                Folder for the application's models.
           └─ views/                 Folder for the application's views (ERB files).

This is the command used to produce this documentation (running it from the greeter directory):

rdoc --exclude ".json|.css" src

The root of the documentation should now be available at: greeter/doc/index.html

Installing and Running the Application ↑

Use this section to explain any details on how to install and run you application.

To run the Greeter web server you only need to type the following command at the terminal from the greeter/src directory:

ruby -I . -w server.rb

Afterwards, point your web brower at the following URL: http://localhost:4567

Class Diagrams ↑

The following figure represents the UML class diagram for the Greeter model and its factory class:

You can include as many of these diagrams as you consider necessary. Note that you only need to specify the names of the classes and their relationships. Don't include attributes or method names in these diagrams.

To include an image in this document, copy it to the images directory and refer it as: link:../images/some_image.png. You can use any web supported image format (PNG, JPEG, GIF, etc.).

Entity Relationship Diagram ↑

In this section you should include your database's Entity Relationship Diagram (ERD) using Chen's notation. The Greeter web application doesn't use a database, but a generic ERD looks something like this:

Deployment Diagram ↑

UML deployment diagrams show a system's physical layout, revealing which pieces of software run on what pieces of hardware. This is the deployment diagram for our application:

Patterns Used ↑

Briefly mention all the patterns that your application uses and identify where exactly. In our example, the following pattern are clearly used:

Acknowledgments ↑

This section is optional. If somebody helped you with your project make sure to include her or his name here.

References ↑

Mention here any consulted books or web resources. Examples: