Comtropy_CargoRadar/README.md

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.

By default the server also runs a test simulator with 10 vehicles moving around Korea. Disable it when real driver phones are connected:

SIMULATOR_ENABLED=false

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.

During early testing, keep SIMULATOR_ENABLED=true to show moving demo vehicles without Android phones. The simulator publishes fresh locations every SIMULATOR_INTERVAL_MS milliseconds.

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.

Admin Access

For sample/demo operation, admin API token checks are disabled by default:

ADMIN_AUTH_REQUIRED=false

With this setting, the control screen works regardless of the admin token value entered in the URL or prompt. Before real deployment, set ADMIN_AUTH_REQUIRED=true and use a strong ADMIN_TOKEN.

Test Simulator

The built-in simulator creates 10 test vehicles with fixed device tokens and routes across Seoul, Incheon, Daejeon, Busan, Gwangju, Ulsan, Gangwon, Jeju, and other regional hubs. It includes several freight vehicle types:

• tractor-trailer: 트레일러
• cargo-truck: 카고트럭
• box-truck: 탑차
• van: 용달차
• refrigerated: 냉동탑차
• container: 컨테이너
• wingbody: 윙바디

Each simulator tick updates latest positions through the same SSE stream used by real Android uploads, so the control screen behaves like a live fleet map.

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 = "전자부품"
  cargoQuantity = "36박스"
  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.