🚀 The Performance Bible: CodeKeeper Optimization Guide
======================================================

המדריך הזה נכתב לאחר ה-Refactor הגדול של דצמבר 2025, שבו הורדנו את ה-p95 של המערכת מ-1.8 שניות ל-200ms. אלו העקרונות שחייבים להישמר:

## 0. חוק הברזל: Cache First (מנע את הגישה ל-DB)

לפני אופטימיזציה של שאילתה – בדוק אם היא הכרחית. המערכת משתמשת ב-**Redis Cache** כשכבת הגנה ראשונה.

* **Heavy Lists:** TTL ארוך (3-5 דקות).
* **Metadata:** TTL קצר (15-60 שניות).
* **Validation:** השתמש ב-`/admin/cache-inspector` כדי לוודא שמפתחות נוצרים עם Hash קבוע ולא כתובות זיכרון.

**הכלל:** כל קריאת קריאה (Read) כבדה חייבת לעבור דרך `CacheManager`.

## 1. חוק ה-Projection (אל תמשוך מה שאתה לא מציג)

לעולם אל תמשוך את השדות `code` או `content` בשאילתות רשימה.

הבעיה: שליפת 50 קבצים עם קוד מלא יוצרת Payload של מגה-בייטים, חונקת את ה-RAM של השרת ומאיטה את ה-Serialization.

הפתרון: שימוש קבוע ב-`LIST_EXCLUDE_HEAVY_PROJECTION`.

איך זה עובד: ה-Repository מחזיר רק מטא-דאטה. התוכן המלא נשלף רק ב-Explicit Fetch (כשמשתמש פותח קובץ ספציפי).

## 2. חישובים ב-DB (Smart Metadata)

במקום למשוך קוד ולספור שורות בפייתון, אנחנו מחשבים ושומרים:

- `file_size`: גודל הקובץ בבייטים.
- `lines_count`: מספר השורות.

הכלל: אם אפשר לחשב את זה ב-MongoDB בזמן השמירה – עשה זאת שם. זה הופך את הרשימות ל"נוצה".

## 3. אינדוקס מורכב (Compound Indexes)

אל תסמוך על אינדקסים פשוטים. השאילתות שלנו מורכבות ולכן האינדקסים חייבים להיות תואמים:

- `{ "user_id": 1, "is_deleted": 1, "created_at": -1 }` – לשליפה מהירה וממוינת של קבצי משתמש.
- `{ "user_id": 1, "is_favorite": 1 }` – לדף המועדפים.

זכור: שאילתה בלי אינדקס (COLLSCAN) היא פצצת זמן מתקתקת.

## 4. אופטימיזציית API וחיפוש (The Snippet Pattern)

בחיפוש גלובלי, במקום להחזיר את כל הקובץ שבו נמצאה המילה:

- משתמשים ב-`$regexFind` בתוך מונגו כדי לחתוך Snippet קטן סביב ההתאמה.
- מחזירים ל-UI רק את ה-Preview.

זה חוסך 99% מהתעבורה בחיפושים כבדים.

## 5. הזרקת נתונים אסינכרונית (Lazy Loading)

בדפים כבדים (כמו Observability):

- **Backend**: ה-Route מחזיר HTML ריק תוך פחות מ-200ms.
- **Frontend**: שימוש ב-Skeleton Loaders בזמן שנתונים נמשכים ב-API נפרד ברקע.
- **Concurrency**: שימוש ב-`asyncio.to_thread` לקריאות DB כבדות כדי לא לחסום את ה-Event Loop.

## 6. הגדרות סביבה (The Production Sweet Spot)

- `LOG_LEVEL=INFO`: צמצום כתיבת לוגים מיותרת.
- `MONGODB_MIN_POOL_SIZE=10`: שמירת חיבורים "חמים" למניעת SSL Handshake Timeouts.
- `AIOHTTP_LIMIT_PER_HOST=25`: פתיחת צוואר הבקבוק מול GitHub/APIs חיצוניים.