# garnavya/exifgrid architecture

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

- Interactive diagram: https://gitdiagram.com/garnavya/exifgrid
- Repository: https://github.com/garnavya/exifgrid

## Overview

1. **System shape:** ExifGrid is a monorepo with a **browser-first React/Vite client** and a **thin Express backend**. The core product behavior happens entirely in the client; the server exists mainly to collect and aggregate anonymous telemetry.

2. **Client app shell:** `client/src/main.jsx` boots the React app, and `App.jsx` is the central orchestrator for upload state, selected photos, filters, comparison mode, modals, and export actions. The app is split into feature components rather than a single gallery screen.

3. **Photo ingestion pipeline:** The entry point is `DropZone`, which accepts local image files from the user. Uploaded files are processed in-browser through `batchProcessor`, `exifReader`, and `exifWorker`, with images typically handled as local blobs/object URLs so the data stays on the device.

4. **Client-side metadata and AI processing:** EXIF extraction, camera stats, and any AI-style analysis are done locally. The ONNX model in `client/public/models/` is loaded through `onnxWorker`, keeping inference inside the browser instead of on the server.

5. **Primary visual surfaces:** `Gallery`, `PhotoCard`, `Lightbox`, and `ComparisonFeed` are the main viewing layers. The gallery is the central browsing surface; lightbox and comparison are the “inspect a single photo / compare two photos” paths.

6. **Insights and filtering layer:** `FilterMatrix`, `StatsBar`, `InsightsDashboard`, and hooks like `usePhotoFilters` and `useKeyboardNav` manage derived views over the uploaded set. `utils/stats.js`, `adviceEngine.js`, and `formatters.js` support summarization and human-readable interpretations of the photo metadata.

7. **Map and geo-focused view:** `JourneyMap` is a separate visualization boundary for location-aware photos. Based on the Leaflet dependency and the EXIF pipeline, this view likely consumes GPS metadata when present and turns it into a geographic browsing experience.

8. **Export and privacy tools:** The app includes local export utilities for different downstream outputs: `csvExport` for tabular metadata, `polaroid.js` for stylized image generation, and `exifStripper` for creating scrubbed, share-safe images. These features reinforce the repo’s privacy-first, local-processing design.

9. **Telemetry subsystem:** `client/src/api/telemetry.js` sends anonymous usage statistics to the backend. `server/server.js` is the aggregation boundary, and the README indicates those metrics feed global leaderboards such as popular camera models and focal lengths, likely backed by MongoDB Atlas.

10. **UI/theming and deployment:** Styling is heavily modularized across many CSS files, with `theme.css` acting as the global visual layer and separate styles for gallery, modal, map, mobile, etc. `client/vercel.json` suggests the frontend is deployed independently, while the root `package.json` and `server/package.json` reflect the split client/server runtime model.

11. **Important architectural boundary:** The key distinction for a diagram is that **photo content and EXIF parsing stay local in the browser**, while **only anonymous telemetry leaves the device**. That boundary is the defining privacy and system-design choice of this repository.

