1

apps/api/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}

apps/api/README.md

@@ -0,0 +1,98 @@
+<p align="center">
+  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
+</p>
+
+[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
+[circleci-url]: https://circleci.com/gh/nestjs/nest
+
+  <p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
+    <p align="center">
+<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
+<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
+<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
+<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
+<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
+<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
+<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
+  <a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
+    <a href="https://opencollective.com/nest#sponsor"  target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
+  <a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
+</p>
+  <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
+  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+
+## Description
+
+[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
+
+## Project setup
+
+```bash
+$ npm install
+```
+
+## Compile and run the project
+
+```bash
+# development
+$ npm run start
+
+# watch mode
+$ npm run start:dev
+
+# production mode
+$ npm run start:prod
+```
+
+## Run tests
+
+```bash
+# unit tests
+$ npm run test
+
+# e2e tests
+$ npm run test:e2e
+
+# test coverage
+$ npm run test:cov
+```
+
+## Deployment
+
+When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
+
+If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
+
+```bash
+$ npm install -g @nestjs/mau
+$ mau deploy
+```
+
+With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
+
+## Resources
+
+Check out a few resources that may come in handy when working with NestJS:
+
+- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
+- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
+- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
+- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
+- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
+- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
+- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
+- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).
+
+## Support
+
+Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
+
+## Stay in touch
+
+- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
+- Website - [https://nestjs.com](https://nestjs.com/)
+- Twitter - [@nestframework](https://twitter.com/nestframework)
+
+## License
+
+Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).

apps/api/eslint.config.mjs

@@ -0,0 +1,35 @@
+// @ts-check
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['eslint.config.mjs'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+      sourceType: 'commonjs',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-unsafe-argument': 'warn',
+      "prettier/prettier": ["error", { endOfLine: "auto" }],
+    },
+  },
+);

apps/api/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

apps/api/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "api",
+  "version": "0.0.1",
+  "description": "",
+  "author": "",
+  "private": true,
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/main",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
+    "test:e2e": "jest --config ./test/jest-e2e.json"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.3",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/platform-express": "^11.0.1",
+    "@nestjs/swagger": "^11.2.6",
+    "@nestjs/typeorm": "^11.0.0",
+    "axios": "^1.13.6",
+    "pg": "^8.20.0",
+    "redis": "^5.11.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "swagger-ui-express": "^5.0.1",
+    "typeorm": "^0.3.28"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.18.0",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.1",
+    "@types/express": "^5.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.7",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.2",
+    "globals": "^16.0.0",
+    "jest": "^30.0.0",
+    "prettier": "^3.4.2",
+    "source-map-support": "^0.5.21",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-loader": "^9.5.2",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

apps/api/src/app.controller.spec.ts

@@ -0,0 +1,22 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+
+describe('AppController', () => {
+  let appController: AppController;
+
+  beforeEach(async () => {
+    const app: TestingModule = await Test.createTestingModule({
+      controllers: [AppController],
+      providers: [AppService],
+    }).compile();
+
+    appController = app.get<AppController>(AppController);
+  });
+
+  describe('root', () => {
+    it('should return "Hello World!"', () => {
+      expect(appController.getHello()).toBe('Hello World!');
+    });
+  });
+});

apps/api/src/app.controller.ts

@@ -0,0 +1,12 @@
+import { Controller, Get } from '@nestjs/common';
+import { AppService } from './app.service';
+
+@Controller()
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get()
+  getHello(): string {
+    return this.appService.getHello();
+  }
+}

apps/api/src/app.module.ts

@@ -0,0 +1,27 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { TelemetryModule } from './telemetry/telemetry.module';
+import { MapsModule } from './maps/maps.module';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+    }),
+    TypeOrmModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        type: 'postgres',
+        url: config.get('DATABASE_URL'),
+        autoLoadEntities: true,
+        synchronize: true, // Only for prototype! Use migrations for production.
+        // synchronize: true, // للمعاينة فقط؛ يفضل استخدام migrations للإنتاج
+      }),
+    }),
+    TelemetryModule,
+    MapsModule,
+  ],
+})
+export class AppModule {}

apps/api/src/app.service.ts

@@ -0,0 +1,8 @@
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class AppService {
+  getHello(): string {
+    return 'Hello World!';
+  }
+}

apps/api/src/common/cache.service.ts

