From 65ce6a0ba22de9e2c33fdd4accb53a9ebd839759 Mon Sep 17 00:00:00 2001
From: Hamza-Ayed <hamzaayedflutter@gmail.com>
Date: Fri, 20 Mar 2026 01:53:40 +0300
Subject: [PATCH] first commit

---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5338037
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# Jordan Map SaaS Platform 🗺️
+# منصة خرائط الأردن البرمجية
+
+A complete self-hosted mapping platform prototype for Jordan, built with OpenStreetMap, GraphHopper, and NestJS.
+
+## 🚀 Quick Start / البدء السريع
+
+1.  **Clone the repository**
+2.  **Run the setup script** to download Jordan OSM data:
+    ```bash
+    npm run setup
+    ```
+3.  **Perform one-time OSM import** into PostGIS:
+    ```bash
+    docker-compose --profile import up osm-import
+    ```
+4.  **Start the platform**:
+    ```bash
+    docker-compose up --build
+    ```
+
+## 🏗️ Architecture / المعمارية البرمجية
+
+-   **Backend**: NestJS (API Gateway, Telemetry Ingestion, Routing Proxy)
+-   **Frontend**: React + MapLibre GL JS (Interactive Map Dashboard)
+-   **Database**: PostgreSQL + PostGIS (Spatial persistence)
+-   **Routing**: GraphHopper (Java-based OSM routing engine)
+-   **Cache**: Redis (Hot driver positions and API caching)
+-   **Tile Server**: Tileserver-GL (Serving Jordan vector/raster tiles)
+
+## 📡 Key API Endpoints / أهم الروابط البرمجية
+
+| Endpoint | Method | Description |
+| :--- | :--- | :--- |
+| `/api` | GET | Swagger Documentation |
+| `/maps/config` | GET | Map center and region bounds |
+| `/maps/route` | GET | Routing between two points |
+| `/telemetry` | POST | Ingest driver location (every 3s) |
+| `/telemetry/nearby`| GET | Find drivers within a radius |
+
+## 🛠️ Tech Stack / التقنيات المستخدمة
+
+-   **Node.js v18**
+-   **PostGIS 15**
+-   **GraphHopper Latest**
+-   **MapLibre GL JS**
+
+## 📝 Arabic Comments / ملاحظات باللغة العربية
+تم تصميم هذا النظام ليكون نواة لمنصة خرائط تجارية تدعم تطبيقات التوصيل والنقل الذكي في الأردن، مع التركيز على استيعاب بيانات الموقع اللحظية للسائقين كل 3 ثواني ومعالجتها مكانياً.
+
+## ⚠️ Limitations / القيود الحالية
+-   Does not include full Map Matching for traffic light delay logic (Phase 2).
+-   Requires manual download of MBTiles for high-performance tile serving in production.