maps-saas/PROJECT_GUIDE.md

Map SaaS Platform - Hyper-Detailed Engineering Guide / الدليل الهندسي التفصيلي العميق لمنصة خرائط ساس

This is the definitive, "ground-zero" guide to the Map SaaS platform. It is designed to explain not just how the code works, but the engineering philosophy and the "Why" behind every architectural decision.

هذا هو الدليل المرجعي والنهائي لمنصة Map SaaS. تم تصميمه لشرح ليس فقط كيفية عمل الكود، ولكن أيضاً الفلسفة الهندسية و"السبب" وراء كل قرار معماري تم اتخاذه.

---

1. Project Philosophy: Why Own the Infrastructure? / فلسفة المشروع: لماذا نمتلك البنية التحتية؟

English: Most developers use Google Maps or Mapbox APIs. While easy, these are expensive and restrict how you use the data. This project is built on the philosophy of Sovereignty. By using OpenStreetMap (OSM), PostGIS, and Martin, we own the entire stack. We don't pay per map view, and we can customize the map logic (like routing rules for specific vehicles) to a level impossible with commercial APIs.

عربي: معظم المطورين يستخدمون واجهات برمجة تطبيقات (APIs) مثل خرائط جوجل أو Mapbox. رغم سهولتها، إلا أنها مكلفة وتقيد كيفية استخدامك للبيانات. تم بناء هذا المشروع على فلسفة السيادة التقنية. من خلال استخدام OpenStreetMap (OSM) و PostGIS و Martin، نحن نمتلك "الكومة" التقنية بالكامل. نحن لا ندفع مقابل كل عرض للخريطة، ويمكننا تخصيص منطق الخريطة (مثل قواعد التوجيه لمركبات معينة) بمستوى مستحيل مع واجهات برمجة التطبيقات التجارية.

---

2. Infrastructure Deep-Dive (Docker Compose) / التعمق في البنية التحتية (Docker Compose)

English: We use Docker Compose to orchestrate 6 distinct services. Each service is isolated, ensuring that a bug in the routing engine doesn't crash the database.

عربي: نستخدم Docker Compose لتنظيم 6 خدمات متميزة. كل خدمة معزولة، مما يضمن أن أي عطل في محرك التوجيه لن يؤدي إلى انهيار قاعدة البيانات.

Service-by-Service Breakdown / تفصيل الخدمات من الناحية التقنية:

A. PostGIS (db)

• Why? / لماذا؟: Standard PostgreSQL cannot understand that a "Point" at (35.9, 31.9) is "inside" a "Polygon". PostGIS adds spatial types and functions.
• Arabic / تفصيل بالعربي: قاعدة بيانات PostgreSQL العادية لا تستطيع فهم أن "نقطة" في الإحداثيات (35.9, 31.9) تقع "داخل" شكل هندسي (Polygon). إضافة PostGIS تضيف أنواعاً وظائف مكانية تسمح لنا بإجراء استعلامات SQL مثل: "ابحث عن أقرب صيدلية لهذا الموقع".
• Config / الإعداد: image: postgis/postgis:15-3.3 -> We use version 15 for stability and PostGIS 3.3 for the latest spatial performance.

B. Martin (martin)

• Why? / لماذا؟: This is our Tile Server. Instead of pre-rendering millions of PNG images (which takes terabytes of space), Martin generates Vector Tiles (MVT) on-the-fly.
• Arabic / تفصيل بالعربي: هذا هو خادم البلاطات. بدلاً من الرصد المسبق لملايين صور PNG (التي تستهلك مساحات هائلة)، يقوم Martin بإنشاء بلاطات المتجهات (MVT) بشكل فوري عند الطلب من قاعدة البيانات.
• Logic / المنطق: It connects directly to PostGIS via the DATABASE_URL and serves tables as map layers.

C. GraphHopper (routing)

• Why? / لماذا؟: While PostGIS can find distances, it doesn't know about one-way streets, traffic lights, or speed limits. GraphHopper converts OSM data into a mathematical "Graph" of nodes and edges to find the mathematically shortest/fastest path.
• Arabic / تفصيل بالعربي: رغم أن PostGIS يمكنه حساب المسافات، إلا أنه لا يعرف شيئاً عن الشوارع ذات الاتجاه الواحد، أو إشارات المرور، أو حدود السرعة. يقوم GraphHopper بتحويل بيانات OSM إلى "رسم بياني" رياضي (Graph) مكون من عقد وحواف للعثور على أقصر أو أسرع مسار رياضياً.

D. API (api) & Web (web)

• Why? / لماذا؟: The API acts as a gateway (using NestJS) to bundle logic and proxy requests. The Web (React/Vite) provides the visual interface using MapLibre GL.
• Arabic / تفصيل بالعربي: يعمل الـ API كبوابة (باستخدام NestJS) لتجميع المنطق وتوجيه الطلبات. يوفر الـ Web (React/Vite) الواجهة المرئية باستخدام MapLibre GL لقراءة بلاطات المتجهات ورسمها.

