Architecture - Writing Architecture Documents

This page provides some guidelines for preparing architecture documents.

Resources

• SEI books - Documenting Software Architectures, Software Architecture in Practice
• Lustre Mailing Lists - in particular, the lustre-devel mailing list used by Lustre developers to discuss Lustre internals, code changes, and other topics of interest to developers.
• Good example of a feature architecture - Simple Space Balance Migration

General Guidelines

• Discuss everything on the lustre-devel mailing list; avoid private discussions until the choices are accepted
• Arch pages should be short and sweet; if printed, most components would fit 1-2 pages; major components maybe 5-10 (say for the LRE)
• Take care with formatting, make them look nice -- people can read these all over
• Use consistent formatting:
  • Summary QAS features - Simple Space Balance Migration
  • Detailed QAS - Adaptive Timeouts
  • Definition lists - Simple Space Balance Migration

Process Outline

1. Get your architecture assignments and priorities from the Lustre Architectural Feature Google spreadsheet
   • this page is maintained by the Chief Architect and VP engineering
   • the Responsible Architect(s) column
     • identifies who needs to generate the architecture
     • is populated initially based on the current engineering organization, but may change based on priorities and negotiation on the lustre-devel mailing list
     • the first person is the list is "on the hook" to deliver; project managers will be coming after you to complete this work
     • the others architects are responsible for contributing to the design
   • the "link" column identifies the page on the Lustre Architecture wiki were you work should be published
2. Make a list of summary requirements, using line per row, and an indicator what kind of use case they are. There are templates and patterns to aid you in finding solutions.
   1. quality attribute scenarios, focus on the following six attributes.
      • performance
      • availability
      • testability
      • modifiability
      • usability
      • security
   2. features
   3. implementation constraints
   4. Examples:
      • features - e.g. offer posix interface for this or that, or replicate file systems, but not atime
      • qualities - e.g. provide performance of 90% of hardware, propagate changes within 1 sec, recovery without semantic changes to clients
      • implementation constraints - e.g. use POSIX DMU, or use existing llog code, or use replication code from cmd2
   5. document this on your assigned architecture wiki page. If there are many, start a separate QAS page
3. Review use cases with Chief Architect and architecture team
   • send an email to the lustre-devel mailing list, requesting an inspection for your high level use cases; specify your architecture wiki page for convenience
   • this is an important quality gating step; be sure to get approval and make required updates before proceeding
4. Review use cases with key customers
   • your project manager will help broker this step for you
   • the key customers for each feature are identified in the Architectural Features Google spreadsheet
   • ask them to review and provide questions and feedback on the use cases; in particular, have we overlooked any key scenarios?
   • discuss relevant feedback on the lustre-devel mailing list and revise use cases as required
5. Decompose the problem into a more detailed architectural definition
   • almost all architecture starts by decomposing the problem
   • write down the subsystems and the functionality and interfaces offered by each
   • often a list of definitions is useful, like "agent = a daemon receiving commands to move data", "coordinator == a daemon running on ... " etc.
   • it is pretty important that the decomposition leaves no doubt about what happens where
6. Write detailed behavioral architecture
   1. Write detailed attribute scenarios
      • pick the hardest use cases from the table
      • describe in more detail what happens when they take place, for each of the components you have identified in the decomposition phase
      • Use existing template tables from the example pages
   2. Sequence and State Diagrams
      • Use UML2 notation - see the petascale white paper for some examples
      • for example, "what is the RPC pattern to handle a lock revocation"
   3. Write detailed command invocations
      • use cases can contain exact command invocations: type mkfs.lustre --mds ...... (all arguments ) to achieve ......
7. Review architecture with architecture team
   • send an email to the lustre-devel mailing list, requesting an inspection for your draft architecture document; specify your architecture wiki page for convenience
   • We follow the benevolent dictatorship model, we are done when Braam says we are done.
   • Typically several weeks are needed for things to settle
8. Review architecture with key customers
   • your project manager will help broker this step for you
   • the key customers for each feature are identified in the Architectural Features Google spreadsheet
   • discuss relevant feedback on the lustre-devel mailing list and revise the architecture as required
9. Cross reference
   • Add bugzilla link to architecture pages (in a Reference section at the bottom)
   • Add an architecture link to the planning worksheet
10. Finish up by preparing the task planning worksheet (which has its own process)

Examples

Example Architectures

• Simple Space Balance Migration
• Client Cleanup - for bigger projects sometimes one separates out a whole page of QAS (requirements)