System Architecture Document

[Siddhartha Chandurkar <si...@yahoo.com>]

Hi all,

    I have joined the mailing lists just yesterday,
but I was going through the archives for past 1 1/2
weeks. Since some of the work has already been done I
wanted to understand the overall architecture vision
and how the various modules which are under progress
will colaberate. I was looking for a System
Architecture Document. While browsing through the Wiki
Web. I saw in the TODO list a requirement of the
System Architecture Description Document. I have been
working as a System Designer for the past 3 years,
below is a template which I have formulated based on
my past experience with prodcuts.  
If there is no work going on this document. I can
start contributing by writting this document.

    Before I proceed,IMHO. I suggest that we should
have some business drivers of the architecture written
down. Even though these things are important for
commercial products and this being an Open Source
product. In my limited experience this really helps.
This will give us a clear focus and we know the enemy
which we are trying to conquer. (Sun Tzu - "Know your
enemy"). Some of the points that we should consider
are given below.

Business Drivers
================
+ Describe the business history, environment,
requirements, market differentiators, stakeholders,
current need. How the proposed system will meet those
requirements.
+ Business Constraints. e.g. time to market, customer
needs and standards etc.
+ Technical Constraints
+ Quality attribute requirements and the business
needs from they are derived from

Having said that below is a proposed template for
System Architecture Description. Some of the things
might not be relevant or some sections might need to
be added.



                                   SYSTEM ARCHITECTURE
DOCUMENT for Apache's Geronimo project

1. Title
<The Title of the Product>

2. Revision History
<Revision History of the Document>

3. Introduction
A Brief Introduction of the Product
 
3.1 Purpose
<Brief description of the Product and the purpose of
the document, plus the intentended audience>

3.2 Scope
<Scope of the Product>

3.3 Definitions, Acronyms, Terminology and Abrivations
<Descrption of all the terms, acronyms, Abrivations
that will help to understand the Document. 
Reference to the Glossary/Dictionary can be given here
if it is present>

3.4 References
<References to the documents which are input to this
document. Their Title and the location from where
they are accessible>

3.5 Overview
<Explains what this document contains and how the
document is organized

4. Architectural Goals and Constraints
<Section describes the main Arcthitectural goals and
constraints which are driving the architecture>

5. UseCase View
<Scenarios/Usecases (Architecturally Significant Use
Cases) that represent the central functionality of the
system>

5.1 UseCase Realization
<Section describes how these Usecase are realized by
the architecture. How various subsystems contribute to
their functionality

6. Logical View
6.1 Subsystem Decomposition
6.2.n Desription of Subsystems
<This section describes the decomposition of the
System into subsystem, their relationships and
responsiblities>


7. Interaction Diagram Between Subsytems
<The Interaction Diagrams (Sequences) between the
interfaces of the subsystem. Note. The flow should be
on the subsystem interface level. Details of the
subsystem should not be depicted here>

8. Process View
<The section descibes the varoius processes and
threads interact>

9. Data View (Optional)
<Section descibes how the persistent data is managed
in the system>

10. Deployment View
<Section desrcibes how the system will be deployed and
the Hardware configurations it supports> 

11. Quality Attributes 
<Section descibes how the Architecures satisfies the
various quality attributes of the system i.e.
reliability, usability, security, performance,
scalability, modifiability and extensibility,
availability etc.>


thanks & regards,
Siddhartha
http://www.visioncodified.com











__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free, easy-to-use web site design software
http://sitebuilder.yahoo.com

Re: System Architecture Document

[Bruce Snyder <fe...@frii.com>]

This one time, at band camp, Siddhartha Chandurkar said:

SC>    I have joined the mailing lists just yesterday,
SC>but I was going through the archives for past 1 1/2
SC>weeks. Since some of the work has already been done I
SC>wanted to understand the overall architecture vision
SC>and how the various modules which are under progress
SC>will colaberate. I was looking for a System
SC>Architecture Document. While browsing through the Wiki
SC>Web. I saw in the TODO list a requirement of the
SC>System Architecture Description Document. I have been
SC>working as a System Designer for the past 3 years,
SC>below is a template which I have formulated based on
SC>my past experience with prodcuts.  
SC>If there is no work going on this document. I can
SC>start contributing by writting this document.
SC>
SC>    Before I proceed,IMHO. I suggest that we should
SC>have some business drivers of the architecture written
SC>down. Even though these things are important for
SC>commercial products and this being an Open Source
SC>product. In my limited experience this really helps.
SC>This will give us a clear focus and we know the enemy
SC>which we are trying to conquer. (Sun Tzu - "Know your
SC>enemy"). Some of the points that we should consider
SC>are given below.
SC>
SC>Business Drivers
SC>================
SC>+ Describe the business history, environment,
SC>requirements, market differentiators, stakeholders,
SC>current need. How the proposed system will meet those
SC>requirements.
SC>+ Business Constraints. e.g. time to market, customer
SC>needs and standards etc.
SC>+ Technical Constraints
SC>+ Quality attribute requirements and the business
SC>needs from they are derived from
SC>
SC>Having said that below is a proposed template for
SC>System Architecture Description. Some of the things
SC>might not be relevant or some sections might need to
SC>be added.

This is a fine idea and something that is sorely lacking from most Open
Source projects. IMO, a project as big as Geronimo needs this. Many
people spending large amounts of money on 'enterprise' commercial
software have come to expect such artifacts from commercial apps but
when an Open Source app delivers this type of forethought, research,
etc. it lends it that much more credibility. In short, it causes people
to change their mindset from believing that Open Source is just a bunch
of hackers with no plan to believing that there is an organized effort
and therefore true value in the project. This is not my belief I am
simply stating this as a demonstration of what I've heard working for
various companies through the years.

This document is definitely something that needs to be placed in the
Wiki so that others can contribute to it and it can grow.

Bruce
-- 
perl -e 'print unpack("u30","<0G)U8V4\@4VYY9&5R\"F9E<G)E=\$\!F<FEI+F-O;0\`\`");'

The Castor Project 
http://www.castor.org/

Apache Geronimo 
http://incubator.apache.org/projects/geronimo.html