ARCHITECTURE.md

ARCHITECTURE — מבנה היעד

המבנה שאליו ה‑monorepo מתכנס. core/ (+config/calibration/pipeline), verticals/logistics/ ו‑harness/ כבר במבנה היעד; infra/ ו‑delivery/ עדיין ב‑legacy/ ומהגרות בשלבים הבאים (MIGRATION_MAP.md).

עקרון מנחה

תלות זורמת בכיוון אחד בלבד:

core  ←  verticals  ←  infra  ←  delivery
 ▲                                  │
 └──────────────────────────────────┘
        delivery ו-infra משתמשים ב-core; core לא יודע על אף אחד מהם

core/ אסור שיֵדע על שום שכבה אחרת. אם משהו ב‑core/ צריך לייבא מ‑infra/ או מ‑verticals/ — הוא לא שייך ל‑core/.

השכבות

core/ — הליבה האנליטית ✅ הוגר ב-Stage 0

מודל הנתונים הקנוני והמתמטיקה הדטרמיניסטית. stdlib בלבד, ללא I/O, ללא state.

• events.py — CanonicalEvent
• state.py — EntityState
• ontology.py — Entity, ENTITY_TYPES
• signals.py — Δ, ψ, ξ, γ, κ, Ω (signal math)
• drift.py — DriftIssue, drift_score, severity_from_score
• decisions.py — DecisionItem, recommendation_for_issue

זו השכבה היחידה שחייבת להיות מכוסה ב‑100% בבדיקות correctness אמיתיות. היום: 36 בדיקות, כולל בדיקת lead‑time אינטגרטיבית (tests/test_core_integration.py).

verticals/ — adapters לאנכים ✅ Stage 1 (logistics)

adapter עושה עבודה אחת: ממפה סכמה גולמית של לקוח ל‑canonical events/metrics ש‑core/ מבין. שום לוגיקה אנליטית ב‑adapter — הוא תרגום בלבד. logistics/ הוא ה‑adapter הראשון (config.yaml + adapter.py). team_drift_detector.py הוגר לכאן — detector, לא core, superseded ע"י הצינור הגנרי.

harness/ — harness אימות ✅ Stage 2

מחולל תרחישים מתויגים ומודד את המנוע מול ground truth: precision, recall, detection delay, lead‑time. תלוי ב‑core/ בלבד. גם שער CI וגם הדמו של המוצר (python -m harness).

infra/ — שכבת תשתית (Stage 3, בפרוסות)

3a ✅ infra/storage/ — אחסון: tenants, calibrations, runs (SQLite היום, ה‑Database ב‑db.py הוא ה‑seam ל‑Postgres). infra/service.py — OrgStateService, שכבת התזמור שמחברת core ל‑storage. 3b ✅ infra/api/ — shell דק של HTTP: handlers.py (לוגיקה טהורה, ללא fastapi), errors.py (מודל שגיאות), app.py (חיווט FastAPI). השרשרת: FastAPI app → handlers → OrgStateService → core+storage. 3c ✅ infra/ingestion/ — connectors.py (Connector ABC, InMemoryConnector, CSVFolderConnector, build_connector) + scheduler.py (Schedule נשמר, is_due/due_schedules טהורים, IngestionService, run_scheduler loop דק). connector = "מאיפה הדאטה", ה‑adapter עדיין בעל מיפוי הסכמה. 3d ✅ infra/deployment/ — settings.py (RuntimeSettings מ‑env), observability.py (logging מובנה JSON), scheduler_service.py (entry point של ה‑worker). Dockerfile + docker-compose.yml ברמת ה‑repo — api ו‑scheduler כשני processes על image אחד שחולקים DB אחד דרך ORGSTATE_DB_PATH. נותר: auth/RBAC (auth_*.py) ו‑backend Postgres — פרוסות נפרדות דרך ה‑seam.

delivery/ — פלט מול לקוח (Stage 4)

דוח ניהולי, תור החלטות, evidence views, דשבורדים, branded report builder, PDF export. היום ב‑legacy/: customer_report_builder.py, executive_audit_report_builder.py, branded_report_builder_v31.py, *_dashboard*.py, evidence_view_builder.py, pdf_exporter_v28.py.

נתיב הנתונים (כשהמבנה יושלם)

מקור דאטה של לקוח
  → verticals/<vertical>  (מיפוי סכמה → CanonicalEvent)
  → core  (EntityState → signals Δψξγκ → Ω → drift_score → DecisionItem)
  → infra  (persist, schedule, serve via API)
  → delivery  (executive report, decision queue, evidence view)

החלטות מבנה מודעות

• infra/ ולא platform/ — platform מצל על מודול stdlib בשם זה.
• core/ ללא תלויות — כדי שהבדיקות יהיו מהירות, ושאי אפשר יהיה "להבריח" I/O או state לתוך הליבה.
• legacy/ נשאר רץ — לא משברים כלום. כל שלב מהגר רכיב, מחליף את ה‑import, ומוחק את המקור מ‑legacy/ רק כשהבדיקות ירוקות.