# roadtrace/kmtrack architecture

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

- Interactive diagram: https://gitdiagram.com/roadtrace/kmtrack
- Repository: https://github.com/roadtrace/kmtrack

## Overview

SPOT IT is an offline-first road-inspection application: an inspector records and reviews inspections locally, then eligible records can be reconciled and submitted to the cloud. Separate branches support guest-to-account claiming, sharing/import-export, mapping and location, and an explicit photo-attachment pilot. The excerpts show important module dependencies and cloud operations; the tree and source index identify other product areas, but their internal wiring is not established here.

Main entry points: [`guest-claim.js`](https://github.com/roadtrace/kmtrack/blob/main/guest-claim.js) (Guest claiming), [`entry-model.js`](https://github.com/roadtrace/kmtrack/blob/main/entry-model.js) (Inspection records), [`inspection-api.js`](https://github.com/roadtrace/kmtrack/blob/main/inspection-api.js) (Inspection API), [`photo-sync.js`](https://github.com/roadtrace/kmtrack/blob/main/photo-sync.js) (Photo sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Inspection workflow"]
  node_entry["Inspection records<br/>[entry-model.js]"]
  node_local[("Local persistence")]
  node_review["Submission review"]
end

subgraph group_sync["Account and sync"]
  node_auth["Authentication<br/>[auth.js]"]
  node_authconfig["Auth configuration<br/>[auth-config.js]"]
  node_claim["Guest claiming<br/>[guest-claim.js]"]
  node_queue["Eligibility queue<br/>[sync-queue.js]"]
  node_runner["Sync runner<br/>[sync-runner.js]"]
  node_api["Inspection API<br/>[inspection-api.js]"]
end

subgraph group_photos["Photo evidence"]
  node_photo_state["Photo preparation"]
  node_photo_sync["Photo sync<br/>[photo-sync.js]"]
  node_photo_api["Photo cloud API<br/>[photo-cloud-api.js]"]
  node_photo_pilot["Photo viewing pilot<br/>[photo-pilot.js]"]
end

subgraph group_field["Field tools"]
  node_location["Location resolution"]
  node_map["Map configuration<br/>[map-config.js]"]
  node_overlays["Map overlays<br/>[map-overlays.js]"]
  node_logs["Inspection log controls<br/>[log-controls.js]"]
end

subgraph group_sharing["Sharing and export"]
  node_sharing["Sharing and workbook exchange"]
  node_sharing_ui["Sharing interface<br/>[sharing-ui.js]"]
end

node_inspector(("Inspector"))
node_cloud[("Cloud inspection service")]

node_entry -->|"normalizes with"| node_photo_state
node_claim -->|"checks eligibility"| node_queue
node_claim -->|"creates copies with"| node_entry
node_claim -->|"persists claims with"| node_local
node_claim -->|"uses review scope"| node_review
node_review -->|"checks eligibility"| node_queue
node_runner -->|"selects eligible records"| node_queue
node_runner -->|"reconciles submissions"| node_api
node_api -->|"inserts inspections"| node_cloud
node_photo_pilot -->|"checks photo state"| node_photo_state
node_photo_pilot -->|"uses inspection API"| node_api
node_photo_sync -->|"validates photo state"| node_photo_state
node_photo_sync -->|"dispatches photo operations"| node_photo_api
node_photo_sync -->|"uses inspection API"| node_api
node_photo_api -->|"reads inspection rows"| node_cloud
node_sharing -->|"reuses entry model"| node_entry
node_inspector -.->|"records inspections"| node_entry

click node_entry "https://github.com/roadtrace/kmtrack/blob/main/entry-model.js"
click node_local "https://github.com/roadtrace/kmtrack/blob/main/local-entry-store.js"
click node_review "https://github.com/roadtrace/kmtrack/blob/main/preapproval-review.js"
click node_auth "https://github.com/roadtrace/kmtrack/blob/main/auth.js"
click node_authconfig "https://github.com/roadtrace/kmtrack/blob/main/auth-config.js"
click node_claim "https://github.com/roadtrace/kmtrack/blob/main/guest-claim.js"
click node_queue "https://github.com/roadtrace/kmtrack/blob/main/sync-queue.js"
click node_runner "https://github.com/roadtrace/kmtrack/blob/main/sync-runner.js"
click node_api "https://github.com/roadtrace/kmtrack/blob/main/inspection-api.js"
click node_photo_state "https://github.com/roadtrace/kmtrack/blob/main/photo-upload-state.js"
click node_photo_sync "https://github.com/roadtrace/kmtrack/blob/main/photo-sync.js"
click node_photo_api "https://github.com/roadtrace/kmtrack/blob/main/photo-cloud-api.js"
click node_photo_pilot "https://github.com/roadtrace/kmtrack/blob/main/photo-pilot.js"
click node_sharing "https://github.com/roadtrace/kmtrack/blob/main/inspection-sharing.js"
click node_sharing_ui "https://github.com/roadtrace/kmtrack/blob/main/sharing-ui.js"
click node_location "https://github.com/roadtrace/kmtrack/blob/main/location-resolver.js"
click node_map "https://github.com/roadtrace/kmtrack/blob/main/map-config.js"
click node_overlays "https://github.com/roadtrace/kmtrack/blob/main/map-overlays.js"
click node_logs "https://github.com/roadtrace/kmtrack/blob/main/log-controls.js"

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_entry,node_local,node_review toneBlue
class node_auth,node_authconfig,node_claim,node_queue,node_runner,node_api,node_cloud toneAmber
class node_photo_state,node_photo_sync,node_photo_api,node_photo_pilot toneMint
class node_location,node_map,node_overlays,node_logs toneRose
class node_sharing,node_sharing_ui,node_inspector toneIndigo
```

## Components

### Inspection workflow

- [Inspection records](https://github.com/roadtrace/kmtrack/blob/main/entry-model.js): `entry-model.js`
- [Local persistence](https://github.com/roadtrace/kmtrack/blob/main/local-entry-store.js): `local-entry-store.js`
- [Submission review](https://github.com/roadtrace/kmtrack/blob/main/preapproval-review.js): `preapproval-review.js`

### Account and sync

- [Authentication](https://github.com/roadtrace/kmtrack/blob/main/auth.js): `auth.js`
- [Auth configuration](https://github.com/roadtrace/kmtrack/blob/main/auth-config.js): `auth-config.js`
- [Guest claiming](https://github.com/roadtrace/kmtrack/blob/main/guest-claim.js): `guest-claim.js`
- [Eligibility queue](https://github.com/roadtrace/kmtrack/blob/main/sync-queue.js): `sync-queue.js`
- [Sync runner](https://github.com/roadtrace/kmtrack/blob/main/sync-runner.js): `sync-runner.js`
- [Inspection API](https://github.com/roadtrace/kmtrack/blob/main/inspection-api.js): `inspection-api.js`

### Photo evidence

- [Photo preparation](https://github.com/roadtrace/kmtrack/blob/main/photo-upload-state.js): `photo-upload-state.js`
- [Photo sync](https://github.com/roadtrace/kmtrack/blob/main/photo-sync.js): `photo-sync.js`
- [Photo cloud API](https://github.com/roadtrace/kmtrack/blob/main/photo-cloud-api.js): `photo-cloud-api.js`
- [Photo viewing pilot](https://github.com/roadtrace/kmtrack/blob/main/photo-pilot.js): `photo-pilot.js`

### Field tools

- [Location resolution](https://github.com/roadtrace/kmtrack/blob/main/location-resolver.js): `location-resolver.js`
- [Map configuration](https://github.com/roadtrace/kmtrack/blob/main/map-config.js): `map-config.js`
- [Map overlays](https://github.com/roadtrace/kmtrack/blob/main/map-overlays.js): `map-overlays.js`
- [Inspection log controls](https://github.com/roadtrace/kmtrack/blob/main/log-controls.js): `log-controls.js`

### Sharing and export

- [Sharing and workbook exchange](https://github.com/roadtrace/kmtrack/blob/main/inspection-sharing.js): `inspection-sharing.js`
- [Sharing interface](https://github.com/roadtrace/kmtrack/blob/main/sharing-ui.js): `sharing-ui.js`

### Other components

- **Inspector**
- **Cloud inspection service**

## Connections

- Inspection records → Photo preparation: normalizes with (evidence: `entry-model.js`)
- Guest claiming → Eligibility queue: checks eligibility (evidence: `guest-claim.js`)
- Guest claiming → Inspection records: creates copies with (evidence: `guest-claim.js`)
- Guest claiming → Local persistence: persists claims with (evidence: `guest-claim.js`)
- Guest claiming → Submission review: uses review scope (evidence: `guest-claim.js`)
- Submission review → Eligibility queue: checks eligibility (evidence: `preapproval-review.js`)
- Sync runner → Eligibility queue: selects eligible records (evidence: `sync-runner.js`)
- Sync runner → Inspection API: reconciles submissions (evidence: `sync-runner.js`)
- Inspection API → Cloud inspection service: inserts inspections (evidence: `inspection-api.js`)
- Photo viewing pilot → Photo preparation: checks photo state (evidence: `photo-pilot.js`)
- Photo viewing pilot → Inspection API: uses inspection API (evidence: `photo-pilot.js`)
- Photo sync → Photo preparation: validates photo state (evidence: `photo-sync.js`)
- Photo sync → Photo cloud API: dispatches photo operations (evidence: `photo-sync.js`)
- Photo sync → Inspection API: uses inspection API (evidence: `photo-sync.js`)
- Photo cloud API → Cloud inspection service: reads inspection rows (evidence: `photo-cloud-api.js`)
- Sharing and workbook exchange → Inspection records: reuses entry model (evidence: `inspection-sharing.js`)
- Inspector → Inspection records: records inspections
