# mdj441/talmud-scripts architecture

> Architecture diagram of the GitHub repository mdj441/talmud-scripts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mdj441/talmud-scripts
- Repository: https://github.com/mdj441/talmud-scripts

## Overview

1. **מהות הריפוזיטורי**
   זהו מאגר של **4 סקריפטי Tampermonkey עצמאיים** עבור מערכת **תלמוד (talmud.edu.gov.il)**. אין כאן אפליקציה שרצה בשרת ואין שכבת backend; כל האוטומציה מתבצעת **מקומית בדפדפן** על גבי האתר הקיים.

2. **יחידת הפריסה הבסיסית**
   כל קובץ `.user.js` הוא **מוצר נפרד**:
   - קליטת תלמידים
   - עזיבת תלמידים
   - טיפול בהודעות
   - דיווח חודשי  
   כל אחד נטען דרך Tampermonkey, מוזרק לעמודי המערכת המתאימים, ומציג ממשק קטן משלו בתוך הדף.

3. **הגבול המרכזי של המערכת**
   הגבול הארכיטקטוני הוא בין:
   - **המשתמש + הדפדפן + Tampermonkey**  
   לבין
   - **אתר תלמוד**  
   הסקריפטים לא שומרים מידע חיצונית, לא פונים לשירותים צד שלישי, ולא דורשים שרת משל עצמם.

4. **דפוס פעולה משותף לכל הסקריפטים**
   כל הסקריפטים פועלים באותו דפוס:
   - זיהוי עמוד היעד באתר תלמוד
   - הזרקת פאנל UI קטן לתוך העמוד
   - קבלת קלט מהמשתמש, לרוב בהדבקה של רשימות טקסט
   - ביצוע פעולות סדרתיות על רשומות בממשק של תלמוד
   - הפקת פלט מסכם, לרוב CSV או דוח טקסטואלי

5. **קליטת תלמידים**
   הסקריפט הזה הוא תהליך ETL מקומי: הוא מקבל רשימת תלמידים בפורמט שורות, מפרש שדות כמו **סניף, סוג לימוד, תעודת זהות/דרכון**, ומבצע קליטה ברצף.  
   יש כאן גם מסלול מיוחד ל**דרכונים זרים**, כולל תאריך לידה וארץ מוצא. בסיום הוא מפיק **CSV** לתיעוד התוצאות.

6. **עזיבת תלמידים**
   סקריפט זה דומה ל"קליטה" אבל עם זרימת עבודה הפוכה: הוא מקבל רשימת תלמידים לפי **סניף + ת.ז.**, מנווט בין הרשומות במערכת ומבצע **עזיבה**. גם כאן יש פאנל קלט וסיכום תוצאות בסיום.

7. **טיפול בהודעות**
   זהו הסקריפט בעל הזרימה המורכבת ביותר. הוא תומך בשני מצבים:
   - **מצב גורף**: עובר על כל ההודעות הממתינות/נשלחו ומטפל בהן אוטומטית
   - **מצב לפי טבלה**: סורק הודעות, מייצא לטבלה/Excel, מאפשר עריכה ידנית של פעולה לכל שורה, ואז מבצע את ההחלטות  
   כלומר יש כאן שילוב של **אוטומציה מלאה** ו**בקרה ידנית מבוססת טבלה**.

8. **דיווח חודשי**
   הסקריפט הרביעי מבצע **מעבר סניף-סניף** בעמוד המוסד, מדלג על סניפים שכבר דווחו או שאינם רלוונטיים, ושולח דיווח חודשי אוטומטי. זהו תהליך סדרתי עם מצב התקדמות וסיכום סיום.

9. **ממשק משתמש והפעלה**
   במקום UI חיצוני, כל סקריפט מוסיף **פאנל צף** לדף הרלוונטי:
   - קליטת תלמידים / עזיבה / דיווח: בעיקר פאנל בצד ימין או שמאל של העמוד
   - טיפול בהודעות: פאנל עם טאבים ופעולות כמו סריקה, טעינה, ביצוע והעתקת דוח  
   המשמעות היא שהממשק הוא חלק מהדף, אבל מנוהל על ידי הסקריפט.

