Skip to end of metadata
Go to start of metadata

Content Guidelines

Sent to Architecture mailing list on 9/14/18 https://lists.acumos.org/g/architecture/message/35

Target completion is 19 October.

The Architecture Guide is broken down into the following sections:

  • Introduction
    • This is drawn directly from the wiki and should be a high-level intro to the project and its architecture aspects. Aimee pulled this section together but it needs to be updated to reflect what the Acumos platform is today
  • Scope
    • This defines what is included in this document. Bryan created the outline in this section. Bryan thinks that is pretty much all that needs to be here, but a section like this is very useful to help the reader see what they will be reading at the next level.
  • Requirements
    • This provides an overview of the capabilities of the platform that are delivered by the various components of the architecture. The current outline of capabilities mirrors the "what is available in Athena" part from Bryan's talk at the LFOSS (see https://etherpad.acumos.org/p/LFOSS18)
    • This section can also expanded to include "Future Features" section which includes e.g. a list of planned features that will have some impact to the architecture.
  • Architecture - This is the core of the document, and is structured per a typical specification, introducing and breaking down the architecture at these stages/focuses:
    • Architecture Overview
      • Intro diagrams that provide
        • (1) an abstracted view of how things fit together in the platform, and the external / internal interfaces (even more abstracted, for brevity/clarity)
        • (2) a "normative" diagram (meaning something that can be specifically built to), in the form of an "entity relationship diagram", to the extent expressible in a single diagram (or as likely needed, multiple), every discrete component of the architecture and a (still abstracted, at this level) view of what they consume and provide from/to other components and external interfaces. More detailed diagrams will be referenced from the developer guide of each component.
        • (3) Other types of architecture diagrams we find useful. The emphasis is here on usefulness - what does someone getting involved in this project, with a background in architectures of similar systems, need to know to quickly come up to speed on how this platform is built.
    • Entity Relationships Component Interactions
    • Interfaces and APIs
      • External
        • For every externally exposed API, a comprehensive intro to its purpose and use. "Intro" means that the details may be somewhere else, but need to be referenced at least in this section.
      • Internal
        • This section includes a subsection for every component that consumes or provides an API. Both need to be listed/described at a high level (bullets with references are adequate). There will likely be some duplication in this section, but for clarity we need to describe the interfaces for each component comprehensively (in scope at least, but not in detail here).
        • Even though internal APIs are likely more numerous and in flux, there should at least be an intro to these APIs at some useful level of grouped detail, with references to where the details are.
    • Core Components
      • Grouped per the project that "owns" the components, this section is intended to provide an intro to the scope, role, functions, interactions, etc of each of these components in the architecture at a high level. At most a few paragraphs should suffice, but the reader should come away with a pretty clear understanding of why this discrete component exists in the architecture. Each section should contain a link to the the component's "index.rst" so that readers can explore further.
    • Supporting Components
      • As above for components that are not considered "core" parts of the platform, but important to explain the architecture nonetheless. These may be components that are optional/replaceable or deployable using other means in specific deployments, etc.
  • Platform Flow
    • This section should include message flows showing external and cross-component interaction for a few important use-cases or "user journeys". Such flows are very important to understand the actual behavior of the system at high level, and should be supplemented in developer guides with even more detailed flows.

    • I recommend that we look to tools which offer easily-maintained message flows, such as web-based flow generators that take simple text input (analogous to RST, for flows). I have such tools that you can install on your workstation, or you can look at https://www.websequencediagrams.com/ or https://bramp.github.io/js-sequence-diagrams/ (this is the open source tool that I have created an offline version of).
    • We can also build a starting library of flows using tcpdump-captured network traces that are processed through wireshark/tshark. This is an easy way to visualize things that you may not realize are actually going on... for me an essential debugging tool. An example is https://wiki.acumos.org/display/SEC/Validation+Flow, from the early work I did to try to understand the operation of the validation-security component.


Development Guidelines

Sent to Architecture mailing list on 9/13.  https://lists.acumos.org/g/architecture/message/34

Repo location: documentation/docs/architecture
Each section is a separate file to make it easier for multiple people to work on various sections concurrently.

Jira User Storyhttps://jira.acumos.org/browse/ACUMOS-426
Five tasks for updating each section of the Architecture Guide have been created under Acumos-426.

As discussed previously, the Architecture Committee can decide which Architects will work on which sections.

The content is created using ReStructuredText (RST) markup syntax and then pushed to Gerrit like any other source code patch. You will need a Linux Foundation ID to contribute patches.

Resources:


Some more notes on the Architecture Guide template and your input into it:
1) If you want to send Aimee text for the sections related to your project/components, the Docs team will make the updates to the RST file(s).
2) if you want to send updated diagrams, the Docs team will also include them where you reference them in your text. Make sure you send/reference at least the diagram source file, so it can be put into the docs repo along with saved images (you can send them, or the Docs team will generate them if you specify the tool you used to create the diagrams).

The above are intended as a one-time service to help get this doc off the ground. Going forward, there needs to be a team of overall architects or PTLs for the project who will maintain their sections in this doc by collaborating/coordinating on patches to it.

  • No labels

2 Comments

  1. I just went through the Content Guidelines at high level.  I have query : As per the industry standards Entity Relationships (ER diagram) represent the abstract data model (w.r.t https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model)that defines a data or information structure required to perform some business processes.  Also the example link provided in Guidelines shows the relationships among the OpenStack services and not about the data model/structure.  

    I possible can we rename Entity Relationships to some thing else (for. e.g. Service Relationships or Component Interaction Diagram, etc)


    1. That's a great point! Component Interaction Diagram is very descriptive and fits better the type of diagram we need.