# aspirant200715/neuromesh architecture

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

- Interactive diagram: https://gitdiagram.com/aspirant200715/neuromesh
- Repository: https://github.com/aspirant200715/neuromesh

## Overview

#### Purpose and runtime

NeuroMesh is an offline Android crisis-response mesh. Each Android 10+ phone senses possible emergencies, creates local assessments with on-device Gemma 4 inference or heuristic fallback, exchanges structured assessments with nearby phones, reaches consensus, and presents actionable alerts. It uses Kotlin, Coroutines/Flow, Hilt, Room, CameraX, MediaPipe LiteRT, and Android Nearby Connections; no cloud/server is required.

App bootstrap and Android entry points are `app/src/main/java/com/neuromesh/crisis/NeuroMeshApplication.kt`, `app/src/main/java/com/neuromesh/crisis/presentation/MainActivity.kt`, and `app/src/main/AndroidManifest.xml`. Critical alerts have a dedicated activity at `app/src/main/java/com/neuromesh/crisis/presentation/CrisisAlertActivity.kt`.

#### Presentation and orchestration

The UI follows MVVM. Activities and custom views render camera, mesh state, observations, and alerts; ViewModels own lifecycle-aware collection and state. `MainViewModel` is the control-plane coordinator for the detection loop, incoming mesh messages, consensus events, and active alert state.

Key paths:
- `app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MainViewModel.kt`
- `app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MeshViewModel.kt`
- `app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/CrisisViewModel.kt`

#### Local sensing and observation

Infrastructure adapters isolate Android hardware. Camera, microphone, and environmental sensors produce textual/signal descriptors rather than raw media; this is a material boundary because the Gemma model is text-oriented. The observer combines those descriptors into an `Observation`, with heuristic detection available when model loading/inference cannot run.

Key paths:
- `app/src/main/java/com/neuromesh/crisis/infrastructure/sensor/CameraSensorManager.kt`
- `app/src/main/java/com/neuromesh/crisis/infrastructure/sensor/AudioSensorManager.kt`
- `app/src/main/java/com/neuromesh/crisis/infrastructure/sensor/EnvironmentalSensorManager.kt`
- `app/src/main/java/com/neuromesh/crisis/domain/agent/ObserverAgent.kt`

#### On-device multi-agent reasoning

The domain pipeline separates perception, assessment, and guidance: `ObserverAgent` yields observations; `ReasonerAgent` fuses recent local and received observations into a `SituationAssessment` plus explainable trace; `ActionAgent` produces a `CrisisAlert`. Use cases establish the principal workflow and prevent presentation from directly coordinating infrastructure.

Gemma integration is contained behind runner/loading/prompt/parser boundaries, allowing structured-output recovery and fallback behavior.

Key paths:
- `app/src/main/java/com/neuromesh/crisis/domain/agent/ReasonerAgent.kt`
- `app/src/main/java/com/neuromesh/crisis/domain/agent/ActionAgent.kt`
- `app/src/main/java/com/neuromesh/crisis/domain/usecase/DetectCrisisUseCase.kt`
- `app/src/main/java/com/neuromesh/crisis/infrastructure/ml/Gemma4ModelRunner.kt`
- `app/src/main/java/com/neuromesh/crisis/infrastructure/ml/OutputParser.kt`

#### Peer mesh transport

Nearby Connections is encapsulated so domain code remains SDK-agnostic. The network manager advertises/discovers peers, sends and receives serialized messages, and tracks peer connectivity. Structured observations/assessments—not images, audio, or raw LLM output—cross the network boundary. Transport is Bluetooth/Wi-Fi Direct P2P, using a Bluetooth-preferred Nearby strategy.

Key paths:
- `app/src/main/java/com/neuromesh/crisis/infrastructure/network/NearbyConnectionsWrapper.kt`
- `app/src/main/java/com/neuromesh/crisis/infrastructure/network/MeshNetworkManager.kt`
- `app/src/main/java/com/neuromesh/crisis/infrastructure/network/MessageSerializer.kt`
- `app/src/main/java/com/neuromesh/crisis/data/repository/MeshRepository.kt`

#### Gossip and consensus

Received assessments enter a TTL-bounded, deduplicated gossip flow and are evaluated over a time window. `VotingStrategy` applies confidence-weighted voting; `ConsensusEngine` emits reached/disputed/no-consensus events and builds a merged assessment. A reached result triggers alert generation, then UI presentation.

