ארכיטקטורה

סקירה כללית

המערכת מורכבת מבוט Telegram, שכבת שירותים (services), שכבת נתונים (MongoDB) ואפליקציית Web. הזרימה העיקרית: Handlers → Services → Database.

תרשים רכיבים (תמציתי)

        graph TD
  A[Telegram Bot] --> B[Handlers]
  B --> C[Services]
  C --> D[(MongoDB)]
  C --> E[GitHub API]
  C --> F[Google Drive API]
  A --> G[WebApp]
  G --> D
    

תרשים ארכיטקטורה מפורט

התרשים הבא מציג את הארכיטקטורה המלאה של המערכת, כולל כל השכבות והקשרים ביניהן:

        graph TB
    subgraph "Telegram Interface"
        U[User] --> TB[Telegram Bot]
    end

    subgraph "Command Processing Layer"
        TB --> CR[Command Router]
        CR --> PH[Permission Handler]
        PH --> CH[Command Handlers]
    end

    subgraph "Core Services"
        CH --> MC[Metrics Collector]
        CH --> GH[GitHub API Handler]
        CH --> CD[Code Analyzer]
        MC --> MS[Metrics Storage]
        MC --> MA[Metrics Analyzer]
    end

    subgraph "Storage Layer"
        MS --> PG[(PostgreSQL)]
        MS --> RD[(Redis Cache)]
        CD --> FS[File System]
    end

    subgraph "Monitoring & Alerts"
        MA --> AM[Alert Manager]
        AM --> NS[Notification Service]
        MA --> PE[Prometheus Exporter]
        PE --> GD[Grafana Dashboards]
    end

    NS -->|Alert| TB
    

הסבר השכבות:

• Telegram Interface: ממשק המשתמש דרך הבוט

• Command Processing Layer: ניתוב פקודות, בדיקת הרשאות וטיפול בפקודות

• Core Services: שירותי הליבה - איסוף מטריקות, GitHub API, ניתוח קוד

• Storage Layer: שכבת האחסון - PostgreSQL, Redis Cache, File System

• Monitoring & Alerts: ניטור והתראות - Prometheus, Grafana, Alert Manager

ראה גם

• תיקיית handlers: Handlers

• תיקיית services: Services

• תיקיית database: Database

מבנה תיקיות

::

handlers/        → Telegram handlers
services/        → Business logic
database/        → MongoDB models & manager
webapp/          → Flask web app
tests/           → Unit/Integration tests
docs/            → Sphinx documentation

מקורות נוספים

• Clean Architecture ב-src

זרימות מרכזיות

שמירת קובץ (תמצית):

        sequenceDiagram
  participant U as User
  participant B as Bot
  participant H as Handler
  participant S as Service
  participant DB as MongoDB
  U->>B: /save file.py
  B->>H: save_command()
  H->>U: "שלח את הקוד"
  U->>H: code content
  H->>S: process_code(code)
  S->>DB: save_snippet()
  DB-->>S: {id}
  S-->>H: success
  H-->>U: "נשמר בהצלחה"
    

קישורים

• המיני Web App (סקירה)

• זרימת הטיפול במסמכים (Document Flow)

• Database

• API Reference

• הנחיות מלאות לסוכני AI

תשתית HTTP – סשן aiohttp משותף

• בכל הרכיבים הא-סינכרוניים (בוט/שירותים) נעשה שימוש ב‑aiohttp.ClientSession משותף דרך http_async.get_session().

• פרמטרים נשלטים דרך ENV: AIOHTTP_TIMEOUT_TOTAL, AIOHTTP_POOL_LIMIT, AIOHTTP_LIMIT_PER_HOST.

• כיבוי מתבצע אוטומטית ב‑atexit; ניתן לסגור ידנית עם await http_async.close_session() ב‑teardown.

• לולאת asyncio: בפרודקשן יש לולאה יחידה. בטסטים/ריסטארט חם, אם נוצרת לולאה חדשה ונתקלתם ב‑“attached to a different loop”, סגרו את הסשן ואז קבלו חדש.

• הנחיה: אל תפתחו ClientSession ישירות בקוד היישום; השתמשו רק ב‑http_async.get_session().

הפרדת אחריות – DocumentHandler

הטיפול במסמכים עבר למחלקה ייעודית: handlers/documents.py (DocumentHandler) המשמשת כ‑Facade למסלולי קבצים:

• GitHub: _handle_github_restore_zip_to_repo / _handle_github_create_repo_from_zip / העלאה ישירה

• ZIP: _handle_zip_import / _handle_zip_create (איסוף קבצים ל‑bundle)

• קבצים טקסטואליים: _handle_textual_file (נורמליזציה, זיהוי קידוד, שמירה)

תלויות מוזרקות לבנאי:

• notify_admins

• log_user_activity

• emit_event (Observability)

• errors_total (מונה שגיאות ל‑Prometheus)

• encodings_to_try (סט קידודים דינמי)

ראו גם: זרימת הטיפול במסמכים (Document Flow) לפרטי זרימה, מצבי upload_mode ונקודות הרחבה.