@@ -0,0 +1,33 @@
+import { Injectable, Inject } from '@nestjs/common';
+import { createClient } from 'redis';
+import { ConfigService } from '@nestjs/config';
+
+@Injectable()
+export class CacheService {
+  private client;
+
+  constructor(private configService: ConfigService) {
+    const redisUrl = this.configService.get('REDIS_URL', 'redis://redis:6379');
+    this.client = createClient({ url: redisUrl });
+    this.client.connect().catch(console.error);
+  }
+
+  async set(key: string, value: any, ttlSeconds: number = 3600) {
+    // Cache data in Redis with TTL
+    // تخزين البيانات في Redis مع تحديد وقت انتهاء
+    await this.client.set(key, JSON.stringify(value), {
+      EX: ttlSeconds,
+    });
+  }
+
+  async get(key: string) {
+    // Retrieve cached data
+    // استرجاع البيانات المخزنة
+    const data = await this.client.get(key);
+    return data ? JSON.parse(data) : null;
+  }
+
+  async del(key: string) {
+    await this.client.del(key);
+  }
+}

apps/api/src/common/gis.utils.ts

@@ -0,0 +1,29 @@
+/**
+ * GIS Utilities for Jordan Map Platform
+ * أدوات مساعدة للتعامل مع البيانات الجغرافية
+ */
+
+export const JORDAN_BOUNDS = {
+  minLat: 29.1,
+  maxLat: 33.4,
+  minLng: 34.9,
+  maxLng: 39.3,
+};
+
+export function isWithinJordan(lat: number, lng: number): boolean {
+  return (
+    lat >= JORDAN_BOUNDS.minLat &&
+    lat <= JORDAN_BOUNDS.maxLat &&
+    lng >= JORDAN_BOUNDS.minLng &&
+    lng <= JORDAN_BOUNDS.maxLng
+  );
+}
+
+/**
+ * Snap a point to the nearest road segment (Placeholder for Map Matching logic)
+ * ربط نقطة جغرافية بأقرب مقطع طريق (تمهيد لمنطق مطابقة الخرائط)
+ */
+export function mockMapMatch(lat: number, lng: number) {
+  // In Phase 2, this would call GraphHopper Map Matching API
+  return `osm_way_${Math.floor(Math.random() * 1000000)}`;
+}

apps/api/src/main.ts

@@ -0,0 +1,29 @@
+import { NestFactory } from '@nestjs/core';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  
+  // Enable CORS for frontend
+  // تفعيل تبادل الموارد مع الواجهة الأمامية
+  app.enableCors();
+
+  // Swagger Documentation Setup
+  // إعداد توثيق API (Swagger)
+  const config = new DocumentBuilder()
+    .setTitle('Jordan Map Platform API')
+    .setDescription('Backend API for map services, routing, and driver telemetry for Jordan')
+    .setVersion('1.0')
+    .addTag('maps')
+    .addTag('telemetry')
+    .build();
+  
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api', app, document);
+
+  const port = process.env.API_PORT || 3000;
+  await app.listen(port);
+  console.log(`🚀 Jordan Map API is running on: http://localhost:${port}/api`);
+}
+bootstrap();

apps/api/src/maps/maps.controller.ts

@@ -0,0 +1,26 @@
+import { Controller, Get, Query } from '@nestjs/common';
+import { ApiTags, ApiOperation } from '@nestjs/swagger';
+import { MapsService } from './maps.service';
+
+@ApiTags('maps')
+@Controller('maps')
+export class MapsController {
+  constructor(private readonly mapsService: MapsService) {}
+
+  @Get('route')
+  @ApiOperation({ summary: 'Calculate a route between two points 🚗' })
+  async getRoute(
+    @Query('fromLat') fromLat: number,
+    @Query('fromLng') fromLng: number,
+    @Query('toLat') toLat: number,
+    @Query('toLng') toLng: number,
+  ) {
+    return this.mapsService.getRoute([fromLat, fromLng], [toLat, toLng]);
+  }
+
+  @Get('config')
+  @ApiOperation({ summary: 'Get map configuration for the region 🗺️' })
+  async getConfig() {
+    return this.mapsService.getMapConfig();
+  }
+}

apps/api/src/maps/maps.module.ts

@@ -0,0 +1,13 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { MapsService } from './maps.service';
+import { MapsController } from './maps.controller';
+import { RoadSegmentStat } from './road-stat.entity';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([RoadSegmentStat])],
+  controllers: [MapsController],
+  providers: [MapsService],
+  exports: [MapsService],
+})
+export class MapsModule {}

apps/api/src/maps/maps.service.ts