10. **תלויות ותנאי הרצה**
    התלות היחידה שממש משנה לארכיטקטורה היא **Tampermonkey** בדפדפן. ב־Chrome/Edge נדרש גם:
    - Developer Mode
    - Allow user scripts  
    זה מגדיר שהרצת הסקריפטים תלויה בתשתית של הדפדפן ולא ביישום עצמאי.

11. **זרימת נתונים**
    נתוני הקלט מגיעים כמעט תמיד מ**הדבקה ידנית** של טקסט:
    - רשימות תלמידים
    - טבלאות הודעות מיוצאות
    - שדות תאריך/סיבה  
    הפלט הוא פעולה בתוך מערכת תלמוד, ובחלק מהמקרים גם **CSV/Excel/דוח מסכם** להורדה או העתקה.

12. **השלכה לדיאגרמת ארכיטקטורה**
    בדיאגרמה נכון להציג:
    - משתמש
    - דפדפן עם Tampermonkey
    - ארבעה userscripts נפרדים
    - אתר תלמוד כיעד יחיד
    - זרימות קלט/פלט מקומיות בלבד  
    אין צורך לצייר שירותים חיצוניים, API ייעודי, מסד נתונים או שכבת אינטגרציה נפרדת.

13. **מסקנת מבנה**
    זהו ריפו של **כלי אוטומציה מבוססי-לקוח** עם ארבעה מסלולי עבודה מופרדים, כולם מכוונים לאותו דומיין, כולם תלויי UI של האתר, וכולם מבצעים אוטומציה חוזרת על תהליכים אדמיניסטרטיביים בתוך מערכת תלמוד.

