Repository navigation
Architecture
Your Name edited this page Oct 27, 2026
·
1 revision
מסמך זה מתאר את מבנה המערכת, השירותים, המודולים וההחלטות הטכניות המרכזיות.
דפדפן (HTML/CSS/JS, MapLibre GL)
│ http://localhost:8080
▼
┌──────────────── api (Python/Starlette) ─────────────────┐
│ חיפוש עברי · נקודות עניין · גיאוקודינג · אריחי POI │
│ מפת בסיס (MBTiles) · גופנים · דוחות · מדדים │
└───────────┬─────────────────────────────┬───────────────┘
│ SQLite: R*Tree + FTS5 │ HTTP / בתוך התהליך
▼ ▼
maps.db ניווט: OSRM ×3 (Docker)
(נבנה ע"י etl) או מנוע פנימי (בלי Docker)
▲ רכב · הליכה · אופניים
etl: OpenStreetMap + data.gov.il + Wikidata/ויקיפדיה
tiles: Planetiler ← OpenStreetMap → israel.mbtiles
| שירות | תפקיד | פורט |
|---|---|---|
api |
שרת האתר וה-API (Python/Starlette, uvicorn) | 8080 |
routing |
שלושה שרתי OSRM – מכין גרפי דרכים בהפעלה ראשונה (Docker בלבד) | פנימי 5001–5003 |
etl (משימה) |
איסוף, ניקוי, איחוד והעשרת נתונים → maps.db + דוח איכות |
– |
tiles (משימה) |
בניית מפת הבסיס הווקטורית (Planetiler) → israel.mbtiles
|
– |
hmaps/core עברית: נרמול, תחיליות, קיצורים, תיקון שגיאות, קטגוריות, שעות פתיחה, גאומטריה, סכמה
hmaps/etl צינור הנתונים: osmium → בנייה → העשרה → אינדקס חיפוש → דוח איכות
hmaps/api API, מנוע חיפוש, אריחים וקטוריים, ניווט והוראות בעברית
hmaps/route מנוע ניווט פנימי (גרף דרכים + A*) – לשימוש בלי Docker
web/ ממשק המשתמש (ללא שלב build): js/, css/, sw.js, manifest
docker/ Dockerfile ושירות הניווט
src-tauri/ אפליקציית שולחן העבודה (Tauri 2, Rust): חלון, הפעלת שרת ועצירתו
installer/ PyInstaller + Inno Setup (מתקין Windows)
tests/ יחידה, אינטגרציה, דפדפן (Playwright), ביצועים
docs/ מסמכי הפרויקט: ADR, מימוש, תפעול, API
site/ אתר המוצר (HTML ו-CSS סטטיים, ללא build)
tools/ כלי עזר: terrain, media, release, basemap, sample_data ועוד
SQLite עם שני מנועים:
- R*Tree – שאילתות מרחביות (מה יש בסביבה, גאוקודינג הפוך, אריחי POI)
-
FTS5 – חיפוש טקסט מלא בעברית (משולב עם מנתח עברי ייעודי ב-
hmaps/core)
למה לא PostGIS + Elasticsearch? הנתונים הם קריאה בלבד ובהיקף בינוני. SQLite מהיר יותר, לא דורש שרתים נפרדים ואין מה לתחזק. (ADR 0002)
- נרמול: הסרת ניקוד, אותיות סופיות, גרש וגרשיים, מקף, וכתיב מלא/חסר (קריית ↔ קרית, תקווה ↔ תקוה)
- אותיות השימוש (ב/ו/ל/ה/ו/ש/מ): "בתל אביב", "לירושלים", "הכותל" – כולם מוצאים את הרצוי
- קיצורים: ת"א, ב"ש, פ"ת, ביה"ח, ביכ"נ, קופ"ח, שד', רח'
- תיקון שגיאות: Damerau-Levenshtein עם עלות מופחתת לאותיות מתחלפות (ט/ת, כ/ק, ס/ש, א/ע, ח/כ)
-
פריסת מקלדת שגויה:
sh,bdu;→ דיזנגוף - הבנת כוונה: קטגוריה + מיקום, "ליד", "פתוח עכשיו", "כשר", קואורדינטות, כתובות בשני הסדרים
בלי Docker: מנוע ניווט פנימי (hmaps/route) – גרף דרכים + A*. תומך ברכב, הליכה ואופניים. שבילים מסומנים זולים ב-10% בהליכה ובאופניים.
עם Docker: שלושה שרתי OSRM (רכב, הליכה, אופניים). מכינים גרפים בהפעלה ראשונה. הניווט לא זמין כ-15 דקות עד שהגרפים מוכנים.
| שכבה | טכנולוגיה | הערה |
|---|---|---|
| שרת | Python 3.13, Starlette, uvicorn | 2 workers |
| לקוח | HTML, CSS, ES Modules (ללא build) | ללא React/Vue |
| מפה | MapLibre GL JS + תוסף RTL | קוד פתוח, ללא מפתח API |
| נתונים | SQLite (R*Tree + FTS5) | אין PostGIS/Redis |
| מפת בסיס | Planetiler → MBTiles | אריחים וקטוריים |
| ניווט | OSRM (Docker) / מנוע פנימי A* | |
| אפליקציית חלון | Tauri 2, Rust | WebView2 |
| מתקין | PyInstaller + Inno Setup | |
| CI/CD | GitHub Actions |
למה ללא framework בלקוח? ממשק ללא build שומר על פשטות: אין
node_modules, אין תלויות, קל לתחזוקה גם בלי צוות פיתוח קבוע. (ADR 0001)
על 120,000 POI ו-12,000 רחובות, תהליך יחיד:
| פעולה | p50 | p95 |
|---|---|---|
| השלמה אוטומטית | 12ms | 29ms |
| חיפוש מלא | 31ms | 88ms |
| כרטיס POI | < 1ms | < 1ms |
| אריח POI | 12ms | 42ms |
| גאוקודינג הפוך | < 1ms | < 1ms |
| ETL (בנייה) | ~23 שניות | – |
-
בריאות:
GET http://localhost:8080/api/health– 200 פירושו שיש נתונים -
מטא-נתונים:
GET /api/meta– תאריך הנתונים, מפת בסיס מלאה/פשוטה, זמינות ניווט -
מדדי Prometheus:
GET /metrics– בקשות לפי נתיב, היסטוגרמת זמני תגובה -
דוח איכות נתונים:
GET /reports
- השרת רץ כמשתמש לא-מורשה (uid 10001)
- הגבלת קצב לכל לקוח (
HMAPS_RATE_PER_SEC,HMAPS_RATE_BURST) - CSP מחמיר (ללא inline scripts),
nosniff,Referrer-Policy,Permissions-Policy - ולידציה לכל פרמטר, הגבלת אורך שאילתות, הגנה מ-path traversal
- הלוגים אינם כוללים מחרוזות חיפוש
ההחלטות הטכניות המלאות עם נימוקיהן נמצאות בתיקיית docs/adr/:
| מסמך | נושא |
|---|---|
| ADR 0001 | טכנולוגיות: Python/Starlette + ES Modules ללא build |
| ADR 0002 | אחסון וחיפוש: SQLite במקום PostGIS + Elasticsearch |
| ADR 0003 | תצלומי אוויר: govmap + Sentinel-2 |
| ADR 0005 | צינור הנתונים: osmium + Python |
| ADR 0006 | מצב native: Python נייד, ניווט פנימי, Java נייד |
| ADR 0007 | תחבורה ציבורית: GTFS |
| ADR 0008 | גבהים: Copernicus DEM GLO-30 |
| ADR 0009 | אפליקציית שולחן העבודה: Tauri 2 |