# rachkb/fire-watch architecture

> Architecture diagram of the GitHub repository rachkb/fire-watch, 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/rachkb/fire-watch
- Repository: https://github.com/rachkb/fire-watch

## Overview

FireWatch is a Streamlit decision-support app for classifying uploaded fire/smoke images, showing confidence, risk, and optional Grad-CAM explanations, then saving submissions for administrator review. The main workflow runs from upload through inference and pending storage; only approved submissions appear in public history. Admins can authenticate, moderate submissions, and view analytics. The graph reflects README and SOURCE INDEX relationships; some implementation details are unsampled, so uncertain links are omitted.

Main entry points: [`firewatch/ui/data_access.py`](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/data_access.py) (UI data adapter), [`firewatch/db/session.py`](https://github.com/rachkb/fire-watch/blob/main/firewatch/db/session.py) (Database sessions), [`firewatch/ui/upload_page.py`](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/upload_page.py) (Image upload), [`firewatch/services/submission_service.py`](https://github.com/rachkb/fire-watch/blob/main/firewatch/services/submission_service.py) (Submission service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit UI"]
  node_app["Page router<br/>[app.py]"]
  node_home["Home page<br/>[home_page.py]"]
  node_upload["Image upload<br/>[upload_page.py]"]
  node_history["Approved history<br/>[history_page.py]"]
  node_admin_login["Admin login page"]
  node_moderation_ui["Moderation page"]
  node_analytics_ui["Analytics page"]
  node_ui_components["Shared UI components<br/>[components.py]"]
  node_ui_adapter["UI data adapter<br/>[data_access.py]"]
end

subgraph group_inference["Image analysis"]
  node_preprocess["Image preprocessing<br/>[preprocess.py]"]
  node_predictor["Classifier and predictor<br/>[predictor.py]"]
  node_risk["Risk assessment<br/>[risk.py]"]
  node_heatmap["Grad-CAM heatmaps<br/>[heatmap.py]"]
  node_gradcam["Grad-CAM computation<br/>[gradcam.py]"]
  node_config["Shared thresholds<br/>[config.py]"]
end

subgraph group_services["Application services"]
  node_submission_service["Submission service"]
  node_moderation_service["Moderation service"]
  node_analytics_service["Analytics service"]
  node_row_mapper["Submission row mapper<br/>[rows.py]"]
end

subgraph group_persistence["Persistence"]
  node_db_models[("Application records<br/>[models.py]")]
  node_db_session["Database sessions<br/>[session.py]"]
  node_image_storage["Image storage adapter<br/>[storage.py]"]
end

subgraph group_identity["Admin identity"]
  node_auth_service["Authentication service<br/>[service.py]"]
end

node_visitor(("Public user"))
node_admin(("Administrator"))
node_database[("SQLite / PostgreSQL")]
node_object_storage[("Local / Supabase storage")]

node_visitor -->|"opens"| node_home
node_admin -->|"logs in"| node_admin_login
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_admin_login
node_app -->|"routes to"| node_moderation_ui
node_app -->|"routes to"| node_analytics_ui
node_home -->|"renders"| node_upload
node_home -->|"renders"| node_history
node_home -->|"uses"| node_ui_components
node_upload -->|"analyzes image"| node_preprocess
node_upload -->|"requests prediction"| node_predictor
node_upload -->|"requests explanation"| node_heatmap
node_upload -->|"saves result"| node_ui_adapter
node_upload -->|"renders result"| node_ui_components
node_history -->|"loads approved items"| node_ui_adapter
node_history -->|"uses"| node_ui_components
node_admin_login -->|"authenticates"| node_ui_adapter
node_moderation_ui -->|"requests review actions"| node_ui_adapter
node_moderation_ui -->|"uses"| node_ui_components
node_analytics_ui -->|"loads analytics"| node_ui_adapter
node_analytics_ui -->|"uses"| node_ui_components
node_ui_adapter -->|"delegates login"| node_auth_service
node_ui_adapter -->|"delegates submissions"| node_submission_service
node_ui_adapter -->|"delegates moderation"| node_moderation_service
node_ui_adapter -->|"delegates analytics"| node_analytics_service
node_predictor -->|"preprocesses with"| node_preprocess
node_predictor -->|"derives risk"| node_risk
node_heatmap -->|"computes with"| node_gradcam
node_heatmap -->|"uses"| node_preprocess
node_risk -->|"reads thresholds"| node_config
node_preprocess -->|"reads input settings"| node_config
node_submission_service -->|"stores image"| node_image_storage
node_submission_service -->|"creates submission"| node_db_models
node_submission_service -->|"opens session"| node_db_session
node_submission_service -->|"formats listings"| node_row_mapper
node_moderation_service -->|"deletes image"| node_image_storage
node_moderation_service -->|"updates records"| node_db_models
node_moderation_service -->|"opens session"| node_db_session
node_moderation_service -->|"formats listings"| node_row_mapper
node_analytics_service -->|"queries records"| node_db_models
node_analytics_service -->|"opens session"| node_db_session
node_row_mapper -->|"loads thumbnails"| node_image_storage
node_auth_service -->|"queries admin"| node_db_models
node_auth_service -->|"opens session"| node_db_session
node_db_session -->|"creates schema"| node_db_models
node_db_session -->|"connects to"| node_database
node_image_storage -->|"reads configuration"| node_db_session
node_image_storage -->|"stores and retrieves"| node_object_storage

click node_app "https://github.com/rachkb/fire-watch/blob/main/app.py"
click node_home "https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/home_page.py"
click node_upload "https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/upload_page.py"
click node_history "https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/history_page.py"
click node_admin_login "https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/admin_login_page.py"
click node_moderation_ui "https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/admin_moderation_page.py"
click node_analytics_ui "https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/admin_analytics_page.py"
click node_ui_components "https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/components.py"
click node_ui_adapter "https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/data_access.py"
click node_preprocess "https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/preprocess.py"
click node_predictor "https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/predictor.py"
click node_risk "https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/risk.py"
click node_heatmap "https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/heatmap.py"
click node_gradcam "https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/gradcam.py"
click node_config "https://github.com/rachkb/fire-watch/blob/main/firewatch/config.py"
click node_submission_service "https://github.com/rachkb/fire-watch/blob/main/firewatch/services/submission_service.py"
click node_moderation_service "https://github.com/rachkb/fire-watch/blob/main/firewatch/services/moderation_service.py"
click node_analytics_service "https://github.com/rachkb/fire-watch/blob/main/firewatch/services/analytics_service.py"
click node_row_mapper "https://github.com/rachkb/fire-watch/blob/main/firewatch/services/rows.py"
click node_auth_service "https://github.com/rachkb/fire-watch/blob/main/firewatch/auth/service.py"
click node_db_models "https://github.com/rachkb/fire-watch/blob/main/firewatch/db/models.py"
click node_db_session "https://github.com/rachkb/fire-watch/blob/main/firewatch/db/session.py"
click node_image_storage "https://github.com/rachkb/fire-watch/blob/main/firewatch/db/storage.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_app,node_home,node_upload,node_history,node_admin_login,node_moderation_ui,node_analytics_ui,node_ui_components,node_ui_adapter,node_visitor toneBlue
class node_preprocess,node_predictor,node_risk,node_heatmap,node_gradcam,node_config,node_database,node_object_storage toneAmber
class node_submission_service,node_moderation_service,node_analytics_service,node_row_mapper toneMint
class node_db_models,node_db_session,node_image_storage toneRose
class node_auth_service,node_admin toneIndigo
```

## Components

### Streamlit UI

- [Page router](https://github.com/rachkb/fire-watch/blob/main/app.py): `app.py`
- [Home page](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/home_page.py): `firewatch/ui/home_page.py`
- [Image upload](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/upload_page.py): `firewatch/ui/upload_page.py`
- [Approved history](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/history_page.py): `firewatch/ui/history_page.py`
- [Admin login page](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/admin_login_page.py): `firewatch/ui/admin_login_page.py`
- [Moderation page](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/admin_moderation_page.py): `firewatch/ui/admin_moderation_page.py`
- [Analytics page](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/admin_analytics_page.py): `firewatch/ui/admin_analytics_page.py`
- [Shared UI components](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/components.py): `firewatch/ui/components.py`
- [UI data adapter](https://github.com/rachkb/fire-watch/blob/main/firewatch/ui/data_access.py): `firewatch/ui/data_access.py`

### Image analysis

- [Image preprocessing](https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/preprocess.py): `firewatch/inference/preprocess.py`
- [Classifier and predictor](https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/predictor.py): `firewatch/inference/predictor.py`
- [Risk assessment](https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/risk.py): `firewatch/inference/risk.py`
- [Grad-CAM heatmaps](https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/heatmap.py): `firewatch/inference/heatmap.py`
- [Grad-CAM computation](https://github.com/rachkb/fire-watch/blob/main/firewatch/inference/gradcam.py): `firewatch/inference/gradcam.py`
- [Shared thresholds](https://github.com/rachkb/fire-watch/blob/main/firewatch/config.py): `firewatch/config.py`

### Application services

- [Submission service](https://github.com/rachkb/fire-watch/blob/main/firewatch/services/submission_service.py): `firewatch/services/submission_service.py`
- [Moderation service](https://github.com/rachkb/fire-watch/blob/main/firewatch/services/moderation_service.py): `firewatch/services/moderation_service.py`
- [Analytics service](https://github.com/rachkb/fire-watch/blob/main/firewatch/services/analytics_service.py): `firewatch/services/analytics_service.py`
- [Submission row mapper](https://github.com/rachkb/fire-watch/blob/main/firewatch/services/rows.py): `firewatch/services/rows.py`

### Persistence

- [Application records](https://github.com/rachkb/fire-watch/blob/main/firewatch/db/models.py): `firewatch/db/models.py`
- [Database sessions](https://github.com/rachkb/fire-watch/blob/main/firewatch/db/session.py): `firewatch/db/session.py`
- [Image storage adapter](https://github.com/rachkb/fire-watch/blob/main/firewatch/db/storage.py): `firewatch/db/storage.py`

### Admin identity

- [Authentication service](https://github.com/rachkb/fire-watch/blob/main/firewatch/auth/service.py): `firewatch/auth/service.py`

### Other components

- **Public user**
- **Administrator**
- **SQLite / PostgreSQL**
- **Local / Supabase storage**

## Connections

- Public user → Home page: opens (evidence: `README.md`)
- Administrator → Admin login page: logs in (evidence: `README.md`)
- Page router → Home page: routes to (evidence: `app.py`)
- Page router → Admin login page: routes to (evidence: `app.py`)
- Page router → Moderation page: routes to (evidence: `app.py`)
- Page router → Analytics page: routes to (evidence: `app.py`)
- Home page → Image upload: renders (evidence: `firewatch/ui/home_page.py`)
- Home page → Approved history: renders (evidence: `firewatch/ui/home_page.py`)
- Home page → Shared UI components: uses (evidence: `firewatch/ui/home_page.py`)
- Image upload → Image preprocessing: analyzes image (evidence: `README.md`)
- Image upload → Classifier and predictor: requests prediction (evidence: `firewatch/ui/upload_page.py`)
- Image upload → Grad-CAM heatmaps: requests explanation (evidence: `README.md`)
- Image upload → UI data adapter: saves result (evidence: `firewatch/ui/upload_page.py`)
- Image upload → Shared UI components: renders result (evidence: `firewatch/ui/upload_page.py`)
- Approved history → UI data adapter: loads approved items (evidence: `firewatch/ui/history_page.py`)
- Approved history → Shared UI components: uses (evidence: `firewatch/ui/history_page.py`)
- Admin login page → UI data adapter: authenticates (evidence: `firewatch/ui/admin_login_page.py`)
- Moderation page → UI data adapter: requests review actions (evidence: `firewatch/ui/admin_moderation_page.py`)
- Moderation page → Shared UI components: uses (evidence: `firewatch/ui/admin_moderation_page.py`)
- Analytics page → UI data adapter: loads analytics (evidence: `firewatch/ui/admin_analytics_page.py`)
- Analytics page → Shared UI components: uses (evidence: `firewatch/ui/admin_analytics_page.py`)
- UI data adapter → Authentication service: delegates login (evidence: `firewatch/ui/data_access.py`)
- UI data adapter → Submission service: delegates submissions (evidence: `firewatch/ui/data_access.py`)
- UI data adapter → Moderation service: delegates moderation (evidence: `firewatch/ui/data_access.py`)
- UI data adapter → Analytics service: delegates analytics (evidence: `firewatch/ui/data_access.py`)
- Classifier and predictor → Image preprocessing: preprocesses with (evidence: `firewatch/inference/predictor.py`)
- Classifier and predictor → Risk assessment: derives risk (evidence: `firewatch/inference/predictor.py`)
- Grad-CAM heatmaps → Grad-CAM computation: computes with (evidence: `firewatch/inference/heatmap.py`)
- Grad-CAM heatmaps → Image preprocessing: uses (evidence: `firewatch/inference/heatmap.py`)
- Risk assessment → Shared thresholds: reads thresholds (evidence: `firewatch/inference/risk.py`)
- Image preprocessing → Shared thresholds: reads input settings (evidence: `firewatch/inference/preprocess.py`)
- Submission service → Image storage adapter: stores image (evidence: `firewatch/services/submission_service.py`)
- Submission service → Application records: creates submission (evidence: `firewatch/services/submission_service.py`)
- Submission service → Database sessions: opens session (evidence: `firewatch/services/submission_service.py`)
- Submission service → Submission row mapper: formats listings (evidence: `firewatch/services/submission_service.py`)
- Moderation service → Image storage adapter: deletes image (evidence: `firewatch/services/moderation_service.py`)
- Moderation service → Application records: updates records (evidence: `firewatch/services/moderation_service.py`)
- Moderation service → Database sessions: opens session (evidence: `firewatch/services/moderation_service.py`)
- Moderation service → Submission row mapper: formats listings (evidence: `firewatch/services/moderation_service.py`)
- Analytics service → Application records: queries records (evidence: `firewatch/services/analytics_service.py`)
- Analytics service → Database sessions: opens session (evidence: `firewatch/services/analytics_service.py`)
- Submission row mapper → Image storage adapter: loads thumbnails (evidence: `firewatch/services/rows.py`)
- Authentication service → Application records: queries admin (evidence: `firewatch/auth/service.py`)
- Authentication service → Database sessions: opens session (evidence: `firewatch/auth/service.py`)
- Database sessions → Application records: creates schema (evidence: `firewatch/db/session.py`)
- Database sessions → SQLite / PostgreSQL: connects to (evidence: `README.md`)
- Image storage adapter → Database sessions: reads configuration (evidence: `firewatch/db/storage.py`)
- Image storage adapter → Local / Supabase storage: stores and retrieves (evidence: `firewatch/db/storage.py`)
