README: document architecture

diff --git a/README.adoc b/README.adoc
index 711f96607b751aafb4c21b725e1d2a9a9492f1f4..b3950761841c2613a274a3328f18756a5272506d 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -114,6 +114,43 @@ beginning of the CI script. The cache is stored as `punyci-cache-$job` in the
 (bare) repository.
 
 
+== Architecture
+
+=== Execution
+
+For each job the following steps are executed:
+
+- Clone the repository
+- Start given image as detached container in Podman which waits forever,
+  mounting the repository and cache (optional)
+- Execute the script to run the CI job
+  . If the CI runs in the foreground write the output to stdout/stderr
+  . Otherwise write it to the log file
+- If the script exits with a non-zero exit code wait for the container to
+  exit with a timeout of one hour
+- Kill the container
+
+=== Container
+
+The following files and directories are mounted in the container:
+
+- `/punyci-cache/`: persistent cache for this job, only if `Cache` is true
+- `/punyci-repo/`: clone of the repository, separate for each job
+- `/punyci-script`: configured `Script` of the job (read-only); executed with
+  `/punyci-repo/` as working directory
+
+=== Repository
+
+The following files and directories are stored in the Git repository (either
+in the bare repository itself or in `.git` for non-bare repositories); `$job`
+is the index of the job (starting from zero):
+
+- `punyci-cache-$job/`: persistent cache
+- `punyci-log-$job`: log of the last run of this job
+- `punyci-failed-$job`: empty file created if the last job failed, used to
+  report "fixed" jobs (gets deleted when a job is fixed)
+
+
 == Licenses
 
 punyci is licensed under GPL 3 or later.