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 nema missing declarations ani podezrele unused runtime deps;
  • nejvetsi complexity hotspoty jsou hlavne v reply-pilot-app/reply_pilot_app/views.py;
  • opakovane soubory jako config.py, logging_utils.py, email_store.py, gmail_store.py, openai_client.py a views.py jsou kandidati na vedome sjednoceni nebo zdokumentovane ponechani.

Module Responsibilities

  • reply-pilot-app: uzivatelske UI a BFF vrstva; vola backend a search, drzi webove formulare, navigaci, simple-auth replay protection 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 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-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-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.

Allowed Runtime Calls

Povolene smery runtime volani jsou:

  • reply-pilot-app -> reply-pilot-be pres HTTP/JSON;
  • reply-pilot-app -> reply-pilot-search pres HTTP/JSON;
  • reply-pilot-app -> reply-pilot-db jen pro simple-auth nonce a typed AI prompt storage, dokud tato oblast nebude plne presunuta za backend API;
  • reply-pilot-worker -> reply-pilot-be pres HTTP/JSON;
  • reply-pilot-be -> reply-pilot-gmail pres HTTP/JSON;
  • reply-pilot-be -> reply-pilot-db pres PostgreSQL;
  • reply-pilot-be -> Google, Atlassian, OpenAI a CME/CmD integrace podle backend dokumentace;
  • reply-pilot-search -> reply-pilot-db pres PostgreSQL;
  • reply-pilot-wholesale-scout -> CME/CmD DB, Reply Pilot DB a AI provideri jako batch/offline workflow;
  • 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 a porovna ho s verzovanym baseline reportem. Kdyz se baseline lisi, nejdriv report zregeneruj:

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