sparc_phase: P project: pediatric-news created: 2026-05-11 author: claude-vps status: draft spec_link: ./01-specification.md

Pseudocode — Pediatric News (Telegram + Threads + Infographic)

High-level flow

Cron tick спрацьовує 3×/день. Pipeline робить fan-in (RSS+select) → fan-out на 3 паралельні output'и (Telegram-пост з PNG, Threads-thread, лог). seen_ids.json — точка дедуплікації, оновлюється після успіху Telegram (мінімальний commitment).

Основний flow

1. CRON tick @ 05:00 / 11:00 / 17:00 UTC
2. load_seen()  # set з seen_ids.json
3. articles = fetch_rss(MAX_AGE_HOURS=90)
   3a. для кожного з 5 RSS-feed'ів → перші 10 entries, filter за cutoff
   3b. помилка одного feed — log + continue
4. new_articles = articles - seen
   4a. якщо порожньо → exit «no new articles»
5. selected = gemini_select_and_format(new_articles[:15])
   5a. retry 1× з batch=8 якщо timeout
   5b. якщо all fail → log error, exit
6. selected містить: {source_article, telegram_html, summary, link, journal}
7. FAN-OUT (паралельно через threads / asyncio.gather):
   ├── 7a. infographic_pipeline(selected)
   ├── 7b. telegram_pipeline(selected, png_path_future)
   └── 7c. threads_pipeline(selected)
8. join fan-out → collect (tg_ok, threads_ok, png_ok)
9. якщо tg_ok → seen.add(selected.id); save_seen()
10. log_metrics({tg_ok, threads_ok, png_ok, timings})

Альтернативні flows / сценарії помилок

Scenario 1: Gemini timeout

gemini_call(batch_15, timeout=60)
  → TimeoutError → retry with batch_8, timeout=45
  → still fail → log "[Gemini] hard fail" + exit без поста

Scenario 2: Threads reply падає (permission error)

threads_publish(root)        → OK, root_id збережено
threads_publish(reply_1)     → 403 permission
  → log warning, НЕ блокуємо tg_ok, root залишається у фіді одиничним
  → daily-metrics позначає depth=1 замість 3

Scenario 3: PIL render fail

render_png(spec)
  → Exception (шрифт missing / spec невалідний)
  → telegram_pipeline отримує png=None → sendMessage (text-only) замість sendPhoto
  → log degraded

Ключові структури даних

Article (RSS-entry): id, title, summary, link, source, published — те, що віддає feedparser
SelectedPost: source_article + telegram_html (з sanitize) + machine-readable: cohort/N/journal/year/key_finding (для infographic spec)
InfographicSpec: JSON {headline, subtitle, section_label, bullets[], twist, footer_source, footer_handle}
ThreadsThread: [{role:root, text}, {role:reply, text}, {role:reply, text}]
MetricsEvent: timestamp, article_id, tg_ok, threads_depth, png_ok, gemini_ms, total_ms — append-only JSONL

Псевдо-функції / responsibilities

fetch_rss(hours) → list[Article] з 5 feed'ів, з age-filter
gemini_select_and_format(articles) → SelectedPost (Telegram-HTML + machine fields)
build_infographic_spec(post) → InfographicSpec (через infographic-builder skill, Gemini)
render_png(spec) → PNG path 1080×1080 (PIL, детермінований)
build_threads_thread(post) → ThreadsThread (через threads-news-editor agent)
telegram_publish(html, png_path|None) → bool
threads_publish_thread(thread) → int depth (0..3) посилаючись на reply_to_id chain з 30-60 сек пауз
persist_seen(id) → атомарне save_seen()
log_metric(event) → append у /var/log/pediatric-news.jsonl

Інтеграції зі сторонніми системами

RSS (feedparser): 5 публічних feed'ів, no auth, rate ~ unlimited
Gemini API (через gemini CLI): timeout 60s, prompt-template = telegram-news + окремий = infographic-spec + threads-thread
Telegram Bot API: sendPhoto з caption HTML (1024 chars limit на caption!), fallback sendMessage
Threads Graph API: POST /threads (create container) → POST /threads_publish (publish), пауза 30-60 сек, reply_to_id chain

Що НЕ робимо у логіці

НЕ публікуємо у TikTok / Instagram Reels (Non-goal #1)
НЕ запитуємо approval людиною перед публікацією (Non-goal #5)
НЕ генеруємо AI-картинку (infographic-builder свідомо PIL, не image-gen)

Відкриті питання

Чи робити fan-out справді паралельним (asyncio) чи послідовним для простоти debug?
Caption Telegram-photo має 1024-char limit — обрізати чи робити sendPhoto+sendMessage у threadi?
Threads-thread треба будувати з тих самих machine-фактів (N, journal, year) чи окремо запускати Gemini ще раз на summary?

Sign-off

[ ] Сергій / тех-leader schválив
[ ] Дата approval: 2026-05-11
[ ] Перехід на наступну фазу: A (Architecture)

🤖 PM Changelog

2026-05-11: повне переписання з bootstrap-template на основі реальної pipeline та нового scope (Threads + infographic)