Module Boundaries

Tento dokument popisuje aplikacni hranice mezi top-level moduly Reply Pilotu. Runtime a deploy pravidla zustavaji v docs/container-runtime-contract.md; datovy model a migrace zustavaji v docs/database.md.

Current Baseline

Aktualni baseline je v reports/architecture-report.md a generuje se pres:

python3 script/architecture-report.py --output reports/architecture-report.md

Soucasny stav:

  • produkcni mezimodulove Python importy mezi reply_pilot_* packages: 0;
  • dependency advisory aktualne hlasi chybejici deklarace markupsafe / werkzeug;
  • reply-pilot-app nema runtime zavislost na psycopg, nema produkcni DB-backed directory/record/task store fallback a nema REPLY_PILOT_DB_* runtime konfiguraci;
  • reply-pilot-app nema app-local Gmail/OpenAI implementation fallback; Gmail a OpenAI runtime vlastni backend/Gmail moduly;
  • nejvetsi complexity hotspoty jsou hlavne v reply-pilot-app workflow vrstve a ve zbyvajici backend route-map cleanup praci;
  • opakovane soubory jako config.py, logging_utils.py, email_store.py, views.py a podobne modulove adaptery jsou kandidati na vedome sjednoceni nebo zdokumentovane ponechani.

Module Responsibilities

  • reply-pilot-app: uzivatelske UI a BFF vrstva; vola backend, drzi webove formulare, navigaci, simple-auth callback UI a typed AI prompt UI.
  • reply-pilot-be: hlavni JSON API a orchestracni vrstva pro inbox, email materializaci, Jira, OpenAI, lead import a zapis do Reply Pilot DB.
  • reply-pilot-gmail: Google/Gmail adapter; vlastni OAuth token, Gmail API, Gmail watch stav, mailbox snapshoty, Gmail-owned mailbox cache, attachment bytes a Gmail draft/send operace.
  • reply-pilot-worker: scheduler nad backend HTTP API; nevlastni business logiku jobu, jen intervaly, konflikty behu a status/heartbeat.
  • reply-pilot-jira-reports: samostatny reporting collector pro Jira data; vlastni raw issue/changelog JSONL, CSV agregace a generovane HTML reporty.
  • reply-pilot-search: Solr/search modul; vlastni Solr proces, search HTTP API, sync z Reply Pilot DB a search heartbeat.
  • reply-pilot-db: PostgreSQL schema, konfigurace a Liquibase migrace; nema REST/JSON API.
  • reply-pilot-db-backup: vlastni readonly DB credential, PostgreSQL 17 logical dump workflow a backup artefakty; vystavuje jen interni trigger/status API.
  • reply-pilot-docs: publikace MkDocs vystupu jako dokumentacni HTTP web.
  • reply-pilot-wholesale-scout: batch CLI pro discovery, enrichment, scoring a outreach podklady; vyrabi artefakty pro navazny lead import.

Target Boundary

Cilovy stav pro vymenitelnost webove aplikace je:

  • reply-pilot-app je pouze browser-facing web/BFF vrstva;
  • reply-pilot-app vola aplikacni stav a business operace pres reply-pilot-be HTTP/JSON API;
  • reply-pilot-app nema primy pristup do Reply Pilot DB;
  • reply-pilot-app nema primy pristup ke Gmail, OpenAI, Jira ani CME/CmD;
  • reply-pilot-be vlastni DB pristup, business workflow, integrace a stabilni JSON kontrakty pro soucasnou Flask appku i budouci preimplementaci UI;
  • Gmail boundary je striktne Google Gmail API/mailbox -> reply-pilot-gmail -> reply-pilot-be; backend nesmi drzet Gmail OAuth/Pub/Sub material ani cist/zapisovat Gmail mailbox cache soubory v gmail_service modu;
  • reply-pilot-worker vola backend job endpointy, neimplementuje job business logiku;
  • reply-pilot-jira-reports cte Jira Cloud REST API a zapisuje vlastni reporting artefakty; pro volitelny emailovy graf vola stabilni reply-pilot-gmail weekly-count HTTP endpoint, necte emailova runtime data pres bind mount;
  • search pro appku jde pres backend: reply-pilot-app -> reply-pilot-be -> reply-pilot-search.

Prime DB, Gmail, OpenAI a dalsi integracni zavislosti v reply-pilot-app nejsou povolene. Novy app kod je nema zavest; business a integracni operace patri za backend API.

Allowed Runtime Calls

Povolene smery runtime volani v aktualnim prechodnem stavu jsou:

  • reply-pilot-app -> reply-pilot-be pres HTTP/JSON;
  • reply-pilot-worker -> reply-pilot-be pres HTTP/JSON;
  • reply-pilot-worker -> reply-pilot-db-backup pres autentizovane HTTP/JSON;
  • reply-pilot-be -> reply-pilot-gmail pres HTTP/JSON;
  • reply-pilot-be -> reply-pilot-search pres HTTP/JSON;
  • reply-pilot-be -> reply-pilot-db pres PostgreSQL;
  • reply-pilot-be -> Atlassian, OpenAI a CME/CmD integrace podle backend dokumentace; Gmail/Google mailbox integrace jde jen pres reply-pilot-gmail;
  • reply-pilot-gmail -> Google Gmail API, Google OAuth token endpoint a Google Pub/Sub pres HTTPS/API klienty;
  • reply-pilot-search -> reply-pilot-db pres PostgreSQL;
  • reply-pilot-db-backup -> reply-pilot-db pres PostgreSQL readonly login;
  • reply-pilot-wholesale-scout -> CME/CmD DB, Reply Pilot DB a AI provideri jako batch/offline workflow;
  • reply-pilot-jira-reports -> Jira Cloud pres HTTPS REST/JSON jako samostatny reporting/offline workflow;
  • reply-pilot-jira-reports -> reply-pilot-gmail pres HTTP/JSON pouze pro volitelny GET /api/reports/email-weekly-counts graf;
  • reply-pilot-docs nema aplikacni runtime zavislosti na ostatnich modulech.

Novy smer volani mezi moduly musi mit explicitni dokumentacni duvod a stabilni HTTP/DB kontrakt. Sdileny bind mount mezi moduly neni rozhrani pro aplikacni stav, pokud k tomu neni vyslovne zdokumentovana vyjimka.

Code Boundaries

  • Produkcni Python kod jednoho reply_pilot_* balicku nesmi importovat jiny reply_pilot_* balicek.
  • Testy a modulove Python scripts se mohou vyhodnocovat oddelene, ale jejich cross-module importy musi byt videt v architecture reportu.
  • Business logika patri do vlastniciho modulu. Jiny modul ji ma volat pres stabilni HTTP/DB kontrakt, ne primym Python importem.
  • Konfigurace, logging a klienti externich sluzeb zustavaji modulove, dokud nevznikne jasny opakovany infrastrukturni kontrakt.
  • Pripadny budouci common balicek smi obsahovat jen stabilni infrastrukturu jako logging helper, env parsing nebo obecne health helpers; nema obsahovat email, Jira, Gmail, AI, lead import ani party/activity business pravidla.

Guardrails

Lokalni check:

script/check-architecture.sh

Check vygeneruje docasny architecture report ve strict rezimu, overi nulove produkcni cross-module importy, hlida ze BE neobsahuje Gmail OAuth/Pub/Sub material ani Google Gmail klient dependency, a porovna report s verzovanym baseline reportem. Kdyz se baseline lisi, nejdriv report zregeneruj:

python3 script/architecture-report.py --output reports/architecture-report.md