# black1plague2/jugaad-agent architecture

> Architecture diagram of the GitHub repository black1plague2/jugaad-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/black1plague2/jugaad-agent
- Repository: https://github.com/black1plague2/jugaad-agent

## Overview

Jugaad Agent is an offline Android machine-condition monitoring app: a technician creates equipment, records a per-machine reference, captures later readings, and reviews scored, actionable diagnoses and history. The README documents synchronized audio and motion sensing, feature extraction, anomaly scoring, catalogue-based fault suggestions, and optional advice. Separate federated-learning capabilities train and merge classifier variants phone-to-phone over local WiFi. The architecture links reflect documented responsibilities and workflow; unsampled subsystem wiring is not inferred.

Main entry points: [`app/src/main/java/com/jugaad/agent/domain/usecase/DiagnoseUseCase.kt`](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/domain/usecase/DiagnoseUseCase.kt) (Diagnosis workflow), [`app/src/main/java/com/jugaad/agent/sensor/CaptureCoordinator.kt`](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/sensor/CaptureCoordinator.kt) (Capture coordination), [`app/src/main/java/com/jugaad/agent/ui/nav/JugaadNavGraph.kt`](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ui/nav/JugaadNavGraph.kt) (Equipment screens), [`app/src/main/java/com/jugaad/agent/domain/usecase/CaptureBaselineUseCase.kt`](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/domain/usecase/CaptureBaselineUseCase.kt) (Reference workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Technician workflow"]
  node_screens["Equipment screens<br/>[JugaadNavGraph.kt]"]
  node_results["Result and history<br/>[ResultScreen.kt]"]
end

subgraph group_measurement["Measurement and diagnosis"]
  node_capture["Capture coordination"]
  node_sensors["Phone sensors<br/>[AudioCapture.kt]"]
  node_features["Signal features"]
  node_diagnose["Diagnosis workflow<br/>[DiagnoseUseCase.kt]"]
  node_anomaly["Anomaly scoring<br/>[AnomalyScorer.kt]"]
  node_rules["Fault rules<br/>[RulesEngine.kt]"]
  node_advice["Maintenance advice"]
end

subgraph group_domain["Domain and persistence"]
  node_catalog["Machine catalogue<br/>[MachineCatalog.kt]"]
  node_baseline["Reference workflow"]
  node_assets[("Equipment and references")]
  node_history[("Diagnosis history")]
end

subgraph group_federation["Federated learning"]
  node_training["Federated runtime<br/>[FlRuntime.kt]"]
  node_classifier["On-device classifier<br/>[FaultClassifier.kt]"]
end

subgraph group_connectivity["Peer networking"]
  node_sync["Sync coordinator"]
  node_service["Sync service<br/>[FlSyncService.kt]"]
  node_discovery["Peer discovery<br/>[LanDiscovery.kt]"]
end

node_technician(("Technician"))
node_peers(("Nearby phones"))

node_technician -->|"uses"| node_screens
node_screens -->|"starts reference"| node_baseline
node_screens -->|"starts reading"| node_capture
node_baseline -->|"records clips"| node_capture
node_capture -->|"samples together"| node_sensors
node_capture -->|"extracts features"| node_features
node_features -->|"forms reference"| node_baseline
node_baseline -->|"saves reference"| node_assets
node_diagnose -->|"captures reading"| node_capture
node_diagnose -->|"extracts features"| node_features
node_diagnose -->|"reads reference"| node_assets
node_diagnose -->|"scores deviation"| node_anomaly
node_diagnose -->|"ranks issues"| node_rules
node_rules -->|"evaluates faults"| node_catalog
node_diagnose -->|"classifies fault"| node_classifier
node_diagnose -->|"requests action"| node_advice
node_diagnose -->|"saves result"| node_history
node_screens -->|"requests diagnosis"| node_diagnose
node_results -->|"shows readings"| node_history
node_training -->|"trains head"| node_classifier
node_service -->|"advertises node"| node_discovery
node_service -->|"runs rounds"| node_sync
node_sync -->|"exchanges weights"| node_peers
node_peers -->|"announces presence"| node_discovery

click node_screens "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ui/nav/JugaadNavGraph.kt"
click node_results "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ui/result/ResultScreen.kt"
click node_capture "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/sensor/CaptureCoordinator.kt"
click node_sensors "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/sensor/AudioCapture.kt"
click node_features "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/FeatureExtractor.kt"
click node_diagnose "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/domain/usecase/DiagnoseUseCase.kt"
click node_anomaly "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/anomaly/AnomalyScorer.kt"
click node_rules "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/diagnosis/RulesEngine.kt"
click node_advice "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/advisor/MaintenanceAdvisor.kt"
click node_catalog "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/core/config/MachineCatalog.kt"
click node_baseline "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/domain/usecase/CaptureBaselineUseCase.kt"
click node_assets "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/data/repository/AssetRepositoryImpl.kt"
click node_history "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/data/repository/DiagnosisRepositoryImpl.kt"
click node_training "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/fl/FlRuntime.kt"
click node_classifier "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/classifier/FaultClassifier.kt"
click node_sync "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/p2p/FedAvgCoordinator.kt"
click node_service "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/p2p/FlSyncService.kt"
click node_discovery "https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/p2p/LanDiscovery.kt"

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_screens,node_results toneBlue
class node_capture,node_sensors,node_features,node_diagnose,node_anomaly,node_rules,node_advice toneAmber
class node_catalog,node_baseline,node_assets,node_history toneMint
class node_training,node_classifier toneRose
class node_sync,node_service,node_discovery,node_technician,node_peers toneIndigo
```

## Components

### Technician workflow

- [Equipment screens](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ui/nav/JugaadNavGraph.kt): `app/src/main/java/com/jugaad/agent/ui/nav/JugaadNavGraph.kt`
- [Result and history](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ui/result/ResultScreen.kt): `app/src/main/java/com/jugaad/agent/ui/result/ResultScreen.kt`

### Measurement and diagnosis

- [Capture coordination](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/sensor/CaptureCoordinator.kt): `app/src/main/java/com/jugaad/agent/sensor/CaptureCoordinator.kt`
- [Phone sensors](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/sensor/AudioCapture.kt): `app/src/main/java/com/jugaad/agent/sensor/AudioCapture.kt`
- [Signal features](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/FeatureExtractor.kt): `app/src/main/java/com/jugaad/agent/ml/FeatureExtractor.kt`
- [Diagnosis workflow](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/domain/usecase/DiagnoseUseCase.kt): `app/src/main/java/com/jugaad/agent/domain/usecase/DiagnoseUseCase.kt`
- [Anomaly scoring](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/anomaly/AnomalyScorer.kt): `app/src/main/java/com/jugaad/agent/ml/anomaly/AnomalyScorer.kt`
- [Fault rules](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/diagnosis/RulesEngine.kt): `app/src/main/java/com/jugaad/agent/ml/diagnosis/RulesEngine.kt`
- [Maintenance advice](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/advisor/MaintenanceAdvisor.kt): `app/src/main/java/com/jugaad/agent/ml/advisor/MaintenanceAdvisor.kt`

### Domain and persistence

- [Machine catalogue](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/core/config/MachineCatalog.kt): `app/src/main/java/com/jugaad/agent/core/config/MachineCatalog.kt`
- [Reference workflow](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/domain/usecase/CaptureBaselineUseCase.kt): `app/src/main/java/com/jugaad/agent/domain/usecase/CaptureBaselineUseCase.kt`
- [Equipment and references](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/data/repository/AssetRepositoryImpl.kt): `app/src/main/java/com/jugaad/agent/data/repository/AssetRepositoryImpl.kt`
- [Diagnosis history](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/data/repository/DiagnosisRepositoryImpl.kt): `app/src/main/java/com/jugaad/agent/data/repository/DiagnosisRepositoryImpl.kt`

### Federated learning

- [Federated runtime](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/fl/FlRuntime.kt): `app/src/main/java/com/jugaad/agent/fl/FlRuntime.kt`
- [On-device classifier](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/ml/classifier/FaultClassifier.kt): `app/src/main/java/com/jugaad/agent/ml/classifier/FaultClassifier.kt`

### Peer networking

- [Sync coordinator](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/p2p/FedAvgCoordinator.kt): `app/src/main/java/com/jugaad/agent/p2p/FedAvgCoordinator.kt`
- [Sync service](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/p2p/FlSyncService.kt): `app/src/main/java/com/jugaad/agent/p2p/FlSyncService.kt`
- [Peer discovery](https://github.com/black1plague2/jugaad-agent/blob/main/app/src/main/java/com/jugaad/agent/p2p/LanDiscovery.kt): `app/src/main/java/com/jugaad/agent/p2p/LanDiscovery.kt`

### Other components

- **Technician**
- **Nearby phones**

## Connections

- Technician → Equipment screens: uses
- Equipment screens → Reference workflow: starts reference
- Equipment screens → Capture coordination: starts reading
- Reference workflow → Capture coordination: records clips
- Capture coordination → Phone sensors: samples together
- Capture coordination → Signal features: extracts features
- Signal features → Reference workflow: forms reference
- Reference workflow → Equipment and references: saves reference
- Diagnosis workflow → Capture coordination: captures reading
- Diagnosis workflow → Signal features: extracts features
- Diagnosis workflow → Equipment and references: reads reference
- Diagnosis workflow → Anomaly scoring: scores deviation
- Diagnosis workflow → Fault rules: ranks issues
- Fault rules → Machine catalogue: evaluates faults
- Diagnosis workflow → On-device classifier: classifies fault
- Diagnosis workflow → Maintenance advice: requests action
- Diagnosis workflow → Diagnosis history: saves result
- Equipment screens → Diagnosis workflow: requests diagnosis
- Result and history → Diagnosis history: shows readings
- Federated runtime → On-device classifier: trains head
- Sync service → Peer discovery: advertises node
- Sync service → Sync coordinator: runs rounds
- Sync coordinator → Nearby phones: exchanges weights
- Nearby phones → Peer discovery: announces presence