@@ -0,0 +1,71 @@
+import { Injectable, HttpException, HttpStatus } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import axios from 'axios';
+
+@Injectable()
+export class MapsService {
+  private readonly graphHopperUrl: string;
+
+  constructor(private configService: ConfigService) {
+    this.graphHopperUrl = this.configService.get('GRAPH_HOPPER_URL', 'http://map-routing:8080');
+  }
+
+  async getRoute(from: [number, number], to: [number, number]) {
+    // Proxy routing request to GraphHopper
+    // تحويل طلب حساب المسارم إلى GraphHopper
+    try {
+      const response = await axios.get(`${this.graphHopperUrl}/route`, {
+        params: {
+          point: [`${from[0]},${from[1]}`, `${to[0]},${to[1]}`],
+          profile: 'car',
+          locale: 'en',
+          calc_points: true,
+          points_encoded: false,
+          elevation: false,
+          type: 'json',
+        },
+        paramsSerializer: (params) => {
+          const searchParams = new URLSearchParams();
+          Object.entries(params).forEach(([key, value]) => {
+            if (Array.isArray(value)) {
+              value.forEach(v => searchParams.append(key, v));
+            } else {
+              searchParams.append(key, value as any);
+            }
+          });
+          return searchParams.toString();
+        },
+      });
+      
+      console.log('Routing Successful:', response.request.path);
+      
+      const route = response.data.paths[0];
+      if (!route) {
+        throw new HttpException('No route found', HttpStatus.NOT_FOUND);
+      }
+
+      return {
+        distance: route.distance, // In meters
+        duration: route.time / 1000, // In seconds
+        points: route.points.coordinates, // Array of [lng, lat]
+        bbox: route.bbox,
+      };
+    } catch (error) {
+      console.error('Routing Error:', error.message);
+      if (error.response) {
+        console.error('GraphHopper Response:', error.response.data);
+      }
+      throw new HttpException('Error calculating route', HttpStatus.BAD_GATEWAY);
+    }
+  }
+
+  async getMapConfig() {
+    // Return basic map configuration for clients
+    // إرجاع إعدادات الخريطة للواجهة الأمامية
+    return {
+      center: [31.95, 35.91], // Amman, Jordan
+      zoom: 12,
+      tileServerUrl: this.configService.get('TILE_SERVER_URL', 'http://localhost:3001'),
+    };
+  }
+}

apps/api/src/maps/road-stat.entity.ts

@@ -0,0 +1,28 @@
+import { Entity, Column, PrimaryColumn, Index } from 'typeorm';
+
+@Entity('road_segment_stats')
+export class RoadSegmentStat {
+  @PrimaryColumn()
+  segmentId: string; // OSM Way ID or similar
+
+  @Column('float', { default: 0 })
+  averageSpeed: number;
+
+  @Column('float', { default: 1.0 })
+  congestionFactor: number; // 1.0 = Free flow, >1.0 = Congested
+
+  @Column('int', { default: 0 })
+  sampleCount: number;
+
+  @Column({
+    type: 'geography',
+    spatialFeatureType: 'LineString',
+    srid: 4326,
+    nullable: true,
+  })
+  @Index({ spatial: true })
+  geometry: any;
+
+  @Column({ type: 'timestamp', default: () => 'CURRENT_TIMESTAMP' })
+  lastUpdated: Date;
+}

apps/api/test/app.e2e-spec.ts

@@ -0,0 +1,25 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication } from '@nestjs/common';
+import request from 'supertest';
+import { App } from 'supertest/types';
+import { AppModule } from './../src/app.module';
+
+describe('AppController (e2e)', () => {
+  let app: INestApplication<App>;
+
+  beforeEach(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    await app.init();
+  });
+
+  it('/ (GET)', () => {
+    return request(app.getHttpServer())
+      .get('/')
+      .expect(200)
+      .expect('Hello World!');
+  });
+});

apps/api/test/jest-e2e.json

@@ -0,0 +1,9 @@
+{
+  "moduleFileExtensions": ["js", "json", "ts"],
+  "rootDir": ".",
+  "testEnvironment": "node",
+  "testRegex": ".e2e-spec.ts$",
+  "transform": {
+    "^.+\\.(t|j)s$": "ts-jest"
+  }
+}

apps/api/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
+}

apps/api/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "resolvePackageJsonExports": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2023",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "forceConsistentCasingInFileNames": true,
+    "noImplicitAny": false,
+    "strictBindCallApply": false,
+    "noFallthroughCasesInSwitch": false
+  }
+}