Skip to end of metadata
Go to start of metadata

This doc will be published at Architecture Guide. This document is intended as a high-level, yet comprehensive architectural overview of the Acumos platform. It will be developed/maintained by collaboration of platform architects and PTLs. Some notes on the intended content for each section are included in the sections.

  • Introduction
    • This should be a high-level intro to the project and its architecture aspects.
  • Scope
    • This defines what is included in this document. 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" talk at the LFOSS (see https://etherpad.acumos.org/p/LFOSS18)
    • This section can also expand 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:
      • 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.
      • 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.
      • Supporting Components
        • As above, for components that are not considered "core" parts of the platform, but important to explain the arch 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.
    • It's intended that the project use tools which offer easily-maintained message flows, such as web-based flow generators that take simple text input (analogous to RST, for flows). For such tools that you can install on your workstation, see  https://www.websequencediagrams.com/ or https://bramp.github.io/js-sequence-diagrams/ (this is the open source tool that Bryan Sullivan has 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... can can be an essential debugging tool. An example is https://wiki.acumos.org/display/SEC/Validation+Flow, from work to discover the operational details of the validation-security component.
  • No labels