# adicodeswell/blackout architecture

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

- Interactive diagram: https://gitdiagram.com/adicodeswell/blackout
- Repository: https://github.com/adicodeswell/blackout

## Overview

This repository is a React Native emergency-response app with offline geolocation and an Android peer-to-peer mesh implementation. The intended workflow is to enter through the app, use location and offline-map routing to orient response, and exchange emergency messages with nearby peers; the contracts also define incident, evidence, resource, and AI capabilities. The README is only the stock React Native setup guide, so product behavior is inferred from source and contracts. Some native and data subsystems are unsampled; their links are omitted or marked unverified.

Main entry points: [`android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java`](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java) (Offline geo engine), [`android/app/src/main/java/com/blackout/network/engine/AndroidNetworkEngine.java`](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/engine/AndroidNetworkEngine.java) (Android network engine), [`android/app/src/main/java/com/blackout/network/transport/ConnectionManager.java`](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/ConnectionManager.java) (Connection manager), [`android/app/src/main/java/com/blackout/network/transport/OutgoingSendManager.java`](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/OutgoingSendManager.java) (Outgoing sends)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and bridges"]
  node_app["React Native app<br/>[App.tsx]"]
  node_native_adapter["Native bridge adapter"]
  node_native_bridge["Blackout native module"]
end

subgraph group_geo["Offline geolocation"]
  node_geo_adapter["Geo adapter"]
  node_geo_engine["Offline geo engine"]
  node_location["Location provider and validation"]
  node_offline_maps["Offline map loading"]
  node_map_sources[("Map sources and cache")]
  node_hazards["Hazard projection"]
  node_road_graph["Road graph<br/>[RoadGraph.java]"]
  node_router["A-star routing<br/>[AStarRouter.java]"]
  node_nearby["Nearby search<br/>[NearbySearch.java]"]
end

subgraph group_mesh["Peer mesh networking"]
  node_network_adapter["Network adapter"]
  node_network_engine["Android network engine"]
  node_discovery["Peer discovery"]
  node_connection_manager["Connection manager"]
  node_peer_connection["Peer connections"]
  node_network_server["Network server<br/>[NetworkServer.java]"]
  node_outgoing["Outgoing sends"]
  node_protocol["Message protocol"]
  node_handshake["Peer handshake"]
  node_reliability["Delivery and forwarding"]
  node_mesh_service["Mesh foreground service"]
end

subgraph group_response["Response data and AI"]
  node_data_adapter["Data engine adapter"]
  node_data_contract["Reports, incidents, resources<br/>[DataEngine.ts]"]
  node_ai_adapter["AI engine adapter<br/>[AIEngineAdapter.ts]"]
  node_ai_contract["AI contracts<br/>[AIEngine.ts]"]
end

node_user(("App user"))

node_user -->|"uses"| node_app
node_app -->|"imports"| node_native_adapter
node_native_adapter -.->|"bridges to"| node_native_bridge
node_geo_adapter -.->|"delegates to"| node_geo_engine
node_geo_engine -.->|"reads location"| node_location
node_geo_engine -->|"loads maps"| node_offline_maps
node_offline_maps -->|"loads from"| node_map_sources
node_geo_engine -->|"projects hazards"| node_hazards
node_geo_engine -->|"routes on"| node_road_graph
node_geo_engine -->|"calculates route"| node_router
node_geo_engine -.->|"searches nearby"| node_nearby
node_network_adapter -.->|"delegates to"| node_network_engine
node_network_engine -->|"discovers peers"| node_discovery
node_network_engine -->|"manages connections"| node_connection_manager
node_network_engine -->|"uses server"| node_network_server
node_connection_manager -->|"starts and sends"| node_peer_connection
node_outgoing -->|"sends through"| node_connection_manager
node_outgoing -->|"serializes"| node_protocol
node_handshake -->|"uses connections"| node_connection_manager
node_handshake -->|"exchanges messages"| node_protocol
node_reliability -->|"forwards messages"| node_outgoing
node_mesh_service -.->|"starts mesh"| node_network_engine
node_data_adapter -->|"implements contract"| node_data_contract
node_ai_adapter -->|"implements contract"| node_ai_contract

