# abdelrahman-zaka/jana-s_trial architecture

> Architecture diagram of the GitHub repository abdelrahman-zaka/jana-s_trial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdelrahman-zaka/jana-s_trial
- Repository: https://github.com/abdelrahman-zaka/jana-s_trial

## Overview

TRACE is an Android field-measurement app: users grant permissions, then foreground monitoring records target-app sessions and radio, location, traffic, and playback observations. Guided active network tests complement passive sampling; events are buffered and persisted locally, then uploaded in batches. The repository also includes Python tools for importing and aligning measurement data. Edges below follow shown calls or README-independent source-index references; unsampled integrations and tool relationships are omitted where ownership is unclear.

Main entry points: [`trace/android/app/src/main/java/eg/cu/trace/core/EventSink.kt`](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/core/EventSink.kt) (Event buffering), [`trace/android/app/src/main/java/eg/cu/trace/session/SessionManager.kt`](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/session/SessionManager.kt) (Session state), [`trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt`](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt) (App runtime), [`trace/android/app/src/main/java/eg/cu/trace/active/ActiveTestRunner.kt`](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/active/ActiveTestRunner.kt) (Guided network tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App control"]
  node_ui["Setup and controls<br/>[MainActivity.kt]"]
  node_appinit["App runtime<br/>[TraceApp.kt]"]
  node_monitor["Foreground monitor<br/>[MonitorService.kt]"]
  node_session["Session state<br/>[SessionManager.kt]"]
  node_foreground["App foreground tracking"]
end

subgraph group_measure["Measurement"]
  node_radio["Radio sampling<br/>[RadioCollector.kt]"]
  node_radiomath["Radio calculations<br/>[RadioMath.kt]"]
  node_collectors["Context and location<br/>[Collectors.kt]"]
  node_labprobes["Lab probes<br/>[LabProbes.kt]"]
  node_qoe["Playback QoE"]
  node_active["Guided network tests"]
end

subgraph group_events["Event pipeline"]
  node_event["Measurement event<br/>[Event.kt]"]
  node_params["Runtime parameters<br/>[TraceParams.kt]"]
  node_clock["Clock anchoring<br/>[TraceClock.kt]"]
  node_sntp["SNTP time source<br/>[Sntp.kt]"]
  node_sink["Event buffering<br/>[EventSink.kt]"]
end

subgraph group_delivery["Data delivery"]
  node_database[("Local event database<br/>[TraceDb.kt]")]
  node_upload["Batch uploader<br/>[UploadWorker.kt]"]
  node_ingest(("Ingest service"))
end

subgraph group_analysis["Data tools"]
  node_align["Timestamp alignment<br/>[align.py]"]
  node_pulseimport["PULSE import<br/>[pulse_import.py]"]
  node_clockbridge["Clock bridge<br/>[t3_clock_bridge.py]"]
  node_decimate["Trace decimation<br/>[decimate.py]"]
end

node_participant(("Participant"))

node_participant -->|"configures"| node_ui
node_ui -->|"uses runtime"| node_appinit
node_ui -->|"starts tests"| node_active
node_appinit -->|"creates"| node_sink
node_appinit -->|"creates"| node_clock
node_appinit -->|"creates"| node_session
node_appinit -->|"creates"| node_active
node_appinit -->|"schedules"| node_upload
node_monitor -->|"starts"| node_radio
node_monitor -->|"starts"| node_collectors
node_monitor -->|"creates probes"| node_labprobes
node_monitor -->|"starts and ends"| node_session
node_session -->|"tracks foreground"| node_foreground
node_session -->|"emits session events"| node_sink
node_session -->|"anchors session"| node_clock
node_session -->|"closes session"| node_database
node_radio -->|"uses calculations"| node_radiomath
node_radio -->|"emits samples"| node_sink
node_collectors -->|"emits samples"| node_sink
node_labprobes -->|"emits probes"| node_sink
node_qoe -->|"emits playback events"| node_sink
node_active -->|"emits test results"| node_sink
node_active -->|"checks recording"| node_session
node_sink -->|"writes batches"| node_database
node_sink -->|"serializes"| node_event
node_clock -->|"emits anchors"| node_sink
node_clock -->|"queries time"| node_sntp
node_sink -->|"uses settings"| node_params
node_active -->|"uses settings"| node_params
node_upload -->|"reads and acknowledges"| node_database
node_upload -->|"posts batches"| node_ingest
node_upload -->|"reports purge"| node_sink
node_align -.->|"uses bridge"| node_clockbridge
node_pulseimport -->|"uses bridge"| node_clockbridge
node_align -.->|"processes traces"| node_decimate

click node_ui "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/ui/MainActivity.kt"
click node_appinit "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt"
click node_monitor "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/service/MonitorService.kt"
click node_session "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/session/SessionManager.kt"
click node_foreground "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/session/ForegroundTracker.kt"
click node_radio "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/collect/RadioCollector.kt"
click node_radiomath "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/collect/RadioMath.kt"
click node_collectors "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/collect/Collectors.kt"
click node_labprobes "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/lab/java/eg/cu/trace/lab/LabProbes.kt"
click node_qoe "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/qoe/MediaSessionProbe.kt"
click node_active "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/active/ActiveTestRunner.kt"
click node_event "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/core/Event.kt"
click node_params "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/gen/TraceParams.kt"
click node_clock "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/core/TraceClock.kt"
click node_sntp "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/core/Sntp.kt"
click node_sink "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/core/EventSink.kt"
click node_database "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/store/TraceDb.kt"
click node_upload "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/upload/UploadWorker.kt"
click node_align "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/tools/align.py"
click node_pulseimport "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/tools/pulse_import.py"
click node_clockbridge "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/tools/t3_clock_bridge.py"
click node_decimate "https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/tools/decimate.py"

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_ui,node_appinit,node_monitor,node_session,node_foreground toneBlue
class node_radio,node_radiomath,node_collectors,node_labprobes,node_qoe,node_active toneAmber
class node_event,node_params,node_clock,node_sntp,node_sink toneMint
class node_database,node_upload,node_ingest toneRose
class node_align,node_pulseimport,node_clockbridge,node_decimate,node_participant toneIndigo
```

## Components

### App control

- [Setup and controls](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/ui/MainActivity.kt): `trace/android/app/src/main/java/eg/cu/trace/ui/MainActivity.kt`
- [App runtime](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt): `trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt`
- [Foreground monitor](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/service/MonitorService.kt): `trace/android/app/src/main/java/eg/cu/trace/service/MonitorService.kt`
- [Session state](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/session/SessionManager.kt): `trace/android/app/src/main/java/eg/cu/trace/session/SessionManager.kt`
- [App foreground tracking](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/session/ForegroundTracker.kt): `trace/android/app/src/main/java/eg/cu/trace/session/ForegroundTracker.kt`

### Measurement

- [Radio sampling](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/collect/RadioCollector.kt): `trace/android/app/src/main/java/eg/cu/trace/collect/RadioCollector.kt`
- [Radio calculations](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/collect/RadioMath.kt): `trace/android/app/src/main/java/eg/cu/trace/collect/RadioMath.kt`
- [Context and location](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/collect/Collectors.kt): `trace/android/app/src/main/java/eg/cu/trace/collect/Collectors.kt`
- [Lab probes](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/lab/java/eg/cu/trace/lab/LabProbes.kt): `trace/android/app/src/lab/java/eg/cu/trace/lab/LabProbes.kt`
- [Playback QoE](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/qoe/MediaSessionProbe.kt): `trace/android/app/src/main/java/eg/cu/trace/qoe/MediaSessionProbe.kt`
- [Guided network tests](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/active/ActiveTestRunner.kt): `trace/android/app/src/main/java/eg/cu/trace/active/ActiveTestRunner.kt`

### Event pipeline

- [Measurement event](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/core/Event.kt): `trace/android/app/src/main/java/eg/cu/trace/core/Event.kt`
- [Runtime parameters](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/gen/TraceParams.kt): `trace/android/app/src/main/java/eg/cu/trace/gen/TraceParams.kt`
- [Clock anchoring](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/core/TraceClock.kt): `trace/android/app/src/main/java/eg/cu/trace/core/TraceClock.kt`
- [SNTP time source](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/core/Sntp.kt): `trace/android/app/src/main/java/eg/cu/trace/core/Sntp.kt`
- [Event buffering](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/core/EventSink.kt): `trace/android/app/src/main/java/eg/cu/trace/core/EventSink.kt`

### Data delivery

- [Local event database](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/store/TraceDb.kt): `trace/android/app/src/main/java/eg/cu/trace/store/TraceDb.kt`
- [Batch uploader](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/android/app/src/main/java/eg/cu/trace/upload/UploadWorker.kt): `trace/android/app/src/main/java/eg/cu/trace/upload/UploadWorker.kt`
- **Ingest service**

### Data tools

- [Timestamp alignment](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/tools/align.py): `trace/tools/align.py`
- [PULSE import](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/tools/pulse_import.py): `trace/tools/pulse_import.py`
- [Clock bridge](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/tools/t3_clock_bridge.py): `trace/tools/t3_clock_bridge.py`
- [Trace decimation](https://github.com/abdelrahman-zaka/jana-s_trial/blob/main/trace/tools/decimate.py): `trace/tools/decimate.py`

### Other components

- **Participant**

## Connections

- Participant → Setup and controls: configures (evidence: `trace/android/app/src/main/java/eg/cu/trace/ui/MainActivity.kt`)
- Setup and controls → App runtime: uses runtime (evidence: `trace/android/app/src/main/java/eg/cu/trace/ui/MainActivity.kt`)
- Setup and controls → Guided network tests: starts tests (evidence: `trace/android/app/src/main/java/eg/cu/trace/ui/MainActivity.kt`)
- App runtime → Event buffering: creates (evidence: `trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt`)
- App runtime → Clock anchoring: creates (evidence: `trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt`)
- App runtime → Session state: creates (evidence: `trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt`)
- App runtime → Guided network tests: creates (evidence: `trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt`)
- App runtime → Batch uploader: schedules (evidence: `trace/android/app/src/main/java/eg/cu/trace/TraceApp.kt`)
- Foreground monitor → Radio sampling: starts (evidence: `trace/android/app/src/main/java/eg/cu/trace/service/MonitorService.kt`)
- Foreground monitor → Context and location: starts (evidence: `trace/android/app/src/main/java/eg/cu/trace/service/MonitorService.kt`)
- Foreground monitor → Lab probes: creates probes (evidence: `trace/android/app/src/main/java/eg/cu/trace/service/MonitorService.kt`)
- Foreground monitor → Session state: starts and ends (evidence: `trace/android/app/src/main/java/eg/cu/trace/service/MonitorService.kt`)
- Session state → App foreground tracking: tracks foreground (evidence: `trace/android/app/src/main/java/eg/cu/trace/session/SessionManager.kt`)
- Session state → Event buffering: emits session events (evidence: `trace/android/app/src/main/java/eg/cu/trace/session/SessionManager.kt`)
- Session state → Clock anchoring: anchors session (evidence: `trace/android/app/src/main/java/eg/cu/trace/session/SessionManager.kt`)
- Session state → Local event database: closes session (evidence: `trace/android/app/src/main/java/eg/cu/trace/session/SessionManager.kt`)
- Radio sampling → Radio calculations: uses calculations (evidence: `trace/android/app/src/main/java/eg/cu/trace/collect/RadioCollector.kt`)
- Radio sampling → Event buffering: emits samples (evidence: `trace/android/app/src/main/java/eg/cu/trace/collect/RadioCollector.kt`)
- Context and location → Event buffering: emits samples (evidence: `trace/android/app/src/main/java/eg/cu/trace/collect/Collectors.kt`)
- Lab probes → Event buffering: emits probes (evidence: `trace/android/app/src/lab/java/eg/cu/trace/lab/LabProbes.kt`)
- Playback QoE → Event buffering: emits playback events (evidence: `trace/android/app/src/main/java/eg/cu/trace/qoe/MediaSessionProbe.kt`)
- Guided network tests → Event buffering: emits test results (evidence: `trace/android/app/src/main/java/eg/cu/trace/active/ActiveTestRunner.kt`)
- Guided network tests → Session state: checks recording (evidence: `trace/android/app/src/main/java/eg/cu/trace/active/ActiveTestRunner.kt`)
- Event buffering → Local event database: writes batches (evidence: `trace/android/app/src/main/java/eg/cu/trace/core/EventSink.kt`)
- Event buffering → Measurement event: serializes (evidence: `trace/android/app/src/main/java/eg/cu/trace/core/EventSink.kt`)
- Clock anchoring → Event buffering: emits anchors (evidence: `trace/android/app/src/main/java/eg/cu/trace/core/TraceClock.kt`)
- Clock anchoring → SNTP time source: queries time (evidence: `trace/android/app/src/main/java/eg/cu/trace/core/TraceClock.kt`)
- Event buffering → Runtime parameters: uses settings (evidence: `trace/android/app/src/main/java/eg/cu/trace/core/EventSink.kt`)
- Guided network tests → Runtime parameters: uses settings (evidence: `trace/android/app/src/main/java/eg/cu/trace/active/ActiveTestRunner.kt`)
- Batch uploader → Local event database: reads and acknowledges (evidence: `trace/android/app/src/main/java/eg/cu/trace/upload/UploadWorker.kt`)
- Batch uploader → Ingest service: posts batches (evidence: `trace/android/app/src/main/java/eg/cu/trace/upload/UploadWorker.kt`)
- Batch uploader → Event buffering: reports purge (evidence: `trace/android/app/src/main/java/eg/cu/trace/upload/UploadWorker.kt`)
- Timestamp alignment → Clock bridge: uses bridge
- PULSE import → Clock bridge: uses bridge (evidence: `trace/tools/pulse_import.py`)
- Timestamp alignment → Trace decimation: processes traces
