# guberm/device-activity-tracker architecture

> Architecture diagram of the GitHub repository guberm/device-activity-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guberm/device-activity-tracker
- Repository: https://github.com/guberm/device-activity-tracker

## Overview

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: [`src/server.ts`](https://github.com/guberm/device-activity-tracker/blob/master/src/server.ts) (Server mode), [`src/tracker.ts`](https://github.com/guberm/device-activity-tracker/blob/master/src/tracker.ts) (WhatsApp tracker), [`docker-compose.yml`](https://github.com/guberm/device-activity-tracker/blob/master/docker-compose.yml) (Compose stack), [`client/src/App.tsx`](https://github.com/guberm/device-activity-tracker/blob/master/client/src/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime boundaries"]
  node_whatsapp(("WhatsApp<br/>messaging platform"))
  node_signal(("Signal<br/>messaging platform"))
  node_signal_api["Signal API<br/>REST service"]
end

subgraph group_backend["Node backend"]
  node_cli_entry["CLI mode<br/>entrypoint<br/>[index.ts]"]
  node_server_entry["Server mode<br/>entrypoint<br/>[server.ts]"]
  node_wa_tracker["WhatsApp tracker<br/>rtt engine<br/>[tracker.ts]"]
  node_sig_tracker["Signal tracker<br/>rtt engine<br/>[signal-tracker.ts]"]
  node_signal_init["Init Signal<br/>bootstrap script<br/>[init-signal.ts]"]
  node_rtt_pipeline{{"RTT pipeline<br/>classification flow"}}
  node_socket_channel(("Socket.IO<br/>realtime channel"))
  node_express_api["Express API<br/>http control surface"]
end

subgraph group_client["React client"]
  node_login_view["Login<br/>ui screen<br/>[Login.tsx]"]
  node_dashboard_view["Dashboard<br/>ui screen<br/>[Dashboard.tsx]"]
  node_contact_card["Contact card<br/>ui component<br/>[ContactCard.tsx]"]
  node_app_shell["App shell<br/>react app<br/>[App.tsx]"]
  node_frontend_boot["Client entry<br/>bootstrap<br/>[index.tsx]"]
end

subgraph group_deploy["Deployment"]
  node_backend_image[("Backend image<br/>container")]
  node_frontend_image[("Frontend image<br/>container")]
  node_compose_stack["Compose stack<br/>deployment config<br/>[docker-compose.yml]"]
end

node_whatsapp -->|"delivery receipts"| node_wa_tracker
node_signal -->|"platform access"| node_signal_api
node_signal_api -->|"receipt events"| node_sig_tracker
node_cli_entry -->|"runs"| node_wa_tracker
node_server_entry -->|"controls"| node_wa_tracker
node_server_entry -->|"controls"| node_sig_tracker
node_wa_tracker -->|"updates"| node_rtt_pipeline
node_sig_tracker -->|"updates"| node_rtt_pipeline
node_rtt_pipeline -->|"live state"| node_socket_channel
node_server_entry -->|"serves"| node_express_api
node_server_entry -->|"publishes"| node_socket_channel
node_socket_channel -->|"subscribes"| node_frontend_boot
node_frontend_boot -->|"mounts"| node_app_shell
node_app_shell -->|"renders"| node_login_view
node_app_shell -->|"renders"| node_dashboard_view
node_dashboard_view -->|"uses"| node_contact_card
node_compose_stack -->|"builds"| node_backend_image
node_compose_stack -->|"builds"| node_frontend_image
node_compose_stack -->|"runs"| node_signal_api
node_signal_init -->|"initializes"| node_signal_api

click node_cli_entry "https://github.com/guberm/device-activity-tracker/blob/master/src/index.ts"
click node_server_entry "https://github.com/guberm/device-activity-tracker/blob/master/src/server.ts"
click node_wa_tracker "https://github.com/guberm/device-activity-tracker/blob/master/src/tracker.ts"
click node_sig_tracker "https://github.com/guberm/device-activity-tracker/blob/master/src/signal-tracker.ts"
click node_signal_init "https://github.com/guberm/device-activity-tracker/blob/master/src/scripts/init-signal.ts"
click node_login_view "https://github.com/guberm/device-activity-tracker/blob/master/client/src/components/Login.tsx"
click node_dashboard_view "https://github.com/guberm/device-activity-tracker/blob/master/client/src/components/Dashboard.tsx"
click node_contact_card "https://github.com/guberm/device-activity-tracker/blob/master/client/src/components/ContactCard.tsx"
click node_app_shell "https://github.com/guberm/device-activity-tracker/blob/master/client/src/App.tsx"
click node_frontend_boot "https://github.com/guberm/device-activity-tracker/blob/master/client/src/index.tsx"
click node_backend_image "https://github.com/guberm/device-activity-tracker/tree/master/Dockerfile"
click node_frontend_image "https://github.com/guberm/device-activity-tracker/tree/master/client/Dockerfile"
click node_compose_stack "https://github.com/guberm/device-activity-tracker/blob/master/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_whatsapp,node_signal,node_signal_api toneBlue
class node_cli_entry,node_server_entry,node_wa_tracker,node_sig_tracker,node_signal_init,node_rtt_pipeline,node_socket_channel,node_express_api toneAmber
class node_login_view,node_dashboard_view,node_contact_card,node_app_shell,node_frontend_boot toneMint
class node_backend_image,node_frontend_image,node_compose_stack toneRose
```

## Components

### Runtime boundaries

Separate execution modes and external dependencies.

- **WhatsApp**: messaging platform · Delivery receipt source for RTT probing.
- **Signal**: messaging platform · Delivery receipt source for RTT probing.
- **Signal API**: REST service · Externalized Signal CLI HTTP dependency used by the backend.

### Node backend

Core orchestration, tracking, and real-time serving.

- [CLI mode](https://github.com/guberm/device-activity-tracker/blob/master/src/index.ts): entrypoint · WhatsApp-only command-line execution path. · `src/index.ts`
- [Server mode](https://github.com/guberm/device-activity-tracker/blob/master/src/server.ts): entrypoint · Express and Socket.IO runtime for web control and live updates. · `src/server.ts`
- [WhatsApp tracker](https://github.com/guberm/device-activity-tracker/blob/master/src/tracker.ts): rtt engine · Probes WhatsApp delivery receipts and computes RTT. · `src/tracker.ts`
- [Signal tracker](https://github.com/guberm/device-activity-tracker/blob/master/src/signal-tracker.ts): rtt engine · Probes Signal delivery receipts through the API service and computes RTT. · `src/signal-tracker.ts`
- [Init Signal](https://github.com/guberm/device-activity-tracker/blob/master/src/scripts/init-signal.ts): bootstrap script · Prepares or initializes the Signal API service. · `src/scripts/init-signal.ts`
- **RTT pipeline**: classification flow · Probe send, receipt confirmation, RTT calculation, thresholding, and device-state inference.
- **Socket.IO**: realtime channel · Pushes live tracking events from backend to browser clients.
- **Express API**: http control surface · Receives start/stop and status requests from the UI and runtime tools.

### React client

Browser UI for status display and control.

- [Login](https://github.com/guberm/device-activity-tracker/blob/master/client/src/components/Login.tsx): ui screen · Authentication and session entry screen. · `client/src/components/Login.tsx`
- [Dashboard](https://github.com/guberm/device-activity-tracker/blob/master/client/src/components/Dashboard.tsx): ui screen · Primary live visualization for RTT, device state, and contact selection. · `client/src/components/Dashboard.tsx`
- [Contact card](https://github.com/guberm/device-activity-tracker/blob/master/client/src/components/ContactCard.tsx): ui component · Displays and selects tracked contacts. · `client/src/components/ContactCard.tsx`
- [App shell](https://github.com/guberm/device-activity-tracker/blob/master/client/src/App.tsx): react app · Client composition root and routing into the main screens. · `client/src/App.tsx`
- [Client entry](https://github.com/guberm/device-activity-tracker/blob/master/client/src/index.tsx): bootstrap · Mounts the React application in the browser. · `client/src/index.tsx`

### Deployment

Container and process composition for the distributed app.

- [Backend image](https://github.com/guberm/device-activity-tracker/tree/master/Dockerfile): container · Node runtime image for server and tracker processes. · `Dockerfile`
- [Frontend image](https://github.com/guberm/device-activity-tracker/tree/master/client/Dockerfile): container · Build and serve image for the React client. · `client/Dockerfile`
- [Compose stack](https://github.com/guberm/device-activity-tracker/blob/master/docker-compose.yml): deployment config · Defines the multi-container backend, client, and Signal API deployment. · `docker-compose.yml`

## Connections

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