Docs Wishlist

[eddyashton]

We're planning to add some more detailed documentation, initially to the Architecture section with walkthroughs of various systems within CCF. In particular, we'd like to bind these with code navigation aids (like the high-level data flow map here).

This discussion is to collect and describe those planned sections, making sure we're in agreement on their purpose.

Please add any suggestions below!

[achamayou]

A dependency graph of all sub-systems (currently top-level directories under src/) would be useful.

[eddyashton]

Ringbuffer

We should have page describing the ringbuffer communication between host and enclave. It should cover the reason we use a ringbuffer rather than ECalls (performance), the constraints it introduces (message size limits, serialization costs), and potential future work (threaded dispatch within the enclave, replacing the ringbuffer on platforms where it is not necessary). It should also provide a technical guide for contributors of the actual implementation and API - an MPSCQ, abstraction layers for queuing/fragmenting messages, type-checking macros for writing and reading.

[eddyashton]

Historical Queries

We should have an Architecture page describing the historical query and indexing system. It should include sequence diagrams of typical useage, explanation of the caching/ownership model, discussion of potential improvements.

[eddyashton]

Service startup walkthrough

We currently have sandbox.sh which automatically executes service startup, and the Operations and Governance pages which describe the manual steps that must be taken. I think we could usefully bridge the gap between these with an explicit walkthrough explaining all of the steps that sandbox.sh takes, probably as an annotated version of the script's output. This only needs brief descriptions since it can link to the existing sections for a full description of each action, but would make explicit the dependencies between various actions.