Main entry points: [`תלמוד - קליטת תלמידים.user.js`](https://github.com/mdj441/talmud-scripts/blob/HEAD/%D7%AA%D7%9C%D7%9E%D7%95%D7%93%20-%20%D7%A7%D7%9C%D7%99%D7%98%D7%AA%20%D7%AA%D7%9C%D7%9E%D7%99%D7%93%D7%99%D7%9D.user.js) (Student intake), [`תלמוד - עזיבת תלמידים.user.js`](https://github.com/mdj441/talmud-scripts/blob/HEAD/%D7%AA%D7%9C%D7%9E%D7%95%D7%93%20-%20%D7%A2%D7%96%D7%99%D7%91%D7%AA%20%D7%AA%D7%9C%D7%9E%D7%99%D7%93%D7%99%D7%9D.user.js) (Student exit), [`תלמוד - טיפול בהודעות.user.js`](https://github.com/mdj441/talmud-scripts/blob/HEAD/%D7%AA%D7%9C%D7%9E%D7%95%D7%93%20-%20%D7%98%D7%99%D7%A4%D7%95%D7%9C%20%D7%91%D7%94%D7%95%D7%93%D7%A2%D7%95%D7%AA.user.js) (Messages), [`תלמוד - דיווח חודשי אוטומטי.user.js`](https://github.com/mdj441/talmud-scripts/blob/HEAD/%D7%AA%D7%9C%D7%9E%D7%95%D7%93%20-%20%D7%93%D7%99%D7%95%D7%95%D7%97%20%D7%97%D7%95%D7%93%D7%A9%D7%99%20%D7%90%D7%95%D7%98%D7%95%D7%9E%D7%98%D7%99.user.js) (Monthly report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local runtime"]
  node_user(("User<br/>operator"))
  node_browser["Browser<br/>client runtime"]
  node_tampermonkey["Tampermonkey<br/>userscript manager"]
  node_readme["README<br/>docs<br/>[README.md]"]
end

subgraph group_scripts["Userscripts"]
  node_entry["Student intake<br/>userscript"]
  node_exit["Student exit<br/>userscript"]
  node_messages["Messages<br/>userscript"]
  node_monthly["Monthly report<br/>userscript"]
  node_detect(("Page detect<br/>shared pattern"))
  node_inject["UI panel<br/>shared pattern"]
  node_paste["Paste input<br/>shared pattern"]
  node_iterate(("Batch run<br/>shared pattern"))
  node_summarize["Summary output<br/>shared pattern"]
end

subgraph group_talmud["Talmud site"]
  node_talmud[("Talmud<br/>target web app")]
  node_student_pages["Student pages<br/>app area"]
  node_message_pages["Message pages<br/>app area"]
  node_branch_pages["Branch pages<br/>app area"]
end

node_user -->|"uses"| node_browser
node_browser -->|"hosts"| node_tampermonkey
node_tampermonkey -->|"loads"| node_entry
node_tampermonkey -->|"loads"| node_exit
node_tampermonkey -->|"loads"| node_messages
node_tampermonkey -->|"loads"| node_monthly
node_entry -->|"starts with"| node_detect
node_exit -->|"starts with"| node_detect
node_messages -->|"starts with"| node_detect
node_monthly -->|"starts with"| node_detect
node_detect -->|"enables"| node_inject
node_inject -->|"collects"| node_paste
node_paste -->|"feeds"| node_iterate
node_iterate -->|"acts on"| node_talmud
node_entry -->|"uses"| node_student_pages
node_exit -->|"uses"| node_student_pages
node_messages -->|"uses"| node_message_pages
node_monthly -->|"uses"| node_branch_pages
node_entry -->|"exports"| node_summarize
node_exit -->|"exports"| node_summarize
node_messages -->|"exports"| node_summarize
node_monthly -->|"exports"| node_summarize
node_readme -.->|"documents"| node_entry
node_readme -.->|"documents"| node_exit
node_readme -.->|"documents"| node_messages
node_readme -.->|"documents"| node_monthly

click node_readme "https://github.com/mdj441/talmud-scripts/blob/main/README.md"
click node_entry "https://github.com/mdj441/talmud-scripts/blob/main/תלמוד - קליטת תלמידים.user.js"
click node_exit "https://github.com/mdj441/talmud-scripts/blob/main/תלמוד - עזיבת תלמידים.user.js"
click node_messages "https://github.com/mdj441/talmud-scripts/blob/main/תלמוד - טיפול בהודעות.user.js"
click node_monthly "https://github.com/mdj441/talmud-scripts/blob/main/תלמוד - דיווח חודשי אוטומטי.user.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_user,node_browser,node_tampermonkey,node_readme toneBlue
class node_entry,node_exit,node_messages,node_monthly,node_detect,node_inject,node_paste,node_iterate,node_summarize toneAmber
class node_talmud,node_student_pages,node_message_pages,node_branch_pages toneMint
```

## Components

### Local runtime

User-side browser execution and script injection

- **User**: operator · Manual operator who pastes inputs and reviews results
- **Browser**: client runtime · Chrome/Edge or similar browser hosting the scripts
- **Tampermonkey**: userscript manager · Browser extension that injects and runs the scripts
- [README](https://github.com/mdj441/talmud-scripts/blob/main/README.md): docs · Repository documentation and usage notes · `README.md`

### Userscripts

Four independent Tampermonkey automations

- [Student intake](https://github.com/mdj441/talmud-scripts/blob/HEAD/%D7%AA%D7%9C%D7%9E%D7%95%D7%93%20-%20%D7%A7%D7%9C%D7%99%D7%98%D7%AA%20%D7%AA%D7%9C%D7%9E%D7%99%D7%93%D7%99%D7%9D.user.js): userscript · Local ETL flow for registering students · `תלמוד - קליטת תלמידים.user.js`
- [Student exit](https://github.com/mdj441/talmud-scripts/blob/HEAD/%D7%AA%D7%9C%D7%9E%D7%95%D7%93%20-%20%D7%A2%D7%96%D7%99%D7%91%D7%AA%20%D7%AA%D7%9C%D7%9E%D7%99%D7%93%D7%99%D7%9D.user.js): userscript · Workflow for marking students as leaving · `תלמוד - עזיבת תלמידים.user.js`
- [Messages](https://github.com/mdj441/talmud-scripts/blob/HEAD/%D7%AA%D7%9C%D7%9E%D7%95%D7%93%20-%20%D7%98%D7%99%D7%A4%D7%95%D7%9C%20%D7%91%D7%94%D7%95%D7%93%D7%A2%D7%95%D7%AA.user.js): userscript · Automation for handling incoming and outgoing messages · `תלמוד - טיפול בהודעות.user.js`
- [Monthly report](https://github.com/mdj441/talmud-scripts/blob/HEAD/%D7%AA%D7%9C%D7%9E%D7%95%D7%93%20-%20%D7%93%D7%99%D7%95%D7%95%D7%97%20%D7%97%D7%95%D7%93%D7%A9%D7%99%20%D7%90%D7%95%D7%98%D7%95%D7%9E%D7%98%D7%99.user.js): userscript · Branch-by-branch monthly reporting automation · `תלמוד - דיווח חודשי אוטומטי.user.js`
- **Page detect**: shared pattern · Identifies the target Talmud page before acting
- **UI panel**: shared pattern · Injects a small in-page control panel
- **Paste input**: shared pattern · Accepts pasted lists, tables, and form fields
- **Batch run**: shared pattern · Processes records sequentially in the site UI
- **Summary output**: shared pattern · Produces CSV, table, or text summary for the user

### Talmud site

Target web application and its working pages

- **Talmud**: target web app · Existing administrative web system at talmud.edu.gov.il
- **Student pages**: app area · Pages used for intake and exit operations
- **Message pages**: app area · Inbox/outbox and table-driven message workflows
- **Branch pages**: app area · Institution and branch pages used for monthly reporting

## Connections

- User → Browser: uses · Operates the browser and pastes data into in-page panels
- Browser → Tampermonkey: hosts · Browser provides the extension runtime
- Tampermonkey → Student intake: loads · Injects the student intake userscript
- Tampermonkey → Student exit: loads · Injects the student exit userscript
- Tampermonkey → Messages: loads · Injects the message handling userscript
- Tampermonkey → Monthly report: loads · Injects the monthly reporting userscript
- Student intake → Page detect: starts with · Checks whether the current page matches the intake flow
- Student exit → Page detect: starts with · Checks whether the current page matches the exit flow
- Messages → Page detect: starts with · Checks whether the current page matches the message flow
- Monthly report → Page detect: starts with · Checks whether the current page matches the branch/report flow
- Page detect → UI panel: enables · Creates the floating control panel on matching pages
- UI panel → Paste input: collects · Receives pasted lists, tables, and command input
- Paste input → Batch run: feeds · Parsed input drives sequential record processing
- Batch run → Talmud: acts on · Executes actions inside the Talmud application
- Student intake → Student pages: uses · Runs intake actions on student pages
- Student exit → Student pages: uses · Runs exit actions on student pages
- Messages → Message pages: uses · Scans, edits, and executes message operations
- Monthly report → Branch pages: uses · Walks branch pages to send monthly reports
- Student intake → Summary output: exports · Outputs CSV or completion results
- Student exit → Summary output: exports · Outputs completion summary
- Messages → Summary output: exports · Outputs table, Excel, or text report
- Monthly report → Summary output: exports · Outputs progress and final summary
- README → Student intake: documents · Repository documentation covers the scripts
- README → Student exit: documents · Repository documentation covers the scripts
- README → Messages: documents · Repository documentation covers the scripts
- README → Monthly report: documents · Repository documentation covers the scripts