Review of architecture document

1
Review of architecture document

• Consortium meeting
• Edinburgh
• December 2004

2
Before or after?

• Architecture before implementation
• Prescriptive
• We didnt record this centrally
• Contracts
• Architecture after implementation
• Descriptive
• Current document.

3
What is architecture

• Parts catalogue
• Compile time (e.g. classes, source-files)
• Time of deployment (e.g.WARs, properties file)
• Run time
• Interfaces
• Syntatic (e.g. WSDL)
• Semantic
• Parts interfaces relationships
• Relationships change control contracts

4
Uses of descriptive architecture

• What does this bit do?
• Where are the classes that do x?
• How does it do y?
• Z doesnt work what parts could be at fault?
• What services does this sub-system provide?
• If I change this, what does it affect?
• Which bits do I install on my site?
• You installed this on my site what for?
• How can I attach my s/w to AstroGrid

5
Prescriptive architectureContracts

• One contract per major interface
• Contracts have version control
• Subsystems document their contracts
• Developers may not merge code that breaks
  contracts
• Need to record a new contract version first.
• Intelligibility of contract tracks cohesion,
  coupling

6
Architecture for whom?

• Mainly for engineers
• AstroGrid developers
• External partners
• Some use to service providers
• Why am I deploying this part?
• What other parts support this part?
• Passing interest to end users
• Because open source.

7
What the architecture doc. is not

• The user manual
• The science requirements
• The analysis of requirements
• Could be stored as appendix to architecture
• The project history
• Lists of technical decisions could be part of the
  architecture. Q.v Brooks, MM-M.
• Therefore, not the best document for some
  readers.

8
Current architecture document (1)

• Represents the system at the end of Itn6.
• As-built description
• No prescriptive role
• therefore no contracts
• Reverse engineered
• From AstroGrids Maven-project structure live
  tests
• Therefore not necessarily accurate
• therefore this review.
• Preparing to do a major revision for end Itn7.

9
Current architecture document (2)

• Technical!
• Based on UML model of system
• Built in Together Control Centre
• Published on the web
• http//astrogrid.ast.cam.ac.uk/architecture-itn6/
• Most pages generated by TCC from model
• A few hand-written essays
• General introduction

10
Current architecture document (3)

• Known problems
• Missing essays
• No description of the portal
• TCC-generated pages unwholesome
• Some broken links to external pages (ex Maven)
• Incomplete mapping of classes in model to Maven
  projects.
• Incomplete list of use cases
• Doesnt refer back to use cases ex AstroGrid
  science cases
• Not well integrated with CVS control.

11
Challenges in documenting

• The architecture is not simple.
• Coupling is quite high
• Cohesion is quite low (in some areas)
• False information scent
• Javadocs
• Good to acceptable at class level
• Not much at package level
• Portal
• Code documentation lacking
• Understanding by experiment only possible when
  the system works
• Together Control Centre
• It bites!

12
Goals for review groups

• Is the overall form of the architecture
  description acceptable?
• If not, would it be acceptable if more complete?
• Is the description accurate?
• Where does it misrepresent the Itn6 system?
• What has changed since Itn6?
• Is the architecture itself wrong?
• What can most usefully be added to the
  description?

13
Break-out groups

• AG presentation team
• AG data team
• Visitors and partners
• Rooms
• Newhaven room (here)
• Deane room (reception floor)
• Open area (floor below reception)
• Report back after lunch
• 10 15 minute summary from each group, please.
  Further notes welcome by email to
  gtr_at_ast.cam.ac.uk