CargoRadar

CargoRadar is an MVP for tracking freight drivers from an Android app and monitoring their latest positions from a web control screen.

Current Shape

• apps/server: Node.js API server with no external runtime dependencies.
• apps/web: Static control web UI served by the API server.
• apps/android: Kotlin Android driver-app skeleton.
• runtime-data: Docker runtime data directory, created on first run.

Run Locally

If Node.js is installed:

node apps/server/src/server.js

Open:

http://localhost:8080

The web screen has a 샘플 위치 button that posts a demo location with the default demo-token.

Run With Docker

copy .env.example .env
docker compose up --build

Open:

http://localhost:8080

On Synology NAS, the same docker-compose.yml can be used through Container Manager or SSH. Keep runtime-data mounted so driver tokens and location history survive container restarts.

For NAS, use .env.nas.example as the starting point and prefer port 18081 behind Synology Reverse Proxy.

Maintenance Scripts

Check server status:

.\scripts\health-check.ps1 -BaseUrl "http://127.0.0.1:8080"

Send a demo location:

.\scripts\post-demo-location.ps1 -BaseUrl "http://127.0.0.1:8080"

Back up runtime data:

.\scripts\backup-runtime-data.ps1

Kakao Map

The Kakao JavaScript key has a project default in the server config. You can override it in .env:

KAKAO_JAVASCRIPT_KEY=<override_key>

The REST API key and native app key are not needed for the current web map screen.

In Kakao Developers, register every web origin that will open the control screen. Useful early entries are:

http://localhost:8080
http://127.0.0.1:8080
http://<NAS-LAN-IP>:18081
https://<NAS-domain>

If the origin is missing, Kakao's map SDK can return HTTP 403 and the control screen will show a map-key/domain warning.

Device Token

On first server start, the server creates:

runtime-data/drivers.json

The default driver is:

{
  "driverId": "demo-driver",
  "name": "Demo Driver",
  "vehicleNo": "SEOUL-12-3456",
  "token": "demo-token",
  "enabled": true
}

Change the token before real use.

API

Driver management:

GET    /api/v1/drivers
POST   /api/v1/drivers
PATCH  /api/v1/drivers/:driverId
DELETE /api/v1/drivers/:driverId

Upload a location:

$body = @{
  driverId = "demo-driver"
  vehicleNo = "SEOUL-12-3456"
  latitude = 37.5665
  longitude = 126.9780
  accuracy = 12
  speed = 42
  heading = 90
  cargoName = "전자부품"
  cargoWeight = "1.2t"
  origin = "서울 상차지"
  destination = "평택 물류센터"
  recordedAt = (Get-Date).ToUniversalTime().ToString("o")
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "http://localhost:8080/api/v1/locations" `
  -Method Post `
  -Headers @{ "X-Device-Token" = "demo-token" } `
  -ContentType "application/json" `
  -Body $body

Read latest locations:

GET /api/v1/locations/latest

Read history:

GET /api/v1/locations/history?driverId=demo-driver&limit=200

Realtime events:

GET /api/v1/events

Android

Open apps/android in Android Studio and run the app module.

• Emulator server URL: http://10.0.2.2:8080
• Real phone server URL: http://<NAS-or-PC-LAN-IP>:8080
• Driver ID and device token: use the values from the web 기사 tab.

For production, use HTTPS and disable Android cleartext traffic.

Operation Flow

1. Start the server on a PC or Synology NAS.
2. Open the control web screen.
3. Register a driver in the 기사 tab.
4. Copy that driver's token into the Android app.
5. Start tracking from the Android app.
6. Confirm the latest location in the 위치 tab.

Next Steps

• Replace JSONL storage with PostgreSQL/PostGIS when history queries become important.
• Expand driver/vehicle management with search and editing.
• Add route playback and detailed location history filters.
• Add route, geofence, and delayed-reception alerts.
• Add Synology reverse proxy, HTTPS, and admin authentication for deployment.