# xhowu/localscan architecture

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

- Interactive diagram: https://gitdiagram.com/xhowu/localscan
- Repository: https://github.com/xhowu/localscan

## Overview

LocalScan is a privacy-first inventory and item-management app whose default data stays on-device. The main workflow is scanning or entering item details, editing a draft, then saving and managing inventory. The graph focuses on the active app source under app/; v1.10.0 is documented as its archived source snapshot, so it is not duplicated here. Unsampled page and service responsibilities are included where established by the tree and README; edges are limited to relationships visible in excerpts or the source index.

Main entry points: [`app/src/App.tsx`](https://github.com/xhowu/localscan/blob/main/app/src/App.tsx) (App shell), [`app/src/pages/ScanPage.tsx`](https://github.com/xhowu/localscan/blob/main/app/src/pages/ScanPage.tsx) (Scan page), [`app/src/db.ts`](https://github.com/xhowu/localscan/blob/main/app/src/db.ts) (Local inventory store), [`app/src/pages/EditItemPage.tsx`](https://github.com/xhowu/localscan/blob/main/app/src/pages/EditItemPage.tsx) (Item editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App navigation"]
  node_app["App shell<br/>[App.tsx]"]
  node_router["Hash router<br/>[router.ts]"]
end

subgraph group_inventory["Inventory management"]
  node_items["Inventory list<br/>[ItemsPage.tsx]"]
  node_detail["Item detail<br/>[ItemDetailPage.tsx]"]
  node_editor["Item editor<br/>[EditItemPage.tsx]"]
  node_recycle["Recycle bin<br/>[RecycleBinPage.tsx]"]
  node_database[("Local inventory store<br/>[db.ts]")]
end

subgraph group_capture["Item capture"]
  node_scan["Scan page<br/>[ScanPage.tsx]"]
  node_native_scan["Native scan bridge<br/>[native-scan.ts]"]
  node_camera["Camera overlay<br/>[camera-overlay.ts]"]
  node_scanner_plugin["Android scanner plugin"]
  node_scanner_activity["Scanner activity"]
  node_ocr["Label OCR<br/>[ocr.ts]"]
  node_label_parser["Label parser<br/>[label-parse.ts]"]
  node_draft["Capture draft<br/>[draft.ts]"]
  node_barcode_lookup["Barcode lookup<br/>[barcode-lookup.ts]"]
end

subgraph group_support["Data and settings"]
  node_sync["Data sync<br/>[SyncPage.tsx]"]
  node_sync_service["Sync service<br/>[sync.ts]"]
  node_export["Data export<br/>[export.ts]"]
  node_settings["Settings<br/>[SettingsPage.tsx]"]
  node_taxonomy["Categories and locations<br/>[TaxonomyPage.tsx]"]
  node_templates["Field templates"]
  node_manual["User manual<br/>[ManualPage.tsx]"]
end

node_user(("Local user"))

node_user -->|"uses"| node_app
node_app -->|"parses routes"| node_router
node_app -->|"renders"| node_items
node_app -->|"renders"| node_scan
node_app -->|"renders"| node_detail
node_app -->|"renders"| node_editor
node_app -->|"renders"| node_sync
node_app -->|"renders"| node_settings
node_scan -->|"requests permission"| node_native_scan
node_scan -->|"controls overlay"| node_camera
node_scanner_plugin -->|"launches"| node_scanner_activity
node_scan -->|"runs OCR"| node_ocr
node_scan -->|"parses OCR"| node_label_parser
node_scan -->|"creates draft"| node_draft
node_scan -->|"navigates to"| node_editor
node_editor -->|"reads and saves"| node_database
node_editor -->|"reads draft"| node_draft
node_items -.->|"loads inventory"| node_database
node_detail -.->|"loads item"| node_database
node_recycle -.->|"manages deleted items"| node_database
node_sync -.->|"uses sync"| node_sync_service
node_sync -.->|"exports data"| node_export
node_settings -.->|"configures local data"| node_database
node_taxonomy -.->|"manages taxonomy"| node_database
node_templates -.->|"manages templates"| node_database
node_scan -->|"looks up barcode"| node_barcode_lookup
node_app -.->|"renders manual"| node_manual

click node_app "https://github.com/xhowu/localscan/blob/main/app/src/App.tsx"
click node_router "https://github.com/xhowu/localscan/blob/main/app/src/router.ts"
click node_items "https://github.com/xhowu/localscan/blob/main/app/src/pages/ItemsPage.tsx"
click node_detail "https://github.com/xhowu/localscan/blob/main/app/src/pages/ItemDetailPage.tsx"
click node_editor "https://github.com/xhowu/localscan/blob/main/app/src/pages/EditItemPage.tsx"
click node_recycle "https://github.com/xhowu/localscan/blob/main/app/src/pages/RecycleBinPage.tsx"
click node_scan "https://github.com/xhowu/localscan/blob/main/app/src/pages/ScanPage.tsx"
click node_native_scan "https://github.com/xhowu/localscan/blob/main/app/src/lib/native-scan.ts"
click node_camera "https://github.com/xhowu/localscan/blob/main/app/src/lib/camera-overlay.ts"
click node_scanner_plugin "https://github.com/xhowu/localscan/blob/main/app/android/app/src/main/java/com/localscan/app/LocalscanScannerPlugin.java"
click node_scanner_activity "https://github.com/xhowu/localscan/blob/main/app/android/app/src/main/java/com/localscan/app/ScannerActivity.java"
click node_ocr "https://github.com/xhowu/localscan/blob/main/app/src/services/ocr.ts"
click node_label_parser "https://github.com/xhowu/localscan/blob/main/app/src/lib/label-parse.ts"
click node_draft "https://github.com/xhowu/localscan/blob/main/app/src/lib/draft.ts"
click node_database "https://github.com/xhowu/localscan/blob/main/app/src/db.ts"
click node_sync "https://github.com/xhowu/localscan/blob/main/app/src/pages/SyncPage.tsx"
click node_sync_service "https://github.com/xhowu/localscan/blob/main/app/src/services/sync.ts"
click node_export "https://github.com/xhowu/localscan/blob/main/app/src/services/export.ts"
click node_settings "https://github.com/xhowu/localscan/blob/main/app/src/pages/SettingsPage.tsx"
click node_taxonomy "https://github.com/xhowu/localscan/blob/main/app/src/pages/TaxonomyPage.tsx"
click node_templates "https://github.com/xhowu/localscan/blob/main/app/src/pages/FieldTemplatesPage.tsx"
click node_manual "https://github.com/xhowu/localscan/blob/main/app/src/pages/ManualPage.tsx"
click node_barcode_lookup "https://github.com/xhowu/localscan/blob/main/app/src/services/barcode-lookup.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_router,node_user toneBlue
class node_items,node_detail,node_editor,node_recycle,node_database toneAmber
class node_scan,node_native_scan,node_camera,node_scanner_plugin,node_scanner_activity,node_ocr,node_label_parser,node_draft,node_barcode_lookup toneMint
class node_sync,node_sync_service,node_export,node_settings,node_taxonomy,node_templates,node_manual toneRose
```

## Components

### App navigation

- [App shell](https://github.com/xhowu/localscan/blob/main/app/src/App.tsx): `app/src/App.tsx`
- [Hash router](https://github.com/xhowu/localscan/blob/main/app/src/router.ts): `app/src/router.ts`

### Inventory management

- [Inventory list](https://github.com/xhowu/localscan/blob/main/app/src/pages/ItemsPage.tsx): `app/src/pages/ItemsPage.tsx`
- [Item detail](https://github.com/xhowu/localscan/blob/main/app/src/pages/ItemDetailPage.tsx): `app/src/pages/ItemDetailPage.tsx`
- [Item editor](https://github.com/xhowu/localscan/blob/main/app/src/pages/EditItemPage.tsx): `app/src/pages/EditItemPage.tsx`
- [Recycle bin](https://github.com/xhowu/localscan/blob/main/app/src/pages/RecycleBinPage.tsx): `app/src/pages/RecycleBinPage.tsx`
- [Local inventory store](https://github.com/xhowu/localscan/blob/main/app/src/db.ts): `app/src/db.ts`

### Item capture

- [Scan page](https://github.com/xhowu/localscan/blob/main/app/src/pages/ScanPage.tsx): `app/src/pages/ScanPage.tsx`
- [Native scan bridge](https://github.com/xhowu/localscan/blob/main/app/src/lib/native-scan.ts): `app/src/lib/native-scan.ts`
- [Camera overlay](https://github.com/xhowu/localscan/blob/main/app/src/lib/camera-overlay.ts): `app/src/lib/camera-overlay.ts`
- [Android scanner plugin](https://github.com/xhowu/localscan/blob/main/app/android/app/src/main/java/com/localscan/app/LocalscanScannerPlugin.java): `app/android/app/src/main/java/com/localscan/app/LocalscanScannerPlugin.java`
- [Scanner activity](https://github.com/xhowu/localscan/blob/main/app/android/app/src/main/java/com/localscan/app/ScannerActivity.java): `app/android/app/src/main/java/com/localscan/app/ScannerActivity.java`
- [Label OCR](https://github.com/xhowu/localscan/blob/main/app/src/services/ocr.ts): `app/src/services/ocr.ts`
- [Label parser](https://github.com/xhowu/localscan/blob/main/app/src/lib/label-parse.ts): `app/src/lib/label-parse.ts`
- [Capture draft](https://github.com/xhowu/localscan/blob/main/app/src/lib/draft.ts): `app/src/lib/draft.ts`
- [Barcode lookup](https://github.com/xhowu/localscan/blob/main/app/src/services/barcode-lookup.ts): `app/src/services/barcode-lookup.ts`

### Data and settings

- [Data sync](https://github.com/xhowu/localscan/blob/main/app/src/pages/SyncPage.tsx): `app/src/pages/SyncPage.tsx`
- [Sync service](https://github.com/xhowu/localscan/blob/main/app/src/services/sync.ts): `app/src/services/sync.ts`
- [Data export](https://github.com/xhowu/localscan/blob/main/app/src/services/export.ts): `app/src/services/export.ts`
- [Settings](https://github.com/xhowu/localscan/blob/main/app/src/pages/SettingsPage.tsx): `app/src/pages/SettingsPage.tsx`
- [Categories and locations](https://github.com/xhowu/localscan/blob/main/app/src/pages/TaxonomyPage.tsx): `app/src/pages/TaxonomyPage.tsx`
- [Field templates](https://github.com/xhowu/localscan/blob/main/app/src/pages/FieldTemplatesPage.tsx): `app/src/pages/FieldTemplatesPage.tsx`
- [User manual](https://github.com/xhowu/localscan/blob/main/app/src/pages/ManualPage.tsx): `app/src/pages/ManualPage.tsx`

### Other components

- **Local user**

## Connections

- Local user → App shell: uses (evidence: `README.md`)
- App shell → Hash router: parses routes (evidence: `app/src/App.tsx`)
- App shell → Inventory list: renders (evidence: `app/src/App.tsx`)
- App shell → Scan page: renders (evidence: `app/src/App.tsx`)
- App shell → Item detail: renders (evidence: `app/src/App.tsx`)
- App shell → Item editor: renders (evidence: `app/src/App.tsx`)
- App shell → Data sync: renders (evidence: `app/src/App.tsx`)
- App shell → Settings: renders (evidence: `app/src/App.tsx`)
- Scan page → Native scan bridge: requests permission (evidence: `app/src/pages/ScanPage.tsx`)
- Scan page → Camera overlay: controls overlay (evidence: `app/src/pages/ScanPage.tsx`)
- Android scanner plugin → Scanner activity: launches (evidence: `app/android/app/src/main/java/com/localscan/app/LocalscanScannerPlugin.java`)
- Scan page → Label OCR: runs OCR (evidence: `app/src/pages/ScanPage.tsx`)
- Scan page → Label parser: parses OCR (evidence: `app/src/pages/ScanPage.tsx`)
- Scan page → Capture draft: creates draft (evidence: `app/src/pages/ScanPage.tsx`)
- Scan page → Item editor: navigates to (evidence: `app/src/pages/ScanPage.tsx`)
- Item editor → Local inventory store: reads and saves (evidence: `app/src/pages/EditItemPage.tsx`)
- Item editor → Capture draft: reads draft (evidence: `app/src/pages/EditItemPage.tsx`)
- Inventory list → Local inventory store: loads inventory
- Item detail → Local inventory store: loads item
- Recycle bin → Local inventory store: manages deleted items
- Data sync → Sync service: uses sync
- Data sync → Data export: exports data
- Settings → Local inventory store: configures local data
- Categories and locations → Local inventory store: manages taxonomy
- Field templates → Local inventory store: manages templates
- Scan page → Barcode lookup: looks up barcode (evidence: `app/src/pages/ScanPage.tsx`)
- App shell → User manual: renders manual (evidence: `app/src/App.tsx`)
