Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • 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.

...