# ujwaltikhe/udtc architecture

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

- Interactive diagram: https://gitdiagram.com/ujwaltikhe/udtc
- Repository: https://github.com/ujwaltikhe/udtc

## Overview

This repository implements a digital field companion for presumptive drug testing: an officer captures and analyzes a reagent-card image, confirms a result, and preserves it as signed, tamper-evident evidence for later synchronization and legal export. The Flutter app is the field-facing product; a FastAPI service supports central records, audit, staged uploads, Merkle batching, SMS anchors, and exports. The sampled files establish backend and security behavior, but not most Flutter call wiring, so uncertain screen-to-service connections are omitted.

Main entry points: [`mobile_app/lib/main.dart`](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/main.dart) (Field app), [`mobile_app/lib/repositories/field_record_repository.dart`](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/repositories/field_record_repository.dart) (Record repository), [`backend/server.py`](https://github.com/ujwaltikhe/udtc/blob/main/backend/server.py) (Sync API), [`mobile_app/lib/screens/test_analysis_screen.dart`](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/test_analysis_screen.dart) (Test analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_field["Field Testing"]
  node_mobile["Field app<br/>[main.dart]"]
  node_capture["Image capture"]
  node_kit["Kit selection"]
  node_analysis["Test analysis"]
  node_timer["Reaction timing"]
  node_colorimeter["Colorimeter engine<br/>[colorimeter.py]"]
  node_card["Reference card<br/>[generate_card.py]"]
  node_record["Record confirmation"]
end

subgraph group_evidence["Evidence Integrity"]
  node_repository["Record repository"]
  node_signer["Dual signer<br/>[crypto_signer.py]"]
  node_ledger[("Local hash ledger<br/>[hash_ledger.py]")]
  node_location["Location service"]
  node_legal["Legal exports<br/>[legal_forensics.py]"]
end

subgraph group_sync["Sync and Review"]
  node_syncservice["Staged sync"]
  node_backend["Sync API<br/>[server.py]"]
  node_vault[("Server records<br/>[server_vault.db]")]
  node_sms[("SMS anchor gateway<br/>[sms_anchor.py]")]
  node_android["Android SMS bridge<br/>[MainActivity.kt]"]
end

subgraph group_demo["Demonstration"]
  node_demo["Demo console<br/>[app.py]"]
end

node_officer(("Field officer"))
node_network(("GSM network"))

node_officer -->|"uses"| node_mobile
node_mobile -->|"opens capture"| node_capture
node_mobile -->|"selects kit"| node_kit
node_mobile -->|"reviews analysis"| node_analysis
node_analysis -->|"analyzes image"| node_colorimeter
node_colorimeter -.->|"uses card layout"| node_card
node_mobile -->|"times reaction"| node_timer
node_mobile -->|"confirms record"| node_record
node_record -->|"saves record"| node_repository
node_repository -->|"requests signatures"| node_signer
node_repository -->|"writes record"| node_ledger
node_repository -.->|"uses location"| node_location
node_mobile -->|"starts sync"| node_syncservice
node_syncservice -->|"uploads stages"| node_backend
node_backend -->|"stores records"| node_vault
node_backend -->|"records inbound SMS"| node_sms
node_android -->|"sends SMS"| node_network
node_backend -->|"generates exports"| node_legal
node_officer -.->|"evaluates demo"| node_demo

click node_mobile "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/main.dart"
click node_capture "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/camera_capture_screen.dart"
click node_kit "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/kit_selection_screen.dart"
click node_analysis "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/test_analysis_screen.dart"
click node_timer "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/reaction_timer_screen.dart"
click node_colorimeter "https://github.com/ujwaltikhe/udtc/blob/main/engine/colorimeter.py"
click node_card "https://github.com/ujwaltikhe/udtc/blob/main/card_assets/generate_card.py"
click node_record "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/record_confirm_screen.dart"
click node_repository "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/repositories/field_record_repository.dart"
click node_signer "https://github.com/ujwaltikhe/udtc/blob/main/security/crypto_signer.py"
click node_ledger "https://github.com/ujwaltikhe/udtc/blob/main/security/hash_ledger.py"
click node_location "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/services/location_service.dart"
click node_legal "https://github.com/ujwaltikhe/udtc/blob/main/security/legal_forensics.py"
click node_syncservice "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/services/staged_sync_service.dart"
click node_backend "https://github.com/ujwaltikhe/udtc/blob/main/backend/server.py"
click node_vault "https://github.com/ujwaltikhe/udtc/blob/main/backend/server_vault.db"
click node_sms "https://github.com/ujwaltikhe/udtc/blob/main/sync_mesh/sms_anchor.py"
click node_android "https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/android/app/src/main/kotlin/gov/ncb/fieldtesting/MainActivity.kt"
click node_demo "https://github.com/ujwaltikhe/udtc/blob/main/demo_suite/app.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_mobile,node_capture,node_kit,node_analysis,node_timer,node_colorimeter,node_card,node_record toneBlue
class node_repository,node_signer,node_ledger,node_location,node_legal toneAmber
class node_syncservice,node_backend,node_vault,node_sms,node_android toneMint
class node_demo toneRose
class node_officer,node_network toneIndigo
```

## Components

### Field Testing

- [Field app](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/main.dart): `mobile_app/lib/main.dart`
- [Image capture](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/camera_capture_screen.dart): `mobile_app/lib/screens/camera_capture_screen.dart`
- [Kit selection](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/kit_selection_screen.dart): `mobile_app/lib/screens/kit_selection_screen.dart`
- [Test analysis](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/test_analysis_screen.dart): `mobile_app/lib/screens/test_analysis_screen.dart`
- [Reaction timing](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/reaction_timer_screen.dart): `mobile_app/lib/screens/reaction_timer_screen.dart`
- [Colorimeter engine](https://github.com/ujwaltikhe/udtc/blob/main/engine/colorimeter.py): `engine/colorimeter.py`
- [Reference card](https://github.com/ujwaltikhe/udtc/blob/main/card_assets/generate_card.py): `card_assets/generate_card.py`
- [Record confirmation](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/screens/record_confirm_screen.dart): `mobile_app/lib/screens/record_confirm_screen.dart`

### Evidence Integrity

- [Record repository](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/repositories/field_record_repository.dart): `mobile_app/lib/repositories/field_record_repository.dart`
- [Dual signer](https://github.com/ujwaltikhe/udtc/blob/main/security/crypto_signer.py): `security/crypto_signer.py`
- [Local hash ledger](https://github.com/ujwaltikhe/udtc/blob/main/security/hash_ledger.py): `security/hash_ledger.py`
- [Location service](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/services/location_service.dart): `mobile_app/lib/services/location_service.dart`
- [Legal exports](https://github.com/ujwaltikhe/udtc/blob/main/security/legal_forensics.py): `security/legal_forensics.py`

### Sync and Review

- [Staged sync](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/lib/services/staged_sync_service.dart): `mobile_app/lib/services/staged_sync_service.dart`
- [Sync API](https://github.com/ujwaltikhe/udtc/blob/main/backend/server.py): `backend/server.py`
- [Server records](https://github.com/ujwaltikhe/udtc/blob/main/backend/server_vault.db): `backend/server_vault.db`
- [SMS anchor gateway](https://github.com/ujwaltikhe/udtc/blob/main/sync_mesh/sms_anchor.py): `sync_mesh/sms_anchor.py`
- [Android SMS bridge](https://github.com/ujwaltikhe/udtc/blob/main/mobile_app/android/app/src/main/kotlin/gov/ncb/fieldtesting/MainActivity.kt): `mobile_app/android/app/src/main/kotlin/gov/ncb/fieldtesting/MainActivity.kt`

### Demonstration

- [Demo console](https://github.com/ujwaltikhe/udtc/blob/main/demo_suite/app.py): `demo_suite/app.py`

### Other components

- **Field officer**
- **GSM network**

## Connections

- Field officer → Field app: uses
- Field app → Image capture: opens capture
- Field app → Kit selection: selects kit
- Field app → Test analysis: reviews analysis
- Test analysis → Colorimeter engine: analyzes image
- Colorimeter engine → Reference card: uses card layout
- Field app → Reaction timing: times reaction
- Field app → Record confirmation: confirms record
- Record confirmation → Record repository: saves record
- Record repository → Dual signer: requests signatures
- Record repository → Local hash ledger: writes record
- Record repository → Location service: uses location
- Field app → Staged sync: starts sync
- Staged sync → Sync API: uploads stages
- Sync API → Server records: stores records
- Sync API → SMS anchor gateway: records inbound SMS
- Android SMS bridge → GSM network: sends SMS
- Sync API → Legal exports: generates exports
- Field officer → Demo console: evaluates demo