Click on parts of the diagram for an explanation of Reef's workflow, or start with Step 1.

A developer is anyone who edits the source code of the object-oriented application. Reef is most suitable for small to medium-size, co-located or distributed teams following an agile development process with little up-front design. Reef initially supports Java applications and UML design diagrams, but could be adapted to work in other settings.  Within those constraints, Reef follows adoption-centric principles by adapting to the developer's preferred tools and workflow.

A code repository holds versions of the source code and other resources that punctuate the evolution of the application. Initially, Reef supports file system and CVS stores, but can be extended with other version control system adapters.

Reef's back-end runs a continuous autonomic control loop on the server, regularly checking the repository for changes, publishing updated documentation, and interacting with team members through diagram agents. It stores data in an embedded XML database and accepts plug-ins at well-defined extension points.

UML diagrams are rendered in SVG 1.2 and pack their own browsing and editing facilities (programmed in ECMAScript). Since they are self-contained, requiring only an SVG viewer to be displayed, they can be transmitted freely to and edited by any interested parties without worrying about installing a special-purpose diagramming tool. The agents can operate in both on-line and off-line environments, automatically tailoring their features and communication techniques.

The documentation set generated by Reef cross-references the design-level diagrams with implementation-level descriptions (e.g. Javadocs) and possibly the source code itself. The documentation also includes a variety of metrics related to the source code, the diagrams, and the development and documentation process.  (For example, it would be possible to see which diagrams are most in need of ratification, or who has been remiss in their documentation duties.)

The developer commits some changes to the application's source code to the repository, using their favourite tool, unaffected by (and possibly even unaware of) Reef. It is advantageous if the commits follow best practices by including an appropriate message and being applied in small, cohesive chunks, but Reef will adapt to less disciplined approaches as well.

When Reef detects that the application's source code has changed in the repository, it checks out an up-to-date version and, by means of reverse-engineering techniques, propagates the modifications to the application's design model. The update process is incremental, so that reasonably sized commit sets can be handled quickly even for large applications. Furthermore, updates to the UML diagrams extrapolate previous adjustments made by the editors (see Step 4) to reduce their workload, and do not unnecessarily change the layout of the diagram to preserve the readers' mental map of the design.

Any UML diagrams that have sustained non-trivial changes are sent by Reef to the appropriate editors with the changes highlighted. Email is the preferred transport mechanism, due to its features (e.g., authentication, off-line availability) and universal cognitive support, with instant messaging, RSS and manual web page polling rounding out the picture. By default, a diagram is sent to the developer responsible for the majority of the relevant changes, but the recipient can delegate the responsibility by forwarding the message to somebody else. Whoever finally ratifies the diagram becomes its editor and is implicitly added to the development team, thus enabling a viral spread of the tool. If the diagram is not ratified for a long time, Reef may decide to resend the request to the same or another editor.

Editors fix the diagrams and ensure that they provide an accurate and useful representation of the application. Human involvement is necessary since some design-level properties are diffused beyond recognition in the implementation, making them unrecoverable by automated reverse-engineering techniques. Furthermore, an editor makes important decisions about what to elide from the diagrams to maximize their communicative value. To make the editor's job easier, the diagram indicates any reverse-engineered changes and links them to commit set comments and ultimately to the source code. Any edits can also be amplified, teaching Reef by example how to improve future diagrams. When the editor is satisfied with the diagram, he ratifies it and submits it back to Reef.  Although ratifying a diagram should only take a few minutes, the editor can also delegate the task (see Step 3), postpone it, or obsolete the diagram altogether.

As ratified diagrams pour back into Reef's back-end, they are embedded into the application's documentation and published to a web server. Team members are notified of updates to diagrams (if so requested), enabling them to track the evolution of the application at a higher level of abstraction than the raw repository change logs would, increasing the team's awareness.

At any time, team members can browse the application's documentation. All documentation is cross-referenced, so there's no need to decide a priori whether implementation or design documentation is relevant to the problem at hand. The ratified UML design diagrams are time-stamped and version-stamped, so that developers can be confident they're not stale; if the browser is running in on-line mode, a diagram can even report how well it matches the current source code. Finally, all the diagrams are still self-editable, so readers can make opportunistic corrections if so authorized.