diagram application state machine

[cfm]

Description

In https://github.com/freedomofpress/securedrop-client/issues/1420#issuecomment-1069808035, we decided to

take this bug as our cue [...] to zoom out, define carefully how we expect the application to behave across these state machines, and then return to code-level work from that understanding.

This line of investigation has resulted in https://gist.github.com/cfm/4f9f84651312ec446b3a380b1772259a, a draft "grand unified state machine" for the operation of the SecureDrop Client. While this draft is both (a) incomplete and (b) aspirational, there's broad consensus on the team that a future version of this diagram this will be a useful addition to the Client's architectural documentation. This ticket tracks the development, revision, and acceptance of this diagram.

User Stories

As a developer, I want to be able to use a canonical visual aid to reason about [changes to] the low-level behavior of the SecureDrop Client.

[sssoleileraaa]

As a developer, I want to be able to use a canonical visual aid to reason about [changes to] the low-level behavior of the SecureDrop Client.

Thanks, Cory! Onboarding new engineers has made this user story very clear to me. Once we get a good visual representation of what's actually happening in the client, whether it's before or after #1420 is resolved, I think we should add it the architecture wiki page (note that the workstation docs does not include a developer section): https://github.com/freedomofpress/securedrop-client/wiki/Architecture, and consider this issue resolved. What do you think?

[cfm]

Goal for this sprint: Accomplish @creviera's suggestion in https://github.com/freedomofpress/securedrop-client/issues/1452#issuecomment-1081275141 and use that to decide on more-conclusive next steps on #1420.

[cfm]

My draft so far is able to (aim to) be grand and unified only by being a prescriptive monolith. @gonzalo-bulnes and I concluded yesterday that the reasonable way to approach this task descriptively is to diagram the current implementation at the level of individual components (e.g., RunnableQueue → ApiJobQueue → Controller). I'm going to post drafts to the wiki by the end of today to wrap this up in the spirit of a time-boxed !ship.

[cfm]

Time-box results:

The RunnableQueue/ApiJobQueue state machine is documented in https://github.com/freedomofpress/securedrop-client/wiki/Architecture#queue-architecture. Feedback welcome!

As I sort of expected, the implicit Controller-level state machines—such as those handling authentication, synchronization, and the results of individual jobs—are individually too simple to be much illuminated by descriptive diagramming. It's in their interactions that these implicit state machines become complicated and hard to reason about. (Thus, alas, the monolithic-prescriptive approach.)

What is illuminating, as I discovered in #1454, are call/caller graphs. I'll have a pull request in tomorrow to add a make docs target that uses Doxygen to generate browseable documentation, including call/caller graphs, from the securedrop_client package.