From: Simon Ruderich <simon@ruderich.org>
Date: Thu, 26 Feb 2026 18:29:21 +0000 (+0100)
Subject: README: document architecture
X-Git-Url: https://ruderich.org/simon/gitweb/?a=commitdiff_plain;h=59ad17e067963c4a176490bfe12b625d51858c0a;p=punyci%2Fpunyci.git

README: document architecture
---

diff --git a/README.adoc b/README.adoc
index 711f966..b395076 100644
--- 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.