ארכיטקטורה וטכנולוגיה
ספר הארכיטקטורה
טופולוגיה, גבולות שירות, מסעות, חוזי אירועים, החלטות ותפעול.
בעמוד הזה
תכנון, מקור אמת בקוד וראיות ביצוע; אינו אישור מוכנות להפעלה מסחרית.
תאריך: 2026-11-08. מקור: lib/systems/architecture.json.
מצבים: deployed = רכיב פרוס עם ראיה מוגדרת; foundation = בסיס בקוד; planned = תכנון; blocked = תלות פתוחה. אף אחד מהם אינו אישור פרודקשן מלא.
מפת הארכיטקטורה#
A01 · שלוש כניסות, תחומי אחריות נפרדים#
מצב: deployed. אחריות: Platform.
אתר החברה, מוצר הלקוחות ואזור ניהול החברה פרוסים בנפרד ב־Vercel.
- linknodesenergy.com: תוכן ציבורי ויצירת קשר. product.linknodesenergy.com: מרחבי לקוחות. admin.linknodesenergy.com: כניסה סגורה לצוות החברה.
- APP_SURFACE נקבע בצד השרת לכל פרויקט. שינוי Host או ניווט לכתובת אחרת אינו מקנה הרשאה.
- האתר ואזור הניהול חוסמים את נתיבי המוצר, ה־API וקובצי הספריות. אזור הניהול עדיין אינו מערכת תפעול.
מקורות: lib/surface.ts, proxy.ts, docs/linknodes-release.md.
A02 · ליבת מוצר מודולרית#
מצב: foundation. אחריות: Platform.
Next.js ו־TypeScript מרכזים את ממשקי הלקוחות ואת שכבת ה־API.
- המודולים: זהות ומרחבים, צי ונהגים, מדיניות, טעינה, כסף, אנליטיקה ושירות.
- PostgreSQL הוא מקור האמת לעובדות עסקיות. תורים מעבירים עבודה; אינם מקור יתרה או מצב כספי.
- שלושת הפרויקטים חולקים מקור קוד. הפריסה הנפרדת אינה מחליפה בדיקת הרשאה בכל פעולה.
מקורות: lib/platform/api.ts, lib/platform/domain.ts.
A03 · זהות לעומת חברות בארגון#
מצב: deployed. אחריות: Identity.
Clerk מאמת אדם; חברות פעילה ב־PostgreSQL קובעת מה מותר לו לעשות.
- JWT מאומת מול issuer מוגדר. sub הוא מזהה המשתמש; role=authenticated הוא תפקיד מסד הנתונים בלבד.
- tenant_id שנשלח בנתיב נבדק מול חברות פעילה; הרשאות אינן נלקחות מ־user_metadata.
- אדם יכול להחזיק מרחב אישי ולהשתייך למספר עסקים. מעבר מרחב מאפס מטמונים פרטיים.
- סביבת Production פעילה בדומיין המוצר: 30 בדיקות עם JWT אמיתי עברו דרך Clerk, שרת האפליקציה ו־Supabase. הזמנות וביטול חברות מקצה לקצה עדיין נדרשים.
מקורות: lib/platform/server.ts, supabase/migrations/20261107211048_platform_foundation.sql, docs/architecture-system/verification.md.
A04 · נתונים תפעוליים ב־Supabase#
מצב: deployed. אחריות: Data.
סכימת המוצר נפרסה בפרויקט ev1 שנבחר; 31 טבלאות עם RLS, כולל נתוני ייחוס בחירת ספקים ופרופילי מרחב.
- הפרויקט בארגון digitalops ובאזור סינגפור, לפי בחירת המשתמש. פרויקט Car Dealers BMS אינו חלק מהמערכת.
- בדיקת advisor האחרונה מצאה 6 הודעות מידע על טבלאות פרטיות ללא policies — חסימת גישת לקוחות מכוונת. טבלאות בחירת הספקים נבדקו עם RLS וללא הרשאת כתיבה ישירה.
- חיבור Clerk Production ל־Supabase עבר 18 בדיקות עם JWT אמיתי ושני משתמשים: יצירת מרחב, בידוד קריאה, חסימת כתיבה בין ארגונים וחסימת יצירת חשבונית. בדיקות שרת האפליקציה והזמנות הן שער נפרד.
מקורות: supabase/migrations/0001_ev1.sql, supabase/migrations/20261107211048_platform_foundation.sql, lib/systems/dictionary.json, docs/provider-preferences.md, supabase/migrations/20261108013050_workspace_profiles.sql.
A05 · עיבוד רקע ותקשורת עם עמדות#
מצב: planned. אחריות: Charging.
RabbitMQ ו־workers נפרדים מיועדים לפקודות, לקליטת אירועים ולהתאמות.
- OCPP ישיר דורש gateway מתמשך עם WebSocket מחוץ לפונקציות Vercel. חיבור לרשת קיימת עשוי להשתמש ב־OCPI/API.
- Outbox נשמר באותה טרנזקציה עם השינוי העסקי. relay מסמן פרסום רק אחרי publisher confirm.
- צרכן מטפל במסירה חוזרת ובאירועים מחוץ לסדר. retry אינו אישור להפעיל פקודה פיזית נוספת.
מקורות: supabase/migrations/20261107211048_platform_foundation.sql.
A06 · סליקה ומסמכים#
מצב: blocked. אחריות: Payments.
בחירת PSP וגורם גובה נדרשת לפני כל תשלום אמיתי.
- איסוף אמצעי תשלום באמצעות טופס מאוחסן של הספק; אין PAN/CVV בדפדפן שלנו, במסד או בלוגים.
- תשלום טעינה ומנוי הם התחייבויות נפרדות; מצב טעינה אינו מוכיח שהכסף נגבה.
- ספק חשבוניות, מע״מ, עיגול, ביטולים והתאמה לספק טעינה טעונים החלטה מסחרית.
- הלקוח משלם עמלה באחוזים בנוסף למחיר הטעינה. מנוי חודשי/שנתי והסכם Enterprise נשמרים בגרסה נפרדת; השיעורים עדיין לא נקבעו.
מקורות: תכנון — טרם מומש.
שירותים וגבולות אמון#
A07 · דפדפן הלקוח#
מצב: foundation. אחריות: Backend.
בקשה אינה עובדה עסקית.
- השרת קובע משתמש, מרחב מורשה, תעריף, סכום ומצב טעינה.
- סכמות strict דוחות שדות עודפים. פעולות כתיבה דורשות מקור בקשה תואם ו־JSON; נדרש להוסיף rate limit לפני לקוחות חיים.
מקורות: lib/platform/validation.ts, lib/platform/api.ts.
A08 · גישה למסד ו־service role#
מצב: foundation. אחריות: Security.
גישה רגילה עם JWT של המשתמש; חריגים מצומצמים בצד השרת.
- ה־service role עוקף RLS: משמש לפעולות שרת מצומצמות לקבלת הזמנה ולסנכרון כתובות מאומתות ב־Clerk, ולשמירת פרטי רישוי רכב שאומתו מול משרד התחבורה.
- פעולות השרת בודקות מחדש חברות פעילה וחשבון פעיל במסד. כתיבת פרטי רישוי ישירה מהדפדפן חסומה; עדכון מטא־נתונים נשאר כפוף ל־RLS.
- מפתחות ספק, hash הזמנה ו־outbox בסכימה פרטית. אין הרשאות טבלה ל־anon/authenticated.
- כל פעולה privileged עתידית דורשת הקשר tenant מפורש, אימות והוספה ליומן.
מקורות: lib/platform/server.ts, lib/platform/vehicle-registration-server.ts, supabase/migrations/20261109190551_invitation_driver_lifecycle.sql, supabase/migrations/20261109191257_enforce_verified_vehicle_writes.sql.
A09 · צוות החברה#
מצב: blocked. אחריות: Security.
הרשאת owner/admin של לקוח אינה הרשאת עובד בחברה.
- הכניסה הניהולית סגורה. יש לתכנן זהות צוות, MFA והרשאות support/finance/operations.
- גישה לתמיכה בלקוח תדרוש סיבה, זמן תפוגה וביקורת; אין התחזות שקטה או tenant wildcard.
מקורות: components/company-site.tsx.
A10 · אירוע מספק חיצוני#
מצב: planned. אחריות: Integrations.
אירוע נכנס טעון אימות ומיפוי לפני שינוי נתונים.
- בדיקת חתימה על הגוף הגולמי, הגבלת גודל, replay window לפי חוזה הספק וסוד נפרד לכל סביבה.
- זיהוי tenant דרך מיפוי ספק שמור בשרת; אין אמון ב־tenant_id מגוף webhook.
- אותו event_id עם hash זהה הוא מסירה חוזרת; תוכן שונה תחת אותו מזהה מועבר לבירור.
מקורות: תכנון — טרם מומש.
A28 · מסחר, חיוב וספרי חברה#
מצב: foundation. אחריות: Product, Payments & Finance.
מנוי חודשי/שנתי + עמלת אחוזים על חשבון הלקוח + Enterprise B2B מותאם הם המודל המאושר.
- Pricing ו־Contracts מחזיקים גרסאות מחיר וקבלת תנאים; Enterprise מוגבל למרחב עסקי מורשה.
- Subscriptions מנהל תקופות וזכאות; Billing יוצר התחייבויות ושורות, Payments גובה ו־Invoicing מפיק מסמכים. אין להחליף מצב אחד בשני.
- Bookkeeping רושם תנועות מאוזנות בספרי החברה; Accounting מבצע התאמה, סגירת תקופה וייצוא למערכת החשבונאית. גישה לשירותים האלה היא staff בלבד.
- החישוב וחוזה ההסכם מיושמים ונבדקים בקוד; אין הפעלה של מנוי, סליקה, חשבוניות או ledger. מחירים, מסים וספקים טרם הוגדרו.
מקורות: lib/commercial-system/spec.json, lib/commercial-system/pricing.ts, docs/commercial-system/architecture.md.
A29 · זהות אישית ופרופיל מרחב#
מצב: foundation. אחריות: Identity & Platform.
Clerk מנהל את הפרופיל האישי וההזדהות; Supabase מנהל את זהות המרחב והלוגו לפי חברות והרשאות.
- שם, תמונה, אימייל מאומת, סיסמה ואבטחה אישית מנוהלים דרך Clerk. Google ו־Apple תלויים בהקמת חשבונות ופרטי OAuth של העסק.
- רק owner/admin עורכים פרטי חברה, איש קשר, כתובת ולוגו. סוג חשבון, בעלות, מטבע והרשאות אינם חלק מהעדכון.
- קבצי לוגו ב־Storage פרטי; API מאמת חברות בכל צפייה. קבצים מתחלפים במפתח חדש ונשמרת גרסת פרופיל נגד דריסת עדכונים.
מקורות: components/account-profile.tsx, components/platform/organization-profile.tsx, lib/platform/profile-server.ts, supabase/migrations/20261108013050_workspace_profiles.sql.
מסעות בין שירותים#
A11 · פתיחת מרחב לקוח#
מצב: foundation. אחריות: Identity.
אדם מאומת → יצירה אטומית של מרחב, בעלים ומדיניות.
- בדיקת JWT → סכמת בקשה → ev1_create_tenant עם request_id → commit → בחירת מרחב.
- מפתח בקשה חוזר מחזיר את אותו מרחב; אין לקוח שיכול לספק owner_user_id.
- נדרש להשלים אימות בענן ותנאים מסחריים לפני onboarding תפעולי.
מקורות: lib/platform/api.ts.
A12 · התחלת טעינה#
מצב: planned. אחריות: Charging.
זכאות → תקציב → אישור תשלום → פקודה → אישור ספק.
- אמת חברות, נהג, רכב, דלקן, מדיניות, מחבר ומידת עדכניות.
- שריין תקציב בטרנזקציה נעולה והקפא גרסת תעריף/גורם משלם; צור session ו־outbox אטומית.
- אישור תשלום חיצוני אינו בתוך טרנזקציית DB: סדר הפעולות ופיצוי בעת כשל חייבים להיקבע עם PSP.
- timeout לאחר שליחה נשאר במצב בירור. לא משחררים מסגרת או מחבר בלי ראיה; סטטוס charging רק אחרי אישור ספק.
מקורות: תכנון — טרם מומש.
A13 · עצירה, חיוב והתאמה#
מצב: planned. אחריות: Payments.
סיום מדידה → סכום סופי → capture → מסמך → התאמה.
- בקשת עצירה עוברת outbox; מציגים stopping עד אישור ולא הצלחה מיידית.
- מדידה מאוחרת מעובדת לפי סדר/גרסה של הספק; אירוע ישן אינו פותח טעינה סופית.
- capture משתמש במפתח פעולה יציב; webhook מאומת מעדכן עובדה כספית.
- השווה session, PSP ומסמך. פער או תשלום לא ידוע נכנסים לתור בירור עם בעל אחריות.
- בסיום מדידה מחושבים בנפרד מחיר טעינה, עמלת הלקוח והמסים לפי צילום תנאים; ההתחשבנות עם המפעיל נקבעת לפי הסכם הספק.
מקורות: תכנון — טרם מומש.
A14 · דוחות גדולים#
מצב: planned. אחריות: Data.
שאילתה מורשית → משימת יצוא → קובץ פרטי עם תפוגה.
- שאילתות כיום מוגבלות ל־1,000 רשומות מלאי ו־500 טעינות; ההגבלה מוצגת.
- להוסיף cursor מבוסס created_at,id ויצוא אסינכרוני עם סינון tenant לפני aggregation.
- הרשאה נבדקת גם בתחילת העבודה וגם בהורדה. אין URL ציבורי קבוע לנתוני צי.
מקורות: lib/platform/api.ts.
A15 · ביטול חברות וגישה#
מצב: foundation. אחריות: Identity.
מצב חברות במסד נאכף בכל קריאה גם מול JWT קיים.
- השעה membership → הבקשות הבאות נכשלות → נקה מטמון לקוח → בטל jobs פרטיים שטרם נמסרו.
- מחיקת משתמש ב־Clerk אינה תחליף לשינוי חברות במסד ולבדיקת sessions קיימים.
- הזמנה חד־פעמית משויכת לאימייל מאומת ופגה אחרי שבעה ימים.
מקורות: lib/platform/server.ts, scripts/test-tenant-isolation.mjs.
חוזי API ואירועים#
A16 · API הלקוחות הקיים#
מצב: foundation. אחריות: Backend.
ממשק JSON דרך /api/platform עם context ופעולות tenant.
- GET /api/platform/context; POST /api/platform/tenants; GET /api/platform/tenants/:id/workspace.
- POST/PATCH לרכבים, נהגים ומרכזי עלות; PATCH למדיניות ולחברות לפי הרשאה.
- 401: לא מחובר; 403: אין הרשאה; 404: חסר; 409: כפילות; 422: נתון לא תקין; 503: חיבור לא זמין.
- Cache-Control private,no-store. אין fallback להדגמה בנתיב המחובר.
מקורות: lib/platform/api.ts.
A17 · מעטפת פקודה גרסה 1#
מצב: foundation. אחריות: Integrations.
חוזה מאומת בקוד; אינו endpoint פעיל או worker מחובר.
- tenantId, sessionId, commandId ו־idempotencyKey הם UUID; סוג הפקודה start/stop.
- הקשר השרת חייב להתאים למרחב ול־session. אותו מפתח עם payload אחר הוא conflict.
- הסכמות והבדיקות מוכנות; כתיבה אטומית, חתימת ספק ושליחה יתווספו במתאם הספק.
מקורות: lib/systems/contracts.ts.
A18 · הפרדת אירועי מוצר ואירועי תפעול#
מצב: planned. אחריות: Data.
PostHog מודד שימוש; עובדות טעינה וכסף נשמרות במסד.
- אירוע תפעולי נושא גרסה, מקור, מזהה יציב וזמן occurrence מול זמן received.
- נתוני מיקום, לוחית, כתובת אימייל וטוקני סליקה אינם analytics properties או תוויות metrics.
- אירועי PostHog מוגבלים להסכמה ולחוזה האירועים של Product System.
מקורות: lib/product-system/event-contract.ts.
החלטות ארכיטקטורה#
A19 · ADR-001 · ליבה מודולרית ושירותי רקע#
מצב: planned. אחריות: Platform.
החלטת תכנון: ליבה אחת, workers ו־gateway בתהליכים נפרדים.
- היתרון: טרנזקציות פשוטות וגבולות מודול ברורים. המחיר: נדרשת משמעת בין מודולים ותלות בשחרור משותף.
- פיצול לשירותים עצמאיים ייבחן לפי עומס, גבול צוות וצורכי זמינות מוכחים.
מקורות: תכנון — טרם מומש.
A20 · ADR-002 · מקור אמת להרשאות#
מצב: foundation. אחריות: Identity.
חברות PostgreSQL קובעת את תפקיד הלקוח.
- Clerk Organizations יכולים לספק חוויית בחירת ארגון, אך אינם מחליפים את membership המקומי.
- לא להעביר tenant_role ב־JWT כמקור סמכות בלעדי; השעיה חייבת להשפיע על בקשות קיימות.
מקורות: lib/platform/server.ts.
A21 · ADR-003 · מסירה חוזרת היא צפויה#
מצב: planned. אחריות: Charging.
Outbox וצרכנים idempotent; אין הבטחת exactly-once בין ספקים.
- מפתח dedup כולל תחום ספק/חשבון/סביבה. יש לבדוק אם uniqueness(provider,event_id) הקיימת מספיקה לחוזה הספק.
- נפילה בין שליחה לאישור דורשת בירור לפני ניסיון פעולה פיזית נוסף.
מקורות: תכנון — טרם מומש.
A22 · ADR-004 · החלטות פתוחות לספקים#
מצב: blocked. אחריות: Commercial.
רשת טעינה, PSP וספק חשבוניות טרם נבחרו.
- החלטות נדרשות: OCPI/OCPP/API, merchant of record, מדידה, עיגול, מסים וזמני פקודה.
- יש להגדיר מי משלם: הנהג, המעסיק או מודל אחר, ואת אחריות החזרים ומחלוקות.
מקורות: תכנון — טרם מומש.
תפעול והתאוששות#
A23 · ניטור ואיתור תקלות#
מצב: planned. אחריות: Operations.
Grafana: זמינות API, זמני פקודה, גיל תור וחריגות התאמה.
- correlation ID מקשר API, outbox, worker וספק; אין לוג של גוף webhook או סוד.
- התראות על טעינה בלי מדידות, פקודה לא ידועה, DLQ ותשלומים ללא התאמה.
- יעדי SLO וספי התראה טעונים אישור לפי פיילוט; אינם SLA מסחרי.
מקורות: תכנון — טרם מומש.
A24 · שחזור ותקרית#
מצב: planned. אחריות: Operations.
גיבוי נבחן רק אחרי תרגיל שחזור.
- להגדיר RPO/RTO מאושרים, זמינות PITR בתוכנית Supabase ומיקום הגיבוי.
- בשיבוש ספק: חסום התחלות חדשות, המשך קליטת מדידות, שמור מזהי פקודות והפעל reconciliation.
- בשחזור DB: אמת tenant isolation, יתרות ו־outbox לפני פתיחת כתיבות. replay אינו רשאי לחייב פעמיים.
מקורות: תכנון — טרם מומש.
A25 · סודות והגנות API#
מצב: planned. אחריות: Security.
Bitwarden כמקור מנוהל; מפתחות נפרדים לפי סביבה.
- סבב החלפת סודות כולל תקופת חפיפה ואימות rollback; service role לעולם אינו NEXT_PUBLIC.
- Rate limit לפי משתמש/tenant/פעולה, הגבלת payload ו־timeouts; Origin לבד אינו הגנת abuse.
- סודות ומידע אישי אינם מועתקים לספריות המערכת או ל־CI artifacts.
מקורות: תכנון — טרם מומש.
סביבות ותוכנית מסירה#
A26 · סביבות וקידום גרסאות#
מצב: foundation. אחריות: Platform.
Development → Staging → Production עם נתונים ומפתחות נפרדים.
- קיימת תצוגת production שמציגה הדגמה; אין לייחס לה readiness תפעולי.
- סביבות זהות ומסד בדיקה נפרדות עדיין דורשות הקמה. CI בודק types/lint/unit/build; נדרש לחבר repository ו־release gates.
- שחרור סכימה בתבנית expand/migrate/contract; feature flag חדש מופעל רק אחרי בדיקות ויכולת rollback.
מקורות: .github/workflows/ci.yml.
A27 · תוכנית פיילוט וקבלת פרודקשן#
מצב: planned. אחריות: Product & Engineering.
התקדמות לפי ראיות, לא לפי מספר המסכים.
- שלב 1: סכימה, זהות ומשתמשים בשני tenants; ביטול חברות ו־JWT ישן.
- שלב 2: ספק sandbox, פקודות כפולות, ניתוק, מדידה מאוחרת ושריון תקציב במקביל.
- שלב 3: PSP sandbox, capture/refund והתאמה למסמכים; חיוב אחד לכל פעולה.
- שלב 4: טעינה אמיתית בפיילוט מצומצם, תרגיל שחזור ותמיכה מאוישת. תנאי השחרור G01–G08 נשארים חסומים עד ראיות.
מקורות: lib/product-system/spec.json.