# 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.