# lincolnkermit/eyefinder architecture

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

- Interactive diagram: https://gitdiagram.com/lincolnkermit/eyefinder
- Repository: https://github.com/lincolnkermit/eyefinder

## Overview

EyeFinder is a browser-based CCTV discovery and monitoring map. Visitors explore camera locations, inspect stream status, and open feeds; operators manage camera records and access settings, review traffic metrics, and run health checks. The backend routes these requests to separate camera, administration, authentication, metrics, and scheduled-check handlers. Camera records use Supabase/PostgreSQL when configured, with local-file and seed-data fallbacks. The README documents the map, live status, feed redirection, and scheduled verification; unsampled frontend/API wiring is shown only where documented or marked unverified.

Main entry points: [`api/admin.js`](https://github.com/lincolnkermit/eyefinder/blob/main/api/admin.js) (Admin API), [`lib/db.js`](https://github.com/lincolnkermit/eyefinder/blob/main/lib/db.js) (Camera store), [`server.js`](https://github.com/lincolnkermit/eyefinder/blob/main/server.js) (HTTP server), [`api/cameras.js`](https://github.com/lincolnkermit/eyefinder/blob/main/api/cameras.js) (Camera API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Map and Admin UI"]
  node_map_ui["Camera map<br/>[app.js]"]
  node_admin_ui["Admin portal<br/>[admin.js]"]
end

subgraph group_api["HTTP API"]
  node_server["HTTP server<br/>[server.js]"]
  node_camera_api["Camera API<br/>[cameras.js]"]
  node_admin_api["Admin API<br/>[admin.js]"]
  node_auth_api["Access API<br/>[auth.js]"]
  node_cron_api["Health cron API<br/>[cron.js]"]
  node_metrics_api["Metrics API<br/>[metrics.js]"]
end

subgraph group_domain["Camera and Security Services"]
  node_camera_data["Camera records<br/>[seed.js]"]
  node_health_probe["Stream health checks<br/>[scraper.js]"]
  node_security["Access and validation<br/>[security.js]"]
end

subgraph group_state["Persistence and Telemetry"]
  node_camera_store[("Camera store<br/>[db.js]")]
  node_settings["Site settings<br/>[settings.json]"]
  node_metrics_logic["Traffic telemetry<br/>[metrics.js]"]
end

node_visitor(("Map visitor"))
node_operator(("Site operator"))
node_supabase[("Supabase / PostgreSQL")]
node_local_files[("Local camera files<br/>[cameras.json]")]
node_camera_streams["Public camera streams"]
node_nominatim["Nominatim geocoder"]
node_scheduler(("Vercel scheduler"))

node_visitor -->|"opens map"| node_map_ui
node_map_ui -.->|"loads cameras"| node_camera_api
node_map_ui -->|"opens feed"| node_camera_streams
node_operator -->|"manages cameras"| node_admin_ui
node_admin_ui -.->|"admin actions"| node_admin_api
node_server -->|"routes requests"| node_camera_api
node_server -->|"routes requests"| node_cron_api
node_server -->|"routes requests"| node_admin_api
node_server -->|"routes requests"| node_metrics_api
node_server -->|"routes requests"| node_auth_api
node_camera_api -->|"reads and writes"| node_camera_store
node_camera_api -->|"checks access"| node_security
node_camera_api -->|"loads seed"| node_camera_data
node_admin_api -->|"manages records"| node_camera_store
node_admin_api -->|"checks access"| node_security
node_admin_api -.->|"uses probe"| node_health_probe
node_admin_api -->|"loads seed"| node_camera_data
node_admin_api -->|"geocodes addresses"| node_nominatim
node_auth_api -->|"verifies passkey"| node_security
node_auth_api -.->|"reads settings"| node_settings
node_cron_api -->|"loads and saves"| node_camera_store
node_cron_api -->|"checks streams"| node_health_probe
node_cron_api -->|"loads fallback"| node_camera_data
node_scheduler -->|"invokes scheduled check"| node_cron_api
node_health_probe -->|"validates URLs"| node_security
node_health_probe -->|"probes streams"| node_camera_streams
node_camera_store -->|"falls back to seed"| node_camera_data
node_camera_store -->|"reads and writes"| node_supabase
node_camera_store -->|"falls back locally"| node_local_files
node_metrics_api -->|"records and summarizes"| node_metrics_logic
node_metrics_api -->|"checks admin access"| node_security

click node_map_ui "https://github.com/lincolnkermit/eyefinder/blob/main/public/app.js"
click node_admin_ui "https://github.com/lincolnkermit/eyefinder/blob/main/public/admin.js"
click node_server "https://github.com/lincolnkermit/eyefinder/blob/main/server.js"
click node_camera_api "https://github.com/lincolnkermit/eyefinder/blob/main/api/cameras.js"
click node_admin_api "https://github.com/lincolnkermit/eyefinder/blob/main/api/admin.js"
click node_auth_api "https://github.com/lincolnkermit/eyefinder/blob/main/api/auth.js"
click node_cron_api "https://github.com/lincolnkermit/eyefinder/blob/main/api/cron.js"
click node_metrics_api "https://github.com/lincolnkermit/eyefinder/blob/main/api/metrics.js"
click node_camera_data "https://github.com/lincolnkermit/eyefinder/blob/main/lib/seed.js"
click node_health_probe "https://github.com/lincolnkermit/eyefinder/blob/main/lib/scraper.js"
click node_security "https://github.com/lincolnkermit/eyefinder/blob/main/lib/security.js"
click node_camera_store "https://github.com/lincolnkermit/eyefinder/blob/main/lib/db.js"
click node_settings "https://github.com/lincolnkermit/eyefinder/blob/main/data/settings.json"
click node_metrics_logic "https://github.com/lincolnkermit/eyefinder/blob/main/lib/metrics.js"
click node_local_files "https://github.com/lincolnkermit/eyefinder/blob/main/data/cameras.json"

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_map_ui,node_admin_ui toneBlue
class node_server,node_camera_api,node_admin_api,node_auth_api,node_cron_api,node_metrics_api,node_supabase,node_local_files toneAmber
class node_camera_data,node_health_probe,node_security toneMint
class node_camera_store,node_settings,node_metrics_logic,node_scheduler toneRose
class node_visitor,node_operator,node_camera_streams,node_nominatim toneIndigo
```

## Components

### Map and Admin UI

- [Camera map](https://github.com/lincolnkermit/eyefinder/blob/main/public/app.js): `public/app.js`
- [Admin portal](https://github.com/lincolnkermit/eyefinder/blob/main/public/admin.js): `public/admin.js`

### HTTP API

- [HTTP server](https://github.com/lincolnkermit/eyefinder/blob/main/server.js): `server.js`
- [Camera API](https://github.com/lincolnkermit/eyefinder/blob/main/api/cameras.js): `api/cameras.js`
- [Admin API](https://github.com/lincolnkermit/eyefinder/blob/main/api/admin.js): `api/admin.js`
- [Access API](https://github.com/lincolnkermit/eyefinder/blob/main/api/auth.js): `api/auth.js`
- [Health cron API](https://github.com/lincolnkermit/eyefinder/blob/main/api/cron.js): `api/cron.js`
- [Metrics API](https://github.com/lincolnkermit/eyefinder/blob/main/api/metrics.js): `api/metrics.js`

### Camera and Security Services

- [Camera records](https://github.com/lincolnkermit/eyefinder/blob/main/lib/seed.js): `lib/seed.js`
- [Stream health checks](https://github.com/lincolnkermit/eyefinder/blob/main/lib/scraper.js): `lib/scraper.js`
- [Access and validation](https://github.com/lincolnkermit/eyefinder/blob/main/lib/security.js): `lib/security.js`

### Persistence and Telemetry

- [Camera store](https://github.com/lincolnkermit/eyefinder/blob/main/lib/db.js): `lib/db.js`
- [Site settings](https://github.com/lincolnkermit/eyefinder/blob/main/data/settings.json): `data/settings.json`
- [Traffic telemetry](https://github.com/lincolnkermit/eyefinder/blob/main/lib/metrics.js): `lib/metrics.js`

### Other components

- **Map visitor**
- **Site operator**
- **Supabase / PostgreSQL**
- [Local camera files](https://github.com/lincolnkermit/eyefinder/blob/main/data/cameras.json): `data/cameras.json`
- **Public camera streams**
- **Nominatim geocoder**
- **Vercel scheduler**

## Connections

- Map visitor → Camera map: opens map (evidence: `README.md`)
- Camera map → Camera API: loads cameras
- Camera map → Public camera streams: opens feed (evidence: `README.md`)
- Site operator → Admin portal: manages cameras (evidence: `README.md`)
- Admin portal → Admin API: admin actions
- HTTP server → Camera API: routes requests (evidence: `server.js`)
- HTTP server → Health cron API: routes requests (evidence: `server.js`)
- HTTP server → Admin API: routes requests (evidence: `server.js`)
- HTTP server → Metrics API: routes requests (evidence: `server.js`)
- HTTP server → Access API: routes requests (evidence: `server.js`)
- Camera API → Camera store: reads and writes (evidence: `api/cameras.js`)
- Camera API → Access and validation: checks access (evidence: `api/cameras.js`)
- Camera API → Camera records: loads seed (evidence: `api/cameras.js`)
- Admin API → Camera store: manages records (evidence: `api/admin.js`)
- Admin API → Access and validation: checks access (evidence: `api/admin.js`)
- Admin API → Stream health checks: uses probe (evidence: `api/admin.js`)
- Admin API → Camera records: loads seed (evidence: `api/admin.js`)
- Admin API → Nominatim geocoder: geocodes addresses (evidence: `api/admin.js`)
- Access API → Access and validation: verifies passkey (evidence: `api/auth.js`)
- Access API → Site settings: reads settings
- Health cron API → Camera store: loads and saves (evidence: `api/cron.js`)
- Health cron API → Stream health checks: checks streams (evidence: `api/cron.js`)
- Health cron API → Camera records: loads fallback (evidence: `api/cron.js`)
- Vercel scheduler → Health cron API: invokes scheduled check (evidence: `README.md`)
- Stream health checks → Access and validation: validates URLs (evidence: `lib/scraper.js`)
- Stream health checks → Public camera streams: probes streams (evidence: `lib/scraper.js`)
- Camera store → Camera records: falls back to seed (evidence: `lib/db.js`)
- Camera store → Supabase / PostgreSQL: reads and writes (evidence: `lib/db.js`)
- Camera store → Local camera files: falls back locally (evidence: `lib/db.js`)
- Metrics API → Traffic telemetry: records and summarizes (evidence: `api/metrics.js`)
- Metrics API → Access and validation: checks admin access (evidence: `api/metrics.js`)
