Add/change: document the internal CI components

This is somewhat speculative, as we don't know what the actual
implementation will be like, but rather than let the tool decide the
architecture, I'm trying to present an architecture that makes sense.

2 files changed, 62 insertions, 5 deletions

diff --git a/arch.dot b/arch.dot
index e998ea5..3c0aa60 100644
--- a/arch.dot
+++ b/arch.dot
@@ -5,7 +5,7 @@ digraph ci {
 
         controller [label="CI controller"];
         controller [shape="box"];
-        controller [fillcolor="grey" style="filled"];
+        controller [fillcolor="pink" style="filled"];
 
         vcs_worker [label="VCS worker"];
         vcs_worker [shape="ellipse"];
@@ -21,19 +21,19 @@ digraph ci {
 
         artifacts [label="artifact store"];
         artifacts [shape="cylinder"];
-        artifacts [fillcolor="grey" style="filled"];
+        artifacts [fillcolor="pink" style="filled"];
 
         logs [label="log store"];
         logs [shape="cylinder"];
-        logs [fillcolor="grey" style="filled"];
+        logs [fillcolor="pink" style="filled"];
 
         test_env [label="test\nenvironment"];
         test_env [shape="octagon"];
-        test_env [fillcolor="#0000ee" style="filled"];
+        test_env [fillcolor="grey" style="filled"];
 
         prod_env [label="production\nenvironment"];
         prod_env [shape="doubleoctagon"];
-        prod_env [fillcolor="red" style="filled"];
+        prod_env [fillcolor="white" style="filled"];
         
 
         gerrit -> controller;
@@ -45,6 +45,7 @@ digraph ci {
         artifacts -> build_worker;
         build_worker -> artifacts;
         build_worker -> logs;
+        build_worker -> test_env;
         vcs_worker -> logs;
         controller -> deployment_worker;
         artifacts -> deployment_worker;
diff --git a/ci-arch.mdwn b/ci-arch.mdwn
index fa1851e..adf52f1 100644
--- a/ci-arch.mdwn
+++ b/ci-arch.mdwn
@@ -486,6 +486,62 @@ stages for manual and capacity testing, and security test/review;
 depending on the change and the component in question, some or all of
 these may be necessary.
 
+## CI internal components
+
+![CI components: white is external, pink is persistent, grey is
+ephemeral](arch.svg){ height=50% }
+
+Note: this is speculative for now, until we actually implement at
+least one of the candidates.
+
+The CI system consists, at least conceptually, of several internal
+components, depicted in the architecture diagram above. The actual
+implementation may end up using different components, but the
+conceptual roles will probably still be there.
+
+* CI interacts with **Gerrit** and production externally. Also test
+  environments, but those ephemeral. Gerrit is code review and git
+  server, and produces an event stream to which CI reacts.
+
+* The **controller** listens to the Gerrit event stream and commands
+  the various workers to do things as appropriate. It is the conductor
+  of the symphonic CI orchestra.
+
+* The **VCS worker** interacts with Gerrit in its role as a git
+  server. Only the VCS worker has credentials for accessing Gerrit.
+  The VCS worker retrieves source code via git, does merge and other
+  git operations, pushes changes back to Gerrit (when it's OK to do
+  that), and publishes snapshots of the working tree to the artifact
+  store. Build workers get their source code from the artifact store,
+  not from Gerrit directly. This avoids having to give build workers
+  credentials, or network access, to gerrit, and having to push
+  speculative changes to Gerrit.
+
+* The **artifact store** store blobs of things that CI needs or
+  produces: git working trees, built artifacts, etc.
+
+* The **build worker** runs builds and tests. It gets the source code
+  from the artifact store and publishes built artifact back to the
+  artifact store. There can be any number of build workers running in
+  VMs or containers.
+
+* The **deployment worker** deploys built artifacts to an environment,
+  such as a test environment or the production environment.
+
+* The **log store** stores build logs, what Jenkins calls "console
+  output": the stdout and stderr of the command run to do a build,
+  and to run tests. Also the commands to deploy, and to interact with
+  Gerrit.
+
+* A **test environment** is an isolated environment that is
+  sufficiently like production to running tests. The test may be
+  automated or manual. There can be any number of test environment,
+  and they might be ephemeral, if that turns out to be useful.
+
+* The **production environment** is what the world sees. It's the
+  actual Wikipedia in all the various languages, and all the other
+  sites we run.
+
 ## Normal change to an individual component
 
 * a developer pushes a change to one program that runs in production