How guberm/device-activity-tracker works
1. Repo shape
This is a two-part TypeScript project: a Node.js backend/CLI in the repository root and a separate React frontend in client/. The architecture is centered on collecting delivery-receipt RTTs from messaging platforms, classifying device state, and streaming updates to a live UI.
2. Primary runtime boundaries
There are three execution modes:
- CLI mode via src/index.ts for WhatsApp-only tracking.
- Backend server mode via src/server.ts for real-time web usage.
- Frontend browser app in client/src/ for visualization and control.
In Dockerized deployment, these are split into multiple containers plus a Signal API service.
3. Backend core
The backend is the main orchestration layer. src/server.ts provides an Express API and Socket.IO channel for real-time events. It likely accepts start/stop commands, connection status, and RTT updates from the tracker modules, then pushes those updates to the browser.
4. Platform-specific tracking engines
Tracking logic is separated by messaging platform:
- src/tracker.ts handles WhatsApp RTT probing and analysis.
- src/signal-tracker.ts handles Signal RTT probing and analysis.
This separation is important because the data source, probe method, and integration surface differ by platform.
5. WhatsApp integration path
WhatsApp tracking uses Baileys (per README) to connect to WhatsApp Web semantics over WebSocket/QR login. The backend measures the time from probe send to delivery confirmation and uses that as the RTT signal for device-state inference.
6. Signal integration path
Signal is not accessed directly by the backend; it goes through a Signal CLI REST API service. src/scripts/init-signal.ts exists to initialize or prepare that service, which becomes a separate runtime dependency in Docker and during npm run dev / npm run start:signal-api.
7. Detection pipeline
The core data flow is:
probe send → delivery receipt/acknowledgement → RTT calculation → threshold comparison → device state
The README describes a dynamic threshold based on the median RTT, which means the backend continuously adapts to network conditions rather than using a fixed cutoff.
8. Realtime UI flow
The frontend does not compute the tracker logic itself; it consumes live state from the backend over Socket.IO/WebSocket. The UI is composed of Login, Dashboard, and ContactCard, with Dashboard acting as the main visualization surface for RTT, online/standby/offline state, and contact selection.
9. Frontend/backend boundary
The browser app is a presentation and control layer, while the Node backend owns credentials, platform sessions, RTT measurement, and classification. This boundary is important: the frontend is stateless with respect to tracking and depends on the backend for live updates and session state.
10. Configuration and environment
Runtime behavior is driven by .env values such as backend/client ports and API URLs. The repo’s port split (3000 client, 3001 backend, 8080 Signal API) indicates the app is designed to run as a small distributed system rather than a single monolith.
11. Containerization and deployment
Dockerfile, client/Dockerfile, and docker-compose.yml show the project is intended to run as multiple containers: backend, frontend, and Signal API. This matters architecturally because it formalizes service boundaries and makes the Signal dependency explicit.
12. Build/tooling boundaries
TypeScript is used on both sides, but the toolchains are separate: root tsconfig.json for backend/CLI code and client/tsconfig.json for React. The frontend uses the standard React build pipeline with Tailwind/PostCSS, while the backend is a Node 20+ TypeScript service.
13. Important diagram framing
An accurate architecture diagram should show:
- external messaging systems: WhatsApp and Signal
- a Node backend with separate WhatsApp and Signal tracker modules
- a real-time Socket.IO channel to the browser UI
- a Signal REST API container as an externalized dependency
- optional CLI entry point as an alternate control path
Main entry points: server.ts Server mode · tracker.ts WhatsApp tracker · docker-compose.yml Compose stack · App.tsx App shell
Components 19
Runtime boundaries
Separate execution modes and external dependencies.
- WhatsApp · Delivery receipt source for RTT probing.
- Signal · Delivery receipt source for RTT probing.
- Signal API · Externalized Signal CLI HTTP dependency used by the backend.
Node backend
Core orchestration, tracking, and real-time serving.
- CLI mode · WhatsApp-only command-line execution path.
src/index.ts - Server mode · Express and Socket.IO runtime for web control and live updates.
src/server.ts - WhatsApp tracker · Probes WhatsApp delivery receipts and computes RTT.
src/tracker.ts - Signal tracker · Probes Signal delivery receipts through the API service and computes RTT.
src/signal-tracker.ts - Init Signal · Prepares or initializes the Signal API service.
src/scripts/init-signal.ts - RTT pipeline · Probe send, receipt confirmation, RTT calculation, thresholding, and device-state inference.
- Socket.IO · Pushes live tracking events from backend to browser clients.
- Express API · Receives start/stop and status requests from the UI and runtime tools.
React client
Browser UI for status display and control.
- Login · Authentication and session entry screen.
client/src/components/Login.tsx - Dashboard · Primary live visualization for RTT, device state, and contact selection.
client/src/components/Dashboard.tsx - Contact card · Displays and selects tracked contacts.
client/src/components/ContactCard.tsx - App shell · Client composition root and routing into the main screens.
client/src/App.tsx - Client entry · Mounts the React application in the browser.
client/src/index.tsx
Deployment
Container and process composition for the distributed app.
- Backend image · Node runtime image for server and tracker processes.
Dockerfile - Frontend image · Build and serve image for the React client.
client/Dockerfile - Compose stack · Defines the multi-container backend, client, and Signal API deployment.
docker-compose.yml
Connections 20
- WhatsApp → WhatsApp tracker: delivery receipts · WhatsApp platform events feed the RTT engine.
- Signal → Signal API: platform access · Signal is accessed through the REST API service.
- Signal API → Signal tracker: receipt events · The API service provides delivery confirmations to the tracker.
- CLI mode → WhatsApp tracker: runs · CLI mode invokes WhatsApp tracking directly.
- Server mode → WhatsApp tracker: controls · Server mode can start and stop WhatsApp tracking.
- Server mode → Signal tracker: controls · Server mode can start and stop Signal tracking.
- WhatsApp tracker → RTT pipeline: updates · WhatsApp RTT measurements flow into classification.
- Signal tracker → RTT pipeline: updates · Signal RTT measurements flow into classification.
- RTT pipeline → Socket.IO: live state · Classified device state is broadcast to browsers.
- Server mode → Express API: serves · Express exposes control and status endpoints.
- Server mode → Socket.IO: publishes · Socket.IO streams live updates to connected clients.
- Socket.IO → Client entry: subscribes · The browser app consumes live tracking events.
- Client entry → App shell: mounts · Client bootstrap loads the React application.
- App shell → Login: renders · Login screen is part of the app flow.
- App shell → Dashboard: renders · Dashboard is the main live view.
- Dashboard → Contact card: uses · Dashboard composes contact selection and status cards.
- Compose stack → Backend image: builds · Compose includes the backend container image.
- Compose stack → Frontend image: builds · Compose includes the frontend container image.
- Compose stack → Signal API: runs · Compose deploys the Signal API as a separate service.
- Init Signal → Signal API: initializes · Bootstrap script prepares the Signal service runtime.