# loicz/fieldlink architecture

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

- Interactive diagram: https://gitdiagram.com/loicz/fieldlink
- Repository: https://github.com/loicz/fieldlink

## Overview

FieldLink coordinates field reports between offline-capable team nodes, with local browser operation and synchronization when connectivity returns. The main workflow is an operator creating or updating a report in the browser; the UI calls the local daemon, which maintains durable report state and exchanges events with peers. The graph also preserves documented attachment transfer, offline maps, signed ZIP transfer, and optional radio/device integrations. Some daemon internals and integrations are unsampled, so their documented links are identified as such rather than inferred from module names.

Main entry points: [`src/runtime.cpp`](https://github.com/loicz/fieldlink/blob/main/src/runtime.cpp) (Daemon runtime), [`ui/src/App.svelte`](https://github.com/loicz/fieldlink/blob/main/ui/src/App.svelte) (Report console), [`adapters/common.py`](https://github.com/loicz/fieldlink/blob/main/adapters/common.py) (Local adapter API), [`adapters/radio.py`](https://github.com/loicz/fieldlink/blob/main/adapters/radio.py) (Meshtastic adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator interface"]
  node_ui["Report console<br/>[App.svelte]"]
  node_ui_model["Local API client<br/>[model.ts]"]
  node_map_view["Offline map view<br/>[Map.svelte]"]
  node_transfer["ZIP transfer<br/>[transfer.ts]"]
end

subgraph group_daemon["FieldLink daemon"]
  node_daemon["Daemon runtime<br/>[runtime.cpp]"]
  node_transport["Network transport<br/>[transport.cpp]"]
  node_resolver["Peer resolver<br/>[resolver.cpp]"]
  node_events["Signed events<br/>[event.cpp]"]
  node_store[("Report and blob store<br/>[store.cpp]")]
  node_executor["Bounded disk executor<br/>[runtime.hpp]"]
end

subgraph group_sync["Peer synchronization"]
  node_ip_sync["Mutual TLS sync<br/>[transport.cpp]"]
  node_map_pack["Map package tooling<br/>[map_pack.py]"]
end

subgraph group_integrations["Field integrations"]
  node_radio["Meshtastic adapter<br/>[radio.py]"]
  node_device["Device telemetry<br/>[devices.py]"]
  node_adapter_api["Local adapter API<br/>[common.py]"]
end

node_operator(("Field operator"))
node_peer(("Other FieldLink node"))
node_external_radio(("Meshtastic hardware"))

node_operator -->|"uses"| node_ui
node_ui -->|"calls"| node_ui_model
node_ui -->|"renders"| node_map_view
node_ui -->|"calls"| node_transfer
node_ui_model -->|"requests API"| node_daemon
node_daemon -.->|"reads and writes"| node_store
node_daemon -.->|"dispatches storage work"| node_executor
node_daemon -.->|"handles events"| node_events
node_daemon -.->|"serves through"| node_transport
node_transport -.->|"implements"| node_ip_sync
node_ip_sync -->|"synchronizes"| node_peer
node_daemon -.->|"resolves peers"| node_resolver
node_ui -.->|"uploads attachment chunks"| node_store
node_ui -.->|"uses installed maps"| node_map_pack
node_radio -->|"calls"| node_adapter_api
node_device -->|"calls"| node_adapter_api
node_adapter_api -.->|"calls local API"| node_daemon
node_radio -.->|"exchanges summaries"| node_external_radio

click node_ui "https://github.com/loicz/fieldlink/blob/main/ui/src/App.svelte"
click node_ui_model "https://github.com/loicz/fieldlink/blob/main/ui/src/model.ts"
click node_map_view "https://github.com/loicz/fieldlink/blob/main/ui/src/Map.svelte"
click node_transfer "https://github.com/loicz/fieldlink/blob/main/ui/src/transfer.ts"
click node_daemon "https://github.com/loicz/fieldlink/blob/main/src/runtime.cpp"
click node_transport "https://github.com/loicz/fieldlink/blob/main/src/transport.cpp"
click node_resolver "https://github.com/loicz/fieldlink/blob/main/src/resolver.cpp"
click node_events "https://github.com/loicz/fieldlink/blob/main/src/event.cpp"
click node_store "https://github.com/loicz/fieldlink/blob/main/src/store.cpp"
click node_executor "https://github.com/loicz/fieldlink/blob/main/include/fieldlink/runtime.hpp"
click node_ip_sync "https://github.com/loicz/fieldlink/blob/main/src/transport.cpp"
click node_map_pack "https://github.com/loicz/fieldlink/blob/main/tools/map_pack.py"
click node_radio "https://github.com/loicz/fieldlink/blob/main/adapters/radio.py"
click node_device "https://github.com/loicz/fieldlink/blob/main/adapters/devices.py"
click node_adapter_api "https://github.com/loicz/fieldlink/blob/main/adapters/common.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_ui_model,node_map_view,node_transfer toneBlue
class node_daemon,node_transport,node_resolver,node_events,node_store,node_executor toneAmber
class node_ip_sync,node_map_pack toneMint
class node_radio,node_device,node_adapter_api toneRose
class node_operator,node_peer,node_external_radio toneIndigo
```

## Components

### Operator interface

- [Report console](https://github.com/loicz/fieldlink/blob/main/ui/src/App.svelte): `ui/src/App.svelte`
- [Local API client](https://github.com/loicz/fieldlink/blob/main/ui/src/model.ts): `ui/src/model.ts`
- [Offline map view](https://github.com/loicz/fieldlink/blob/main/ui/src/Map.svelte): `ui/src/Map.svelte`
- [ZIP transfer](https://github.com/loicz/fieldlink/blob/main/ui/src/transfer.ts): `ui/src/transfer.ts`

### FieldLink daemon

- [Daemon runtime](https://github.com/loicz/fieldlink/blob/main/src/runtime.cpp): `src/runtime.cpp`
- [Network transport](https://github.com/loicz/fieldlink/blob/main/src/transport.cpp): `src/transport.cpp`
- [Peer resolver](https://github.com/loicz/fieldlink/blob/main/src/resolver.cpp): `src/resolver.cpp`
- [Signed events](https://github.com/loicz/fieldlink/blob/main/src/event.cpp): `src/event.cpp`
- [Report and blob store](https://github.com/loicz/fieldlink/blob/main/src/store.cpp): `src/store.cpp`
- [Bounded disk executor](https://github.com/loicz/fieldlink/blob/main/include/fieldlink/runtime.hpp): `include/fieldlink/runtime.hpp`

### Peer synchronization

- [Mutual TLS sync](https://github.com/loicz/fieldlink/blob/main/src/transport.cpp): `src/transport.cpp`
- [Map package tooling](https://github.com/loicz/fieldlink/blob/main/tools/map_pack.py): `tools/map_pack.py`

### Field integrations

- [Meshtastic adapter](https://github.com/loicz/fieldlink/blob/main/adapters/radio.py): `adapters/radio.py`
- [Device telemetry](https://github.com/loicz/fieldlink/blob/main/adapters/devices.py): `adapters/devices.py`
- [Local adapter API](https://github.com/loicz/fieldlink/blob/main/adapters/common.py): `adapters/common.py`

### Other components

- **Field operator**
- **Other FieldLink node**
- **Meshtastic hardware**

## Connections

- Field operator → Report console: uses (evidence: `README.md`)
- Report console → Local API client: calls (evidence: `ui/src/App.svelte`)
- Report console → Offline map view: renders (evidence: `ui/src/App.svelte`)
- Report console → ZIP transfer: calls (evidence: `ui/src/App.svelte`)
- Local API client → Daemon runtime: requests API (evidence: `ui/src/model.ts`)
- Daemon runtime → Report and blob store: reads and writes
- Daemon runtime → Bounded disk executor: dispatches storage work (evidence: `src/runtime.cpp`)
- Daemon runtime → Signed events: handles events
- Daemon runtime → Network transport: serves through
- Network transport → Mutual TLS sync: implements (evidence: `src/transport.cpp`)
- Mutual TLS sync → Other FieldLink node: synchronizes (evidence: `README.md`)
- Daemon runtime → Peer resolver: resolves peers
- Report console → Report and blob store: uploads attachment chunks
- Report console → Map package tooling: uses installed maps
- Meshtastic adapter → Local adapter API: calls (evidence: `adapters/radio.py`)
- Device telemetry → Local adapter API: calls (evidence: `adapters/devices.py`)
- Local adapter API → Daemon runtime: calls local API
- Meshtastic adapter → Meshtastic hardware: exchanges summaries (evidence: `README.md`)