Key paths:
- `app/src/main/java/com/neuromesh/crisis/domain/consensus/GossipProtocol.kt`
- `app/src/main/java/com/neuromesh/crisis/domain/consensus/ConsensusEngine.kt`
- `app/src/main/java/com/neuromesh/crisis/domain/consensus/VotingStrategy.kt`
- `app/src/main/java/com/neuromesh/crisis/domain/usecase/ShareObservationUseCase.kt`

#### Persistence, models, and dependency boundaries

Typed domain/data models carry observations, assessments, traces, alerts, and peers. Room persists observations and alerts for local continuity; repositories shield callers from DAO/network details. Hilt modules compose runtime implementations. The intended boundary is Presentation → Domain, with infrastructure owning Android SDK, ML, network, and storage access.

Key paths:
- `app/src/main/java/com/neuromesh/crisis/data/model/Observation.kt`
- `app/src/main/java/com/neuromesh/crisis/data/model/SituationAssessment.kt`
- `app/src/main/java/com/neuromesh/crisis/data/local/NeuroMeshDatabase.kt`
- `app/src/main/java/com/neuromesh/crisis/data/repository/ObservationRepository.kt`
- `app/src/main/java/com/neuromesh/crisis/di/AppModule.kt`

Main entry points: [`app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MainViewModel.kt`](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MainViewModel.kt) (MainViewModel), [`app/src/main/java/com/neuromesh/crisis/di/AppModule.kt`](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/di/AppModule.kt) (Hilt composition), [`app/src/main/java/com/neuromesh/crisis/domain/usecase/DetectCrisisUseCase.kt`](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/usecase/DetectCrisisUseCase.kt) (DetectCrisisUseCase), [`app/src/main/java/com/neuromesh/crisis/infrastructure/network/MeshNetworkManager.kt`](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/infrastructure/network/MeshNetworkManager.kt) (MeshNetworkManager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_bootstrap{{"Android bootstrap<br/>Android entry points"}}
  node_ui["Activities &amp; views<br/>Android UI<br/>[MainActivity.kt]"]
  node_main_vm["MainViewModel<br/>control-plane ViewModel<br/>[MainViewModel.kt]"]
  node_mesh_vm["MeshViewModel<br/>mesh ViewModel<br/>[MeshViewModel.kt]"]
  node_crisis_vm["CrisisViewModel<br/>alert ViewModel<br/>[CrisisViewModel.kt]"]
end

subgraph group_reasoning["Local reasoning"]
  node_sensors["Sensor descriptors<br/>hardware adapters"]
  node_observer["ObserverAgent<br/>perception agent<br/>[ObserverAgent.kt]"]
  node_detect["DetectCrisisUseCase<br/>workflow use case"]
  node_reasoner["ReasonerAgent<br/>assessment agent<br/>[ReasonerAgent.kt]"]
  node_gemma["Gemma inference boundary<br/>on-device ML runner"]
  node_action["ActionAgent<br/>guidance agent<br/>[ActionAgent.kt]"]
end

subgraph group_mesh["Peer mesh &amp; consensus"]
  node_share["ShareObservationUseCase<br/>mesh workflow"]
  node_mesh_repo["MeshRepository<br/>transport repository<br/>[MeshRepository.kt]"]
  node_mesh_transport["MeshNetworkManager<br/>Nearby transport"]
  node_gossip["GossipProtocol<br/>TTL deduplication<br/>[GossipProtocol.kt]"]
  node_consensus["ConsensusEngine<br/>consensus engine<br/>[ConsensusEngine.kt]"]
  node_voting["VotingStrategy<br/>confidence-weighted voting<br/>[VotingStrategy.kt]"]
end

subgraph group_platform["Platform adapters &amp; data"]
  node_observation_repo["ObservationRepository<br/>local repository"]
  node_database[("NeuroMeshDatabase<br/>Room database")]
  node_models["Structured models<br/>observation &amp; assessment data<br/>[Observation.kt]"]
  node_di["Hilt composition<br/>dependency injection<br/>[AppModule.kt]"]
end

node_bootstrap -->|"initializes"| node_di
node_ui -->|"renders state from"| node_main_vm
node_ui -->|"renders mesh state from"| node_mesh_vm
node_ui -->|"renders alert state from"| node_crisis_vm
node_main_vm -->|"starts detection"| node_detect
node_main_vm -->|"shares observations"| node_share
node_main_vm -->|"handles events from"| node_consensus
node_sensors -->|"textual/signal descriptors"| node_observer
node_observer -->|"Observation"| node_detect
node_detect -->|"local assessment"| node_reasoner
node_reasoner -->|"structured inference"| node_gemma
node_detect -->|"stores local results"| node_observation_repo
node_share -->|"publishes structured data"| node_mesh_repo
node_mesh_repo -->|"uses"| node_mesh_transport
node_mesh_transport -->|"received assessments"| node_gossip
node_gossip -->|"windowed candidates"| node_consensus
node_consensus -->|"evaluates with"| node_voting
node_consensus -->|"reached assessment"| node_action
node_action -->|"CrisisAlert"| node_crisis_vm
node_observation_repo -->|"persists through"| node_database
node_observer -->|"creates"| node_models
node_reasoner -->|"produces assessment"| node_models
node_mesh_transport -->|"serialized structured messages"| node_models
node_di -.->|"binds"| node_sensors
node_di -.->|"binds"| node_mesh_transport
node_di -.->|"binds"| node_gemma

click node_bootstrap "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/NeuroMeshApplication.kt"
click node_ui "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/presentation/MainActivity.kt"
click node_main_vm "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MainViewModel.kt"
click node_mesh_vm "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MeshViewModel.kt"
click node_crisis_vm "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/CrisisViewModel.kt"
click node_sensors "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/infrastructure/sensor/CameraSensorManager.kt"
click node_observer "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/agent/ObserverAgent.kt"
click node_detect "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/usecase/DetectCrisisUseCase.kt"
click node_reasoner "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/agent/ReasonerAgent.kt"
click node_gemma "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/infrastructure/ml/Gemma4ModelRunner.kt"
click node_action "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/agent/ActionAgent.kt"
click node_share "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/usecase/ShareObservationUseCase.kt"
click node_mesh_repo "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/data/repository/MeshRepository.kt"
click node_mesh_transport "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/infrastructure/network/MeshNetworkManager.kt"
click node_gossip "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/consensus/GossipProtocol.kt"
click node_consensus "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/consensus/ConsensusEngine.kt"
click node_voting "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/consensus/VotingStrategy.kt"
click node_observation_repo "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/data/repository/ObservationRepository.kt"
click node_database "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/data/local/NeuroMeshDatabase.kt"
click node_models "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/data/model/Observation.kt"
click node_di "https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/di/AppModule.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_bootstrap,node_ui,node_main_vm,node_mesh_vm,node_crisis_vm toneBlue
class node_sensors,node_observer,node_detect,node_reasoner,node_gemma,node_action toneAmber
class node_share,node_mesh_repo,node_mesh_transport,node_gossip,node_consensus,node_voting toneMint
class node_observation_repo,node_database,node_models,node_di toneRose
```

## Components

### Presentation

- [Android bootstrap](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/NeuroMeshApplication.kt): Android entry points · Initializes the offline app runtime and alert activity. · `app/src/main/java/com/neuromesh/crisis/NeuroMeshApplication.kt`
- [Activities & views](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/presentation/MainActivity.kt): Android UI · Renders camera, mesh state, observations, and alerts. · `app/src/main/java/com/neuromesh/crisis/presentation/MainActivity.kt`
- [MainViewModel](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MainViewModel.kt): control-plane ViewModel · Coordinates detection, mesh input, consensus, and active alerts. · `app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MainViewModel.kt`
- [MeshViewModel](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MeshViewModel.kt): mesh ViewModel · `app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/MeshViewModel.kt`
- [CrisisViewModel](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/CrisisViewModel.kt): alert ViewModel · `app/src/main/java/com/neuromesh/crisis/presentation/viewmodel/CrisisViewModel.kt`

### Local reasoning

- [Sensor descriptors](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/infrastructure/sensor/CameraSensorManager.kt): hardware adapters · Camera, audio, and environmental signals are converted to descriptors. · `app/src/main/java/com/neuromesh/crisis/infrastructure/sensor/CameraSensorManager.kt`
- [ObserverAgent](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/agent/ObserverAgent.kt): perception agent · Combines local descriptors into observations. · `app/src/main/java/com/neuromesh/crisis/domain/agent/ObserverAgent.kt`
- [DetectCrisisUseCase](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/usecase/DetectCrisisUseCase.kt): workflow use case · Runs the local observation-to-assessment workflow. · `app/src/main/java/com/neuromesh/crisis/domain/usecase/DetectCrisisUseCase.kt`
- [ReasonerAgent](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/agent/ReasonerAgent.kt): assessment agent · Fuses recent local and received observations with an explainable trace. · `app/src/main/java/com/neuromesh/crisis/domain/agent/ReasonerAgent.kt`
- [Gemma inference boundary](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/infrastructure/ml/Gemma4ModelRunner.kt): on-device ML runner · Loads Gemma, prompts it, parses structured output, and permits fallback. · `app/src/main/java/com/neuromesh/crisis/infrastructure/ml/Gemma4ModelRunner.kt`
- [ActionAgent](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/agent/ActionAgent.kt): guidance agent · Turns reached assessments into crisis alerts. · `app/src/main/java/com/neuromesh/crisis/domain/agent/ActionAgent.kt`

### Peer mesh & consensus

- [ShareObservationUseCase](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/usecase/ShareObservationUseCase.kt): mesh workflow · `app/src/main/java/com/neuromesh/crisis/domain/usecase/ShareObservationUseCase.kt`
- [MeshRepository](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/data/repository/MeshRepository.kt): transport repository · Shields callers from mesh transport details. · `app/src/main/java/com/neuromesh/crisis/data/repository/MeshRepository.kt`
- [MeshNetworkManager](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/infrastructure/network/MeshNetworkManager.kt): Nearby transport · Advertises, discovers, sends, receives, and tracks peers. · `app/src/main/java/com/neuromesh/crisis/infrastructure/network/MeshNetworkManager.kt`
- [GossipProtocol](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/consensus/GossipProtocol.kt): TTL deduplication · Bounds and deduplicates received assessments. · `app/src/main/java/com/neuromesh/crisis/domain/consensus/GossipProtocol.kt`
- [ConsensusEngine](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/consensus/ConsensusEngine.kt): consensus engine · Evaluates time-windowed assessments and emits consensus events. · `app/src/main/java/com/neuromesh/crisis/domain/consensus/ConsensusEngine.kt`
- [VotingStrategy](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/domain/consensus/VotingStrategy.kt): confidence-weighted voting · `app/src/main/java/com/neuromesh/crisis/domain/consensus/VotingStrategy.kt`

### Platform adapters & data

- [ObservationRepository](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/data/repository/ObservationRepository.kt): local repository · Provides local continuity for observations and alerts. · `app/src/main/java/com/neuromesh/crisis/data/repository/ObservationRepository.kt`
- [NeuroMeshDatabase](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/data/local/NeuroMeshDatabase.kt): Room database · Persists observations and alerts on device. · `app/src/main/java/com/neuromesh/crisis/data/local/NeuroMeshDatabase.kt`
- [Structured models](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/data/model/Observation.kt): observation & assessment data · Only structured observations and assessments cross peer boundaries. · `app/src/main/java/com/neuromesh/crisis/data/model/Observation.kt`
- [Hilt composition](https://github.com/aspirant200715/neuromesh/blob/main/app/src/main/java/com/neuromesh/crisis/di/AppModule.kt): dependency injection · Binds runtime implementations at application composition. · `app/src/main/java/com/neuromesh/crisis/di/AppModule.kt`

## Connections

- Android bootstrap → Hilt composition: initializes
- Activities & views → MainViewModel: renders state from
- Activities & views → MeshViewModel: renders mesh state from
- Activities & views → CrisisViewModel: renders alert state from
- MainViewModel → DetectCrisisUseCase: starts detection
- MainViewModel → ShareObservationUseCase: shares observations
- MainViewModel → ConsensusEngine: handles events from
- Sensor descriptors → ObserverAgent: textual/signal descriptors
- ObserverAgent → DetectCrisisUseCase: Observation
- DetectCrisisUseCase → ReasonerAgent: local assessment
- ReasonerAgent → Gemma inference boundary: structured inference
- DetectCrisisUseCase → ObservationRepository: stores local results
- ShareObservationUseCase → MeshRepository: publishes structured data
- MeshRepository → MeshNetworkManager: uses
- MeshNetworkManager → GossipProtocol: received assessments
- GossipProtocol → ConsensusEngine: windowed candidates
- ConsensusEngine → VotingStrategy: evaluates with
- ConsensusEngine → ActionAgent: reached assessment
- ActionAgent → CrisisViewModel: CrisisAlert
- ObservationRepository → NeuroMeshDatabase: persists through
- ObserverAgent → Structured models: creates
- ReasonerAgent → Structured models: produces assessment
- MeshNetworkManager → Structured models: serialized structured messages
- Hilt composition → Sensor descriptors: binds
- Hilt composition → MeshNetworkManager: binds
- Hilt composition → Gemma inference boundary: binds