Перейти к содержанию

Живая архитектурная карта polit-media-radar🔗

polit-media-radar мониторит политико-медийную активность (Telegram, VK) по списку отслеживаемых кандидатов: собирает посты, комментарии, реакции и репосты, затем наслаивает SocialScan-пуллы и LLM-классификацию, чтобы собрать еженедельные «народные» аналитические отчёты.

Эта живая архитектурная карта даёт увидеть систему с высоты — модули, их зависимости и швы между модулями и базой данных — не держа всё в голове и не читая код.

Две модели документации🔗

Карта построена на двухслойной модели из практики Living Documentation и делении Diátaxis на «справку» и «объяснение»:

flowchart TB
    code["Код + живая схема БД"]
    refl["Reference-слой<br/>(генерируемый — не может соврать)"]
    expl["Explanation-слой<br/>(курируемый — держит замысел)"]
    drift{"Drift-гейт"}

    code -->|tach / tbls| refl
    code -.->|меняется| drift
    refl -.->|сверяется| drift
    drift -->|расхождение → CI краснеет| code
    refl --> expl
    expl -->|«почему»| reader["Читатель: от модуля до таблицы за три клика"]

    classDef gen fill:#e8f0ff,stroke:#36c
    classDef cur fill:#fff3e0,stroke:#b80
    class refl gen
    class expl cur
  • Reference-слой (генерируемый, не может соврать). Граф модулей и ER-диаграммы выводятся механически из кода (tach) и из живой базы (tbls). Они «дрейфят» только когда дрейфят сам код или схема, и drift-гейт это ловит — пересобранная диаграмма сверяется с зафиксированной, расхождение красит CI.
  • Explanation-слой (курируемый, держит замысел). Обзор карты и швы пишет человек или агент, чтобы объяснить почему — границы контекстов, спина candidates/fetch_runs, прямые записи в обход репозиториев.

Один источник истины. Сгенерированные факты не перепечатываются в прозу — на них ссылаются. Если важно число или ребро графа — идите по ссылке к диаграмме, которая им владеет.

Куда смотреть🔗

Раздел Архитектура — точка входа в визуальную часть карты:

  • Обзор карты — связный рассказ: введение, building-block view, runtime-view, data-view, сквозные концепции, и трасса «модуль → таблица за три клика».
  • Граф модулей — 12 пакетов polit_media_radar и их реальные импорт-зависимости (генерирует tach).
  • Швы «модуль → таблица» — какой модуль пишет какую таблицу: seams, включая прямые записи в обход репозиториев и writer-pending-скелеты.
  • ER-диаграммы живой схемы radar, разнесённые по двум ограниченным контекстам, чтобы ни один не превратился в нечитаемый клубок:

В разделе Решения — история выбора инструментов (помечена как superseded пилотом 2026-06-22).

Пилотный прогон: 2026-06-22, проект er. Сайт собирается mkdocs build --strict по курируемому подмножеству страниц.