click node_app "https://github.com/adicodeswell/blackout/blob/main/App.tsx"
click node_native_adapter "https://github.com/adicodeswell/blackout/blob/main/src/adapters/native/NativeBridgeAdapter.ts"
click node_native_bridge "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/bridge/BlackoutNativeModule.java"
click node_geo_adapter "https://github.com/adicodeswell/blackout/blob/main/src/adapters/geo/GeoEngineAdapter.ts"
click node_geo_engine "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java"
click node_location "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/AndroidLocationProvider.java"
click node_offline_maps "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/OfflineMapManager.java"
click node_map_sources "https://github.com/adicodeswell/blackout/tree/main/android/app/src/main/java/com/blackout/geolocation/source"
click node_hazards "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/HazardProjector.java"
click node_road_graph "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/RoadGraph.java"
click node_router "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/AStarRouter.java"
click node_nearby "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/NearbySearch.java"
click node_network_adapter "https://github.com/adicodeswell/blackout/blob/main/src/adapters/network/NetworkEngineAdapter.ts"
click node_network_engine "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/engine/AndroidNetworkEngine.java"
click node_discovery "https://github.com/adicodeswell/blackout/tree/main/android/app/src/main/java/com/blackout/network/discovery"
click node_connection_manager "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/ConnectionManager.java"
click node_peer_connection "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/PeerConnection.java"
click node_network_server "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/NetworkServer.java"
click node_outgoing "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/OutgoingSendManager.java"
click node_protocol "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/protocol/NetworkMessage.java"
click node_handshake "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/protocol/HandshakeManager.java"
click node_reliability "https://github.com/adicodeswell/blackout/tree/main/android/app/src/main/java/com/blackout/network/reliability"
click node_mesh_service "https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/service/MeshForegroundService.java"
click node_data_adapter "https://github.com/adicodeswell/blackout/blob/main/src/adapters/data/DataEngineAdapter.ts"
click node_data_contract "https://github.com/adicodeswell/blackout/blob/main/src/contracts/data/DataEngine.ts"
click node_ai_adapter "https://github.com/adicodeswell/blackout/blob/main/src/adapters/ai/AIEngineAdapter.ts"
click node_ai_contract "https://github.com/adicodeswell/blackout/blob/main/src/contracts/ai/AIEngine.ts"

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_native_adapter,node_native_bridge,node_user toneBlue
class node_geo_adapter,node_geo_engine,node_location,node_offline_maps,node_map_sources,node_hazards,node_road_graph,node_router,node_nearby toneAmber
class node_network_adapter,node_network_engine,node_discovery,node_connection_manager,node_peer_connection,node_network_server,node_outgoing,node_protocol,node_handshake,node_reliability,node_mesh_service toneMint
class node_data_adapter,node_data_contract,node_ai_adapter,node_ai_contract toneRose
```

## Components

### App and bridges

- [React Native app](https://github.com/adicodeswell/blackout/blob/main/App.tsx): `App.tsx`
- [Native bridge adapter](https://github.com/adicodeswell/blackout/blob/main/src/adapters/native/NativeBridgeAdapter.ts): `src/adapters/native/NativeBridgeAdapter.ts`
- [Blackout native module](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/bridge/BlackoutNativeModule.java): `android/app/src/main/java/com/blackout/bridge/BlackoutNativeModule.java`

### Offline geolocation

- [Geo adapter](https://github.com/adicodeswell/blackout/blob/main/src/adapters/geo/GeoEngineAdapter.ts): `src/adapters/geo/GeoEngineAdapter.ts`
- [Offline geo engine](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java): `android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java`
- [Location provider and validation](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/AndroidLocationProvider.java): `android/app/src/main/java/com/blackout/geolocation/AndroidLocationProvider.java`
- [Offline map loading](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/OfflineMapManager.java): `android/app/src/main/java/com/blackout/geolocation/OfflineMapManager.java`
- [Map sources and cache](https://github.com/adicodeswell/blackout/tree/main/android/app/src/main/java/com/blackout/geolocation/source): `android/app/src/main/java/com/blackout/geolocation/source`
- [Hazard projection](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/HazardProjector.java): `android/app/src/main/java/com/blackout/geolocation/HazardProjector.java`
- [Road graph](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/RoadGraph.java): `android/app/src/main/java/com/blackout/geolocation/RoadGraph.java`
- [A-star routing](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/AStarRouter.java): `android/app/src/main/java/com/blackout/geolocation/AStarRouter.java`
- [Nearby search](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/geolocation/NearbySearch.java): `android/app/src/main/java/com/blackout/geolocation/NearbySearch.java`

### Peer mesh networking

- [Network adapter](https://github.com/adicodeswell/blackout/blob/main/src/adapters/network/NetworkEngineAdapter.ts): `src/adapters/network/NetworkEngineAdapter.ts`
- [Android network engine](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/engine/AndroidNetworkEngine.java): `android/app/src/main/java/com/blackout/network/engine/AndroidNetworkEngine.java`
- [Peer discovery](https://github.com/adicodeswell/blackout/tree/main/android/app/src/main/java/com/blackout/network/discovery): `android/app/src/main/java/com/blackout/network/discovery`
- [Connection manager](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/ConnectionManager.java): `android/app/src/main/java/com/blackout/network/transport/ConnectionManager.java`
- [Peer connections](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/PeerConnection.java): `android/app/src/main/java/com/blackout/network/transport/PeerConnection.java`
- [Network server](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/NetworkServer.java): `android/app/src/main/java/com/blackout/network/transport/NetworkServer.java`
- [Outgoing sends](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/transport/OutgoingSendManager.java): `android/app/src/main/java/com/blackout/network/transport/OutgoingSendManager.java`
- [Message protocol](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/protocol/NetworkMessage.java): `android/app/src/main/java/com/blackout/network/protocol/NetworkMessage.java`
- [Peer handshake](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/protocol/HandshakeManager.java): `android/app/src/main/java/com/blackout/network/protocol/HandshakeManager.java`
- [Delivery and forwarding](https://github.com/adicodeswell/blackout/tree/main/android/app/src/main/java/com/blackout/network/reliability): `android/app/src/main/java/com/blackout/network/reliability`
- [Mesh foreground service](https://github.com/adicodeswell/blackout/blob/main/android/app/src/main/java/com/blackout/network/service/MeshForegroundService.java): `android/app/src/main/java/com/blackout/network/service/MeshForegroundService.java`

### Response data and AI

- [Data engine adapter](https://github.com/adicodeswell/blackout/blob/main/src/adapters/data/DataEngineAdapter.ts): `src/adapters/data/DataEngineAdapter.ts`
- [Reports, incidents, resources](https://github.com/adicodeswell/blackout/blob/main/src/contracts/data/DataEngine.ts): `src/contracts/data/DataEngine.ts`
- [AI engine adapter](https://github.com/adicodeswell/blackout/blob/main/src/adapters/ai/AIEngineAdapter.ts): `src/adapters/ai/AIEngineAdapter.ts`
- [AI contracts](https://github.com/adicodeswell/blackout/blob/main/src/contracts/ai/AIEngine.ts): `src/contracts/ai/AIEngine.ts`

### Other components

- **App user**

## Connections

- App user → React Native app: uses (evidence: `App.tsx`)
- React Native app → Native bridge adapter: imports (evidence: `App.tsx`)
- Native bridge adapter → Blackout native module: bridges to
- Geo adapter → Offline geo engine: delegates to
- Offline geo engine → Location provider and validation: reads location (evidence: `android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java`)
- Offline geo engine → Offline map loading: loads maps (evidence: `android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java`)
- Offline map loading → Map sources and cache: loads from (evidence: `android/app/src/main/java/com/blackout/geolocation/OfflineMapManager.java`)
- Offline geo engine → Hazard projection: projects hazards (evidence: `android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java`)
- Offline geo engine → Road graph: routes on (evidence: `android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java`)
- Offline geo engine → A-star routing: calculates route (evidence: `android/app/src/main/java/com/blackout/geolocation/OfflineGeoEngine.java`)
- Offline geo engine → Nearby search: searches nearby
- Network adapter → Android network engine: delegates to
- Android network engine → Peer discovery: discovers peers (evidence: `android/app/src/main/java/com/blackout/network/engine/AndroidNetworkEngine.java`)
- Android network engine → Connection manager: manages connections (evidence: `android/app/src/main/java/com/blackout/network/engine/AndroidNetworkEngine.java`)
- Android network engine → Network server: uses server (evidence: `android/app/src/main/java/com/blackout/network/engine/AndroidNetworkEngine.java`)
- Connection manager → Peer connections: starts and sends (evidence: `android/app/src/main/java/com/blackout/network/transport/ConnectionManager.java`)
- Outgoing sends → Connection manager: sends through (evidence: `android/app/src/main/java/com/blackout/network/transport/OutgoingSendManager.java`)
- Outgoing sends → Message protocol: serializes (evidence: `android/app/src/main/java/com/blackout/network/transport/OutgoingSendManager.java`)
- Peer handshake → Connection manager: uses connections (evidence: `android/app/src/main/java/com/blackout/network/protocol/HandshakeManager.java`)
- Peer handshake → Message protocol: exchanges messages (evidence: `android/app/src/main/java/com/blackout/network/protocol/HandshakeManager.java`)
- Delivery and forwarding → Outgoing sends: forwards messages (evidence: `android/app/src/main/java/com/blackout/network/reliability/ForwardingEngine.java`)
- Mesh foreground service → Android network engine: starts mesh
- Data engine adapter → Reports, incidents, resources: implements contract (evidence: `src/adapters/data/DataEngineAdapter.ts`)
- AI engine adapter → AI contracts: implements contract (evidence: `src/adapters/ai/AIEngineAdapter.ts`)