Main entry points: [`client/src/App.jsx`](https://github.com/garnavya/exifgrid/blob/main/client/src/App.jsx) (App shell), [`client/src/utils/batchProcessor.js`](https://github.com/garnavya/exifgrid/blob/main/client/src/utils/batchProcessor.js) (Batch processor), [`client/src/components/Gallery.jsx`](https://github.com/garnavya/exifgrid/blob/main/client/src/components/Gallery.jsx) (Gallery), [`client/src/components/DropZone.jsx`](https://github.com/garnavya/exifgrid/blob/main/client/src/components/DropZone.jsx) (DropZone)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_main(("Entry<br/>React boot<br/>[main.jsx]"))
  node_app["App shell<br/>Orchestrator<br/>[App.jsx]"]
  node_dropzone["DropZone<br/>Uploader<br/>[DropZone.jsx]"]
end

subgraph group_pipeline["Local processing"]
  node_batch["Batch processor<br/>Ingest pipeline<br/>[batchProcessor.js]"]
  node_exif["EXIF reader<br/>Metadata parse<br/>[exifReader.js]"]
  node_worker["EXIF worker<br/>Web worker<br/>[exifWorker.js]"]
  node_onnx["AI worker<br/>Inference worker<br/>[onnxWorker.js]"]
  node_model[("ONNX model<br/>Browser model")]
end

subgraph group_views["Viewing surfaces"]
  node_gallery["Gallery<br/>Browse view<br/>[Gallery.jsx]"]
  node_card["Photo card<br/>Thumbnail view<br/>[PhotoCard.jsx]"]
  node_lightbox["Lightbox<br/>Inspect view<br/>[Lightbox.jsx]"]
  node_compare["Compare feed<br/>Compare view<br/>[ComparisonFeed.jsx]"]
  node_map["Journey map<br/>Geo view<br/>[JourneyMap.jsx]"]
end

subgraph group_insights["Insights layer"]
  node_filters["Filter matrix<br/>Filter UI<br/>[FilterMatrix.jsx]"]
  node_statsbar["Stats bar<br/>Summary strip<br/>[StatsBar.jsx]"]
  node_dashboard["Insights dashboard<br/>Analytics view"]
  node_filtershook{{"Photo filters<br/>Hook<br/>[usePhotoFilters.js]"}}
end

subgraph group_export["Exports"]
  node_exporttools["Export tools<br/>Local output<br/>[csvExport.js]"]
  node_stripper["Exif stripper<br/>Privacy tool<br/>[exifStripper.js]"]
end

subgraph group_server["Telemetry server"]
  node_telemetry(("Telemetry API<br/>Client analytics<br/>[telemetry.js]"))
  node_serverjs[("Aggregator<br/>Express server<br/>[server.js]")]
end

node_main -->|"boots"| node_app
node_app -->|"upload"| node_dropzone
node_dropzone -->|"files"| node_batch
node_batch -->|"parse"| node_exif
node_exif -->|"offload"| node_worker
node_batch -->|"infer"| node_onnx
node_onnx -->|"loads"| node_model
node_app -->|"browse"| node_gallery
node_gallery -->|"renders"| node_card
node_app -->|"inspect"| node_lightbox
node_app -->|"compare"| node_compare
node_app -->|"geo view"| node_map
node_app -->|"filter"| node_filters
node_filters -->|"derive"| node_filtershook
node_filtershook -->|"subset"| node_gallery
node_app -->|"summarize"| node_statsbar
node_app -->|"analyze"| node_dashboard
node_app -->|"export"| node_exporttools
node_exporttools -->|"scrub"| node_stripper
node_app -->|"usage"| node_telemetry
node_telemetry -->|"collect"| node_serverjs

click node_main "https://github.com/garnavya/exifgrid/blob/main/client/src/main.jsx"
click node_app "https://github.com/garnavya/exifgrid/blob/main/client/src/App.jsx"
click node_dropzone "https://github.com/garnavya/exifgrid/blob/main/client/src/components/DropZone.jsx"
click node_batch "https://github.com/garnavya/exifgrid/blob/main/client/src/utils/batchProcessor.js"
click node_exif "https://github.com/garnavya/exifgrid/blob/main/client/src/utils/exifReader.js"
click node_worker "https://github.com/garnavya/exifgrid/blob/main/client/src/utils/exifWorker.js"
click node_onnx "https://github.com/garnavya/exifgrid/blob/main/client/src/utils/onnxWorker.js"
click node_model "https://github.com/garnavya/exifgrid/blob/main/client/public/models/exifgrid_v1_production.onnx"
click node_gallery "https://github.com/garnavya/exifgrid/blob/main/client/src/components/Gallery.jsx"
click node_card "https://github.com/garnavya/exifgrid/blob/main/client/src/components/PhotoCard.jsx"
click node_lightbox "https://github.com/garnavya/exifgrid/blob/main/client/src/components/Lightbox.jsx"
click node_compare "https://github.com/garnavya/exifgrid/blob/main/client/src/components/ComparisonFeed.jsx"
click node_map "https://github.com/garnavya/exifgrid/blob/main/client/src/components/JourneyMap.jsx"
click node_filters "https://github.com/garnavya/exifgrid/blob/main/client/src/components/FilterMatrix.jsx"
click node_statsbar "https://github.com/garnavya/exifgrid/blob/main/client/src/components/StatsBar.jsx"
click node_dashboard "https://github.com/garnavya/exifgrid/blob/main/client/src/components/InsightsDashboard.jsx"
click node_filtershook "https://github.com/garnavya/exifgrid/blob/main/client/src/hooks/usePhotoFilters.js"
click node_telemetry "https://github.com/garnavya/exifgrid/blob/main/client/src/api/telemetry.js"
click node_serverjs "https://github.com/garnavya/exifgrid/blob/main/server/server.js"
click node_exporttools "https://github.com/garnavya/exifgrid/blob/main/client/src/utils/csvExport.js"
click node_stripper "https://github.com/garnavya/exifgrid/blob/main/client/src/utils/exifStripper.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_main,node_app,node_dropzone toneBlue
class node_batch,node_exif,node_worker,node_onnx,node_model toneAmber
class node_gallery,node_card,node_lightbox,node_compare,node_map toneMint
class node_filters,node_statsbar,node_dashboard,node_filtershook toneRose
class node_exporttools,node_stripper toneIndigo
class node_telemetry,node_serverjs toneTeal
```

## Components

### Browser client

React/Vite app where photos are uploaded, processed, viewed, and exported locally.

- [Entry](https://github.com/garnavya/exifgrid/blob/main/client/src/main.jsx): React boot · Mounts the client application. · `client/src/main.jsx`
- [App shell](https://github.com/garnavya/exifgrid/blob/main/client/src/App.jsx): Orchestrator · Coordinates upload state, selection, filters, compare mode, modals, and export actions. · `client/src/App.jsx`
- [DropZone](https://github.com/garnavya/exifgrid/blob/main/client/src/components/DropZone.jsx): Uploader · Accepts local image files and starts ingestion. · `client/src/components/DropZone.jsx`

### Local processing

In-browser ingestion, EXIF extraction, and model inference.

- [Batch processor](https://github.com/garnavya/exifgrid/blob/main/client/src/utils/batchProcessor.js): Ingest pipeline · Processes uploaded files in-browser and prepares photo records. · `client/src/utils/batchProcessor.js`
- [EXIF reader](https://github.com/garnavya/exifgrid/blob/main/client/src/utils/exifReader.js): Metadata parse · Extracts camera and GPS metadata from image files locally. · `client/src/utils/exifReader.js`
- [EXIF worker](https://github.com/garnavya/exifgrid/blob/main/client/src/utils/exifWorker.js): Web worker · Offloads metadata parsing work from the main thread. · `client/src/utils/exifWorker.js`
- [AI worker](https://github.com/garnavya/exifgrid/blob/main/client/src/utils/onnxWorker.js): Inference worker · Runs browser-side model inference using the packaged ONNX model. · `client/src/utils/onnxWorker.js`
- [ONNX model](https://github.com/garnavya/exifgrid/blob/main/client/public/models/exifgrid_v1_production.onnx): Browser model · Packaged inference asset loaded by the client. · `client/public/models/exifgrid_v1_production.onnx`

### Viewing surfaces

Primary screens for browsing, inspecting, comparing, and mapping photos.

- [Gallery](https://github.com/garnavya/exifgrid/blob/main/client/src/components/Gallery.jsx): Browse view · Central browsing surface for uploaded photos. · `client/src/components/Gallery.jsx`
- [Photo card](https://github.com/garnavya/exifgrid/blob/main/client/src/components/PhotoCard.jsx): Thumbnail view · Renders individual photo tiles and metadata cues. · `client/src/components/PhotoCard.jsx`
- [Lightbox](https://github.com/garnavya/exifgrid/blob/main/client/src/components/Lightbox.jsx): Inspect view · Focused single-photo inspection path. · `client/src/components/Lightbox.jsx`
- [Compare feed](https://github.com/garnavya/exifgrid/blob/main/client/src/components/ComparisonFeed.jsx): Compare view · Side-by-side comparison path for two or more photos. · `client/src/components/ComparisonFeed.jsx`
- [Journey map](https://github.com/garnavya/exifgrid/blob/main/client/src/components/JourneyMap.jsx): Geo view · Visualizes location-aware photos using GPS metadata when available. · `client/src/components/JourneyMap.jsx`

### Insights layer

Derived filtering, statistics, and interpretation over the uploaded set.

- [Filter matrix](https://github.com/garnavya/exifgrid/blob/main/client/src/components/FilterMatrix.jsx): Filter UI · Controls derived views and subset selection. · `client/src/components/FilterMatrix.jsx`
- [Stats bar](https://github.com/garnavya/exifgrid/blob/main/client/src/components/StatsBar.jsx): Summary strip · Shows quick counts and metadata summaries. · `client/src/components/StatsBar.jsx`
- [Insights dashboard](https://github.com/garnavya/exifgrid/blob/main/client/src/components/InsightsDashboard.jsx): Analytics view · Aggregates photo-level patterns into readable insights. · `client/src/components/InsightsDashboard.jsx`
- [Photo filters](https://github.com/garnavya/exifgrid/blob/main/client/src/hooks/usePhotoFilters.js): Hook · Derives filtered photo sets from current app state. · `client/src/hooks/usePhotoFilters.js`

### Exports

Local output tools for tabular, visual, and scrubbed sharing formats.

- [Export tools](https://github.com/garnavya/exifgrid/blob/main/client/src/utils/csvExport.js): Local output · Shared export utilities for metadata, visuals, and scrubbed images. · `client/src/utils/csvExport.js`
- [Exif stripper](https://github.com/garnavya/exifgrid/blob/main/client/src/utils/exifStripper.js): Privacy tool · Creates share-safe images by removing sensitive metadata. · `client/src/utils/exifStripper.js`

### Telemetry server

Thin backend that receives anonymous metrics and aggregates usage data.

- [Telemetry API](https://github.com/garnavya/exifgrid/blob/main/client/src/api/telemetry.js): Client analytics · Sends anonymous usage statistics from the browser. · `client/src/api/telemetry.js`
- [Aggregator](https://github.com/garnavya/exifgrid/blob/main/server/server.js): Express server · Receives and aggregates anonymous telemetry. · `server/server.js`

## Connections

- Entry → App shell: boots · React entry mounts the main app shell.
- App shell → DropZone: upload · App exposes file ingestion through the drop zone.
- DropZone → Batch processor: files · Selected files enter the browser-side batch pipeline.
- Batch processor → EXIF reader: parse · Batched images are parsed for local metadata extraction.
- EXIF reader → EXIF worker: offload · Parsing work is delegated to a worker.
- Batch processor → AI worker: infer · Batch processing can trigger local model analysis.
- AI worker → ONNX model: loads · Inference worker uses the packaged ONNX asset.
- App shell → Gallery: browse · The app routes processed photos into the gallery surface.
- Gallery → Photo card: renders · Gallery is composed of individual photo cards.
- App shell → Lightbox: inspect · Single-photo inspection is opened from the app shell.
- App shell → Compare feed: compare · Comparison mode is coordinated by the app shell.
- App shell → Journey map: geo view · Geo-aware photos can be shown in the map surface.
- App shell → Filter matrix: filter · Filtering controls shape the visible subset.
- Filter matrix → Photo filters: derive · The filter UI is backed by derived-photo filtering logic.
- Photo filters → Gallery: subset · Filtered results feed the browsing surface.
- App shell → Stats bar: summarize · Quick summaries are surfaced in the stats bar.
- App shell → Insights dashboard: analyze · Insights dashboard presents deeper aggregated views.
- App shell → Export tools: export · App exposes local export actions.
- Export tools → Exif stripper: scrub · Privacy-preserving exports remove EXIF data when needed.
- App shell → Telemetry API: usage · Anonymous usage events are sent from the client.
- Telemetry API → Aggregator: collect · Backend receives telemetry for aggregation.