---

3. Backend Logic: The Brain / منطق الخلفية البرمجية: العقل

English: The API is built using NestJS. We chose this because of its modular architecture, which mirrors our microservices.

عربي: تم بناء الـ API باستخدام NestJS. اخترنا هذا بسبب هيكليته المودولية (Modular Architecture)، والتي تعكس خدماتنا المصغرة.

Maps Module Deep-Dive / تعمق في موديول الخرائط:

maps.controller.ts

• EN: Handles HTTP requests like GET /maps/route. It validates input before passing it to the service.
• AR: يتعامل مع طلبات HTTP مثل GET /maps/route. يقوم بالتحقق من صحة المدخلات قبل تمريرها إلى الخدمة (Service).

maps.service.ts

• EN: This is where the heavy lifting happens. It communicates with GraphHopper.
• AR: هنا يحدث العمل الفعلي الثقيل. تتواصل هذه الخدمة مع GraphHopper.
• Why Proxy? / لماذا التوجيه البرمجي؟: We proxy GraphHopper through the API so that:
  1. We can add authentication. / يمكننا إضافة مصادقة (Security).
  2. We can cache frequent routes in Redis. / يمكننا تخزين المسارات المتكررة في Redis لزيادة السرعة.
  3. We hide the internal infrastructure (like port 8989) from the public internet. / نخفي البنية التحتية الداخلية عن الإنترنت العام.

---

4. Frontend Logic: The Interface / منطق الواجهة الأمامية: الواجهة

English: The frontend uses MapLibre GL, an open-source library for high-performance interactive maps.

عربي: تستخدم الواجهة الأمامية MapLibre GL، وهي مكتبة مفتوحة المصدر للخرائط التفاعلية عالية الأداء.

MapComponent.tsx Explained / شرح مكون الخريطة:

• Sources & Layers / المصادر والطبقات:
  • EN: We define Sources (where the data comes from, i.e., Martin) and Layers (how the data looks, e.g., coloring roads blue).
  • AR: نقوم بتعريف المصادر (Sources) (من أين تأتي البيانات، أي من Martin) و الطبقات (Layers) (كيف تبدو البيانات، مثل تلوين الطرق باللون الأزرق).
• 3D Logic / منطق ثلاثي الأبعاد:
  • We use the fill-extrusion layer type to turn 2D building outlines into 3D blocks by calculating heights from OSM data.
  • نستخدم نوع الطبقة fill-extrusion لتحويل حدود المباني ثنائية الأبعاد إلى كتل ثلاثية الأبعاد من خلال حساب الارتفاعات من بيانات OSM.

---

5. Command Tutorial: Step-by-Step / دليل الأوامر: خطوة بخطوة

1. docker-compose up -d

• Why? / لماذا؟: -d stands for "detached". It runs the servers in the background so your terminal remains free.
• AR: حرف -d يعني "Detached". يقوم بتشغيل الخوادم في الخلفية حتى يظل التيرمينال (Terminal) متاحاً لك للاستخدام.

2. docker-compose run --rm osm-import

• Why? / لماذا؟:
  • run: Starts the importer. / يبدأ عملية الاستيراد.
  • --rm: Automatically removes the container after it finishes to save disk space. / يحذف الحاوية تلقائياً بعد الانتهاء لتوفير مساحة القرص.
  • Technical Goal: It uses osm2pgsql to convert the jordan-latest.osm.pbf file (raw data) into relational SQL tables in PostGIS.
  • الهدف التقني: يستخدم أداة osm2pgsql لتحويل ملف بيانات الأردن (البيانات الخام) إلى جداول SQL علائقية داخل PostGIS ليتمكن Martin من قراءتها.

---

6. Glossary of Terms (Advanced) / قاموس المصطلحات (متقدم)

• MVT (Mapbox Vector Tiles): The binary format we use to transmit map data over the wire. Small and fast. / التنسيق الثنائي الذي نستخدمه لنقل بيانات الخريطة عبر الشبكة. صغير وسريع.
• PBF (Protocolbuffer Binary Format): The compressed format for OpenStreetMap data. / التنسيق المضغوط لبيانات OpenStreetMap.
• Reverse Proxy: The pattern of the API sitting between the user and internal services like GraphHopper. / نمط عمل الـ API عندما يقع بين المستخدم والخدمات الداخلية (مثل GraphHopper) لحمايتها وإدارتها.
• Schema: The structure of the database tables where map data is stored. / هيكلية جداول قاعدة البيانات حيث يتم تخزين بيانات الخريطة.

---

This guide is your roadmap. Use it to build the future of mapping! / هذا الدليل هو خارطة الطريق الخاصة بك. استخدمه لبناء مستقبل الخرائط!