m0rph3us1987/10Backward
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation to OKF v0.1 format

Browse Source
This commit is contained in:
OpenVelo Agent
2026-08-04 18:00:52 +00:00
parent 9dc62aed73
commit feadda663a
2 changed files with 15 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/config-schema.md
+13 -7
View File
@@ -41,13 +41,15 @@ environment for the container to boot.
`DEFAULTS` in `config.py` provides fallback strings that `apply_defaults` `DEFAULTS` in `config.py` provides fallback strings that `apply_defaults`
fills into the merged map **before** validation runs: fills into the merged map **before** validation runs:
| Default key | Default value | | Default key | Default value |
|-----------------------|-------------------| |-----------------------|-------------------------------------------|
| `VISIBILITY` | `public` | | `VISIBILITY` | `public` |
| `THROWNBACK_PREFIX` | `Throwback:` | | `THROWNBACK_PREFIX` | `Throwback:` |
| `MAX_RETRIES` | `3` | | `MAX_RETRIES` | `3` |
| `TZ` | `Europe/Berlin` | | `TZ` | `Europe/Berlin` |
| `RUN_AT` | `09:00` | | `RUN_AT` | `09:00` |
| `BLOG_REPO_URL` | `https://git.chaospott.de/Chaospott/site` |
| `BLOG_DIR` | `blog` (resolved relative to `data_dir`) |
Because every required key carries a default, a freshly-initialised Because every required key carries a default, a freshly-initialised
container can still boot to validate the scaffold, but the operator container can still boot to validate the scaffold, but the operator
@@ -68,6 +70,8 @@ ideally `SITE_URL`) to make a real run.
| `run_at` | `str` | `RUN_AT` | | `run_at` | `str` | `RUN_AT` |
| `tz` | `str` | `TZ` | | `tz` | `str` | `TZ` |
| `data_dir` | `Path` | Constant: `Path("/app/data")` | | `data_dir` | `Path` | Constant: `Path("/app/data")` |
| `blog_repo_url` | `str` | `BLOG_REPO_URL` |
| `blog_dir` | `Path` | `BLOG_DIR` resolved against `data_dir` |
# Validation Behaviour # Validation Behaviour
@@ -80,6 +84,8 @@ problem joined with `"; "`. Validation covers:
* `MASTODON_BASE_URL` and `SITE_URL` parse via `urllib.parse.urlparse` * `MASTODON_BASE_URL` and `SITE_URL` parse via `urllib.parse.urlparse`
with an `http`/`https` scheme and a non-empty `netloc`. with an `http`/`https` scheme and a non-empty `netloc`.
* `VISIBILITY` is one of `{"public", "unlisted"}` (`ALLOWED_VISIBILITY`). * `VISIBILITY` is one of `{"public", "unlisted"}` (`ALLOWED_VISIBILITY`).
* `BLOG_REPO_URL` (optional, has default) parses via `urllib.parse.urlparse`
with an `http`/`https` scheme and a non-empty `netloc` when present.
* `TZ` resolves via `zoneinfo.ZoneInfo`. * `TZ` resolves via `zoneinfo.ZoneInfo`.
* `MAX_RETRIES` parses as a non-negative integer (rejects bools). * `MAX_RETRIES` parses as a non-negative integer (rejects bools).
docs/architecture/system-overview.md
+2 -2
View File
@@ -34,7 +34,7 @@ foreground of the `cron` process. Each scheduled invocation calls
| `tenbackward.config` | Loads `.env` + process env, applies defaults, validates schema, produces a typed `Config` dataclass. | | `tenbackward.config` | Loads `.env` + process env, applies defaults, validates schema, produces a typed `Config` dataclass. |
| `tenbackward.logging_setup` | JSON formatter (one log record per line), secret redaction, and `log_startup` / `log_error` / `log_run_summary` helpers. | | `tenbackward.logging_setup` | JSON formatter (one log record per line), secret redaction, and `log_startup` / `log_error` / `log_run_summary` helpers. |
| `tenbackward.state` | Read/write of `posted.json` (atomic temp-file replace). | | `tenbackward.state` | Read/write of `posted.json` (atomic temp-file replace). |
| `tenbackward.blog` | Stubbed blog clone/update helper (lands in a follow-up job). | | `tenbackward.blog` | GitPython `ensure_repo()` — clones the configured blog repo on first run, fast-forwards it via `pull --ff-only` thereafter, with exponential-backoff retries on transient network errors. |
| `/etc/cron.d/tenbackward`| Rendered cron file. One daily line that `cd /app` and runs `python -m tenbackward`. | | `/etc/cron.d/tenbackward`| Rendered cron file. One daily line that `cd /app` and runs `python -m tenbackward`. |
# Communication & Wiring # Communication & Wiring
@@ -80,7 +80,7 @@ foreground of the `cron` process. Each scheduled invocation calls
| `/repo/src/tenbackward/config.py` | Env merging, defaults, validation, `Config` dataclass, `ConfigError`. | | `/repo/src/tenbackward/config.py` | Env merging, defaults, validation, `Config` dataclass, `ConfigError`. |
| `/repo/src/tenbackward/logging_setup.py` | JSON formatter, secret redaction, structured event helpers. | | `/repo/src/tenbackward/logging_setup.py` | JSON formatter, secret redaction, structured event helpers. |
| `/repo/src/tenbackward/state.py` | `posted.json` read/write with atomic temp-file replace. | | `/repo/src/tenbackward/state.py` | `posted.json` read/write with atomic temp-file replace. |
| `/repo/src/tenbackward/blog.py` | Stubbed blog clone helper (not yet wired into the pipeline). | | `/repo/src/tenbackward/blog.py` | `ensure_repo()` — GitPython clone + fast-forward pull with `2^n` retry/backoff; raises `BlogRepoError` on local modifications or exhausted retries. |
| `/repo/.env.example` | Canonical list of environment variables. | | `/repo/.env.example` | Canonical list of environment variables. |
| `/repo/docker-compose.yml` | Service definition; binds env vars from the host `.env`. | | `/repo/docker-compose.yml` | Service definition; binds env vars from the host `.env`. |
| `/repo/Dockerfile` | Builds the runtime image. | | `/repo/Dockerfile` | Builds the runtime image. |