Controller architecture

arvados (Apache2) defines a Provider interface with the Arvados database operations, like CollectionList(context.Context, ListOptions) (CollectionListResponse, error).

rpc (Apache2) implements arvados.Provider by calling an Arvados controller's http service.

pgdb implements arvados.Provider by doing PostgreSQL queries. Enforces permissions, validations, model integrity.

pgdb/container implements the Container/ContainerRequest methods of pgdb.Provider. Similarly: pgdb/collection, pgdb/user, etc.

pgdbrow provides generic functions (used by pgdb/container et al.) to translate between object fields/transformations and SQL rows/statements.

model validates create/update operations (called by pgdb before doing insert/update statements)

federation implements arvados.Provider by fanning out to multiple arvados.DBClient backends (typically one local and several remotes, to suit cluster config). Federation-unaware APIs just call through to the default (local) Provider.

router provides an http.Handler that maps each HTTP request to a Provider action: deserialize the request to a Provider call signature, check auth scope, call the Provider method, and serialize the return values as an HTTP response.

controller reads a cluster config file and starts a server backed by a federation.Provider.

Diagram: https://docs.google.com/drawings/d/1Qsj7Re4kE1tNMy7RaNR_dc9U5t6vswMJOhCI2YlbsCM/edit?usp=sharing

The rpc, federation, and pgdb providers offer the same interface so any given program can switch easily between using the federation and model logic built into its own binary and calling out to a different process or host.