# pratikdas-vtu/nexus architecture

> Architecture diagram of the GitHub repository pratikdas-vtu/nexus, 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/pratikdas-vtu/nexus
- Repository: https://github.com/pratikdas-vtu/nexus

## Overview

NEXUS is an offline-first emergency and community mesh app: people report incidents, devices validate and queue them locally, then relay them opportunistically to peers and responders. Field views and an admin dashboard support situational awareness and coordination. The graph follows documented layers and sampled call sites; unsampled implementation details are represented only where the README or repository tree establishes the capability, so uncertain wiring is omitted.

Main entry points: [`backend/data/incidentService.ts`](https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/incidentService.ts) (Incident Service), [`frontend/src/context/ServiceContext.tsx`](https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/context/ServiceContext.tsx) (Service Context), [`networking/multiTransportManager.ts`](https://github.com/pratikdas-vtu/nexus/blob/main/networking/multiTransportManager.ts) (Transport Manager), [`networking/relayEngine.ts`](https://github.com/pratikdas-vtu/nexus/blob/main/networking/relayEngine.ts) (Relay Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Field And Command"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_field["Field Views"]
  node_admin["Command Dashboard"]
end

subgraph group_incident["Incident Lifecycle"]
  node_services["Service Context<br/>[ServiceContext.tsx]"]
  node_report["Incident Service<br/>[incidentService.ts]"]
  node_schema["Validation Schema<br/>[schema.ts]"]
  node_dedup["Ingest Checks<br/>[dedup.ts]"]
  node_priority["Priority Rules<br/>[priority.ts]"]
  node_outbox["Relay Outbox<br/>[outboxService.ts]"]
  node_database[("Local Incident Store<br/>[db.ts]")]
  node_mapper["Incident Mapper<br/>[incidentMapper.ts]"]
end

subgraph group_mesh["Mesh Coordination"]
  node_coordinator["Network Coordinator"]
  node_relay["Relay Engine<br/>[relayEngine.ts]"]
  node_protocol["Wire Protocol<br/>[protocol.ts]"]
end

subgraph group_transport["Peer Transports"]
  node_manager["Transport Manager"]
  node_nearby["Nearby Controller"]
  node_rtc["WebRTC Transport<br/>[webRtcTransport.ts]"]
  node_websocket["WebSocket Transport"]
  node_signaling["LAN Signaling<br/>[signalingClient.ts]"]
end

subgraph group_native["Native Radio"]
  node_bridge["Native Bridge<br/>[nativeBridge.ts]"]
  node_plugin["Android Plugin"]
end

node_community(("Community / Responder"))
node_radios{{"Android Radios"}}
node_peers(("Nearby Peer Devices"))
node_gemini{{"Gemini API"}}

node_community -->|"uses"| node_app
node_app -->|"renders"| node_field
node_app -->|"opens"| node_admin
node_field -->|"reads services"| node_services
node_admin -->|"manages incidents"| node_services
node_services -->|"creates and updates"| node_report
node_report -->|"validates"| node_schema
node_report -->|"assigns priority"| node_priority
node_report -->|"ingests through"| node_dedup
node_report -->|"persists"| node_database
node_report -->|"queues"| node_outbox
node_services -->|"maps incidents"| node_mapper
node_services -->|"coordinates network"| node_coordinator
node_coordinator -->|"starts relay"| node_relay
node_coordinator -->|"manages connections"| node_manager
node_relay -->|"uses transports"| node_manager
node_relay -->|"encodes messages"| node_protocol
node_relay -->|"syncs queued reports"| node_outbox
node_nearby -->|"calls"| node_bridge
node_nearby -->|"registers connections"| node_manager
node_bridge -->|"bridges calls"| node_plugin
node_plugin -->|"discovers and connects"| node_radios
node_radios -->|"links devices"| node_peers
node_manager -.->|"selects transport"| node_rtc
node_manager -.->|"selects transport"| node_websocket
node_signaling -.->|"coordinates sessions"| node_peers
node_field -.->|"requests triage"| node_gemini

click node_app "https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/App.tsx"
click node_field "https://github.com/pratikdas-vtu/nexus/tree/main/frontend/src/components"
click node_admin "https://github.com/pratikdas-vtu/nexus/tree/main/frontend/src/admin"
click node_services "https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/context/ServiceContext.tsx"
click node_report "https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/incidentService.ts"
click node_schema "https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/schema.ts"
click node_dedup "https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/dedup.ts"
click node_priority "https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/priority.ts"
click node_outbox "https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/outboxService.ts"
click node_database "https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/db.ts"
click node_mapper "https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/services/incidentMapper.ts"
click node_coordinator "https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/services/networkCoordinator.ts"
click node_relay "https://github.com/pratikdas-vtu/nexus/blob/main/networking/relayEngine.ts"
click node_protocol "https://github.com/pratikdas-vtu/nexus/blob/main/shared/protocol.ts"
click node_manager "https://github.com/pratikdas-vtu/nexus/blob/main/networking/multiTransportManager.ts"
click node_nearby "https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/services/nearbyMeshController.ts"
click node_rtc "https://github.com/pratikdas-vtu/nexus/blob/main/networking/webRtcTransport.ts"
click node_websocket "https://github.com/pratikdas-vtu/nexus/blob/main/networking/webSocketTransport.ts"
click node_signaling "https://github.com/pratikdas-vtu/nexus/blob/main/networking/signalingClient.ts"
click node_bridge "https://github.com/pratikdas-vtu/nexus/blob/main/networking/nativeBridge.ts"
click node_plugin "https://github.com/pratikdas-vtu/nexus/blob/main/android/app/src/main/java/org/nexus/mesh/NexusNativePlugin.java"

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_app,node_field,node_admin toneBlue
class node_services,node_report,node_schema,node_dedup,node_priority,node_outbox,node_database,node_mapper toneAmber
class node_coordinator,node_relay,node_protocol,node_gemini toneMint
class node_manager,node_nearby,node_rtc,node_websocket,node_signaling toneRose
class node_bridge,node_plugin,node_community,node_radios,node_peers toneIndigo
```

## Components

### Field And Command

- [Application Shell](https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Field Views](https://github.com/pratikdas-vtu/nexus/tree/main/frontend/src/components): `frontend/src/components`
- [Command Dashboard](https://github.com/pratikdas-vtu/nexus/tree/main/frontend/src/admin): `frontend/src/admin`

### Incident Lifecycle

- [Service Context](https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/context/ServiceContext.tsx): `frontend/src/context/ServiceContext.tsx`
- [Incident Service](https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/incidentService.ts): `backend/data/incidentService.ts`
- [Validation Schema](https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/schema.ts): `backend/data/schema.ts`
- [Ingest Checks](https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/dedup.ts): `backend/data/dedup.ts`
- [Priority Rules](https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/priority.ts): `backend/data/priority.ts`
- [Relay Outbox](https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/outboxService.ts): `backend/data/outboxService.ts`
- [Local Incident Store](https://github.com/pratikdas-vtu/nexus/blob/main/backend/data/db.ts): `backend/data/db.ts`
- [Incident Mapper](https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/services/incidentMapper.ts): `frontend/src/services/incidentMapper.ts`

### Mesh Coordination

- [Network Coordinator](https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/services/networkCoordinator.ts): `frontend/src/services/networkCoordinator.ts`
- [Relay Engine](https://github.com/pratikdas-vtu/nexus/blob/main/networking/relayEngine.ts): `networking/relayEngine.ts`
- [Wire Protocol](https://github.com/pratikdas-vtu/nexus/blob/main/shared/protocol.ts): `shared/protocol.ts`

### Peer Transports

- [Transport Manager](https://github.com/pratikdas-vtu/nexus/blob/main/networking/multiTransportManager.ts): `networking/multiTransportManager.ts`
- [Nearby Controller](https://github.com/pratikdas-vtu/nexus/blob/main/frontend/src/services/nearbyMeshController.ts): `frontend/src/services/nearbyMeshController.ts`
- [WebRTC Transport](https://github.com/pratikdas-vtu/nexus/blob/main/networking/webRtcTransport.ts): `networking/webRtcTransport.ts`
- [WebSocket Transport](https://github.com/pratikdas-vtu/nexus/blob/main/networking/webSocketTransport.ts): `networking/webSocketTransport.ts`
- [LAN Signaling](https://github.com/pratikdas-vtu/nexus/blob/main/networking/signalingClient.ts): `networking/signalingClient.ts`

### Native Radio

- [Native Bridge](https://github.com/pratikdas-vtu/nexus/blob/main/networking/nativeBridge.ts): `networking/nativeBridge.ts`
- [Android Plugin](https://github.com/pratikdas-vtu/nexus/blob/main/android/app/src/main/java/org/nexus/mesh/NexusNativePlugin.java): `android/app/src/main/java/org/nexus/mesh/NexusNativePlugin.java`

### Other components

- **Community / Responder**
- **Android Radios**
- **Nearby Peer Devices**
- **Gemini API**

## Connections

- Community / Responder → Application Shell: uses
- Application Shell → Field Views: renders
- Application Shell → Command Dashboard: opens
- Field Views → Service Context: reads services
- Command Dashboard → Service Context: manages incidents
- Service Context → Incident Service: creates and updates
- Incident Service → Validation Schema: validates
- Incident Service → Priority Rules: assigns priority
- Incident Service → Ingest Checks: ingests through
- Incident Service → Local Incident Store: persists
- Incident Service → Relay Outbox: queues
- Service Context → Incident Mapper: maps incidents
- Service Context → Network Coordinator: coordinates network
- Network Coordinator → Relay Engine: starts relay
- Network Coordinator → Transport Manager: manages connections
- Relay Engine → Transport Manager: uses transports
- Relay Engine → Wire Protocol: encodes messages
- Relay Engine → Relay Outbox: syncs queued reports
- Nearby Controller → Native Bridge: calls
- Nearby Controller → Transport Manager: registers connections
- Native Bridge → Android Plugin: bridges calls
- Android Plugin → Android Radios: discovers and connects
- Android Radios → Nearby Peer Devices: links devices
- Transport Manager → WebRTC Transport: selects transport
- Transport Manager → WebSocket Transport: selects transport
- LAN Signaling → Nearby Peer Devices: coordinates sessions
- Field Views → Gemini API: requests triage