docs: update documentation to OKF v0.1 format
This commit is contained in:
OpenVelo Agent
@@ -3,7 +3,7 @@ type: architecture
|
||||
title: System Architecture
|
||||
description: Component map of 10Backward — how configuration, blog synchronization, anniversary matching, logging, the pipeline runner, state persistence, and container entrypoint are wired together.
|
||||
tags: [architecture, overview]
|
||||
timestamp: 2026-08-04T17:51:00Z
|
||||
timestamp: 2026-08-04T18:55:00Z
|
||||
---
|
||||
|
||||
# Overview
|
||||
@@ -12,8 +12,9 @@ timestamp: 2026-08-04T17:51:00Z
|
||||
containerised cron job. Job 1086 adds anniversary matching across Jekyll
|
||||
posts, backed by the blog clone/pull workflow from Job 1084 and the
|
||||
structured logging, retry-capable runner, and deduplication state from
|
||||
Job 1083. The current pipeline identifies matching post paths and records
|
||||
those identifiers; Mastodon publishing is still a future integration.
|
||||
Job 1083. The current pipeline identifies matching posts, publishes a
|
||||
single combined Mastodon status for the new matches, and records the
|
||||
published identifiers in `posted.json`.
|
||||
|
||||
The container boots, validates environment configuration, renders a
|
||||
`/etc/cron.d/tenbackward` entry that fires once per day at the
|
||||
@@ -25,7 +26,9 @@ foreground of the `cron` process. Each scheduled invocation calls
|
||||
2. Loads and validates the `Config`.
|
||||
3. Ensures the data directory exists.
|
||||
4. Emits a `startup` log line.
|
||||
5. Executes one pipeline pass wrapped in a retry loop.
|
||||
5. Executes one pipeline pass wrapped in a retry loop:
|
||||
`ensure_repo` → `find_anniversary_matches` → `PostedStore` dedupe →
|
||||
`publish_mastodon` → `PostedStore.mark_posted_many`.
|
||||
6. Emits a `run_complete` summary (skipped silently if there were no candidates).
|
||||
|
||||
# Components
|
||||
@@ -39,6 +42,7 @@ foreground of the `cron` process. Each scheduled invocation calls
|
||||
| `tenbackward.state` | `PostedStore` — self-contained dedup store. `posted.json` holds `{"posted": [str, ...]}`; mutations are serialised by an `fcntl.flock` on a sibling lock file, writes go through a temp-file replace, and `load()` auto-creates an empty list when the file is missing. |
|
||||
| `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. |
|
||||
| `tenbackward.matching` | Walks `_posts/blog/**/*.md`, parses Jekyll front matter and filenames, and yields posts exactly ten years before the current date using Berlin-time and leap-day rules. |
|
||||
| `tenbackward.publishing` | `publish_mastodon()` — the single success boundary between the runner and the Mastodon HTTP API. Composes a combined status for the day's matches, validates the 500-character limit, and posts via `mastodon.Mastodon.status_post`. Raises `PublishError` on composition, length, or API failure; the runner treats it like any other pipeline exception. |
|
||||
| `/etc/cron.d/tenbackward`| Rendered cron file. One daily line that `cd /app` and runs `python -m tenbackward`. |
|
||||
|
||||
# Communication & Wiring
|
||||
@@ -55,16 +59,30 @@ foreground of the `cron` process. Each scheduled invocation calls
|
||||
| /etc/cron.d/ | -- daily fires --> | tenbackward.main.main |
|
||||
| tenbackward | | - configure logging |
|
||||
+-------------------+ | - retry-wrapped pass |
|
||||
+-----------+-------------+
|
||||
|
|
||||
v
|
||||
+-------------------------+
|
||||
| _run_with_retry(...) |
|
||||
| -> _run_once(...) |
|
||||
| -> PostedStore. |
|
||||
| {is_posted, |
|
||||
| mark_posted_many}|
|
||||
+-------------------------+
|
||||
+-----------+-------------+
|
||||
|
|
||||
v
|
||||
+-------------------------+
|
||||
| _run_with_retry(...) |
|
||||
| -> _run_once(...) |
|
||||
| -> ensure_repo(...) |
|
||||
| -> matching |
|
||||
| find_anniversary_|
|
||||
| matches |
|
||||
| -> PostedStore |
|
||||
| {is_posted, |
|
||||
| mark_posted_many}|
|
||||
| -> publishing |
|
||||
| publish_mastodon |
|
||||
| -> PostedStore |
|
||||
| mark_posted_many |
|
||||
+-------------------------+
|
||||
|
|
||||
v
|
||||
+-------------------------+
|
||||
| Mastodon HTTP API |
|
||||
| status_post(...) |
|
||||
+-------------------------+
|
||||
```
|
||||
|
||||
* **Env → Config.** `load_config()` merges a `.env` file (when
|
||||
@@ -73,10 +91,14 @@ foreground of the `cron` process. Each scheduled invocation calls
|
||||
`Config` dataclass.
|
||||
* **Cron → main.** Each scheduled tick re-runs `python -m tenbackward`,
|
||||
so every run is a fresh interpreter invocation.
|
||||
* **Matching → publishing.** `find_anniversary_matches` yields
|
||||
`MatchedPost` objects; the runner dedupes against `PostedStore`, then
|
||||
passes the unposted objects to `publish_mastodon`. See
|
||||
[Mastodon Publishing](/architecture/mastodon-publishing.md).
|
||||
* **Pipeline state.** `_run_once` reads `posted.json` via
|
||||
`PostedStore.is_posted()` for dedupe, then writes it back via
|
||||
`PostedStore.mark_posted_many()` only when at least one new post
|
||||
was recorded. The store serialises concurrent runs with an
|
||||
`PostedStore.mark_posted_many()` **only after** `publish_mastodon`
|
||||
returns. The store serialises concurrent runs with an
|
||||
`fcntl.flock` on a sibling lock file and writes via temp-file
|
||||
rename.
|
||||
|
||||
@@ -91,6 +113,7 @@ foreground of the `cron` process. Each scheduled invocation calls
|
||||
| `/repo/src/tenbackward/state.py` | `PostedStore` + module helpers (`load_posted`, `is_posted`, `mark_posted`, `mark_posted_many`); list-shaped JSON, `fcntl.flock`, atomic temp-file replace, env-var data dir. |
|
||||
| `/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/src/tenbackward/matching.py` | Jekyll post discovery, front matter parsing, anniversary and leap-day matching, and canonical URL construction. |
|
||||
| `/repo/src/tenbackward/publishing.py` | `publish_mastodon()` — composes a combined Mastodon status, validates the 500-character limit, posts via `mastodon.Mastodon.status_post`. Pure helpers `build_status_text` and `validate_status` keep network code out of tests. |
|
||||
| `/repo/src/tenbackward/__main__.py` | Module entrypoint that invokes `tenbackward.main.main()`. |
|
||||
| `/repo/.env.example` | Canonical list of environment variables. |
|
||||
| `/repo/docker-compose.yml` | Service definition; binds env vars from the host `.env`. |
|
||||
@@ -105,5 +128,6 @@ foreground of the `cron` process. Each scheduled invocation calls
|
||||
* [Logging & Run Summary](/architecture/logging.md)
|
||||
* [Pipeline Runner](/architecture/pipeline-runner.md)
|
||||
* [Anniversary Matching](/architecture/anniversary-matching.md)
|
||||
* [Mastodon Publishing](/architecture/mastodon-publishing.md)
|
||||
* [Environment Variable Setup](/operations/environment-setup.md)
|
||||
* [Cron Lifecycle](/operations/cron-lifecycle.md)
|
||||
|
||||
Reference in New Issue
Block a user