# External Integrations

**Analysis Date:** 2026-10-21

## Project Maturity Note

There is **no running integration code** in this repository yet — no backend, no SDK packages, no environment files. This document is based on what is *actually wired* in the static mockups plus the integration architecture explicitly declared in `IDEAS.md` ("Architecture Overview") and `DESIGN.md` ("Interaction Flows"). Items marked **[actual]** are live CDN dependencies; items marked **[planned]** are targets for the first implementation and should be verified/re-selected when that phase is planned.

## APIs & External Services

**Bot Transport (planned — the product's primary "frontend"):**
- Telegram Bot API — commands and inline queries for incident reports and navigation (`IDEAS.md`: "Telegram-first")
  - SDK/Client: not chosen yet; no package installed
  - Auth: bot token (env var to be introduced; none exists)
  - Command surface from `DESIGN.md` / `IDEAS.md`: `/report accident|traffic|hazard` with location share, `/navigate origin → destination`, geohash-style broadcast of nearby events

**Routing (planned):**
- OSRM — route computation with "dynamic traffic weighting" (`IDEAS.md`; also `DESIGN.md` flow: `/navigate origin → destination → OSRM route → text directions + map snapshot`)
  - SDK/Client: none; OSRM is a plain HTTP API
  - Auth: none required for self-hosted; hosting decision (self-host vs public server) not yet made

**Map Tiles (planned):**
- Maptiler — map tiles for grayscale map snapshots (`IDEAS.md`, `DESIGN.md` "Map Snapshots: Grayscale tiles with accent overlays")
  - SDK/Client: none; HTTP tile API
  - Auth: API key (to be added to env config)

**CDN services actually referenced by the mockups [actual]:**
- `cdn.tailwindcss.com` — Tailwind Play CDN script, in all four screens (`*`/`code.html`)
- `fonts.googleapis.com` + `fonts.gstatic.com` — Geist, Space Grotesk, Material Symbols Outlined
- `lh3.googleusercontent.com/aida/...` — placeholder screenshot URLs embedded in mockups (tool-generated assets, should be replaced by project-generated images before reuse)

**Email (planned, low priority):**
- Resend — transactional email (`IDEAS.md`). Purpose is not specified further; may not be needed for the MVP.

## Data Storage

**Databases:**
- Neon — serverless Postgres with PostGIS extension for spatial queries (`IDEAS.md`) [planned]
  - Connection: env var to be introduced (none exists)
  - Client/ORM: none chosen yet
  - Spatial needs: storing incident reports with coordinates + "broadcast nearby" radius queries (PostGIS ` geography` point search)

**File Storage:**
- Cloudflare R2 — blob storage for map snapshots/UAV-style images (`IDEAS.md`) [planned]
  - Current mockup screens store images as static `screen.png` files locally; no storage integrated

**Caching:**
- None integrated; none planned explicitly. Route/traffic data caching is implied if OSRM traffic weighting is implemented, but not documented.

## Authentication & Identity

**Auth Provider:**
- None [actual]
- Planned: Telegram identity is the implicit identity layer — the bot sees `chat_id`/`user_id` directly from Telegram (`IDEAS.md` gamification: points and leaderboards via Telegram bot). No separate auth system is documented; a first implementation should treat Telegram user IDs as the primary key and require no passwords.

## Monitoring & Observability

**Error Tracking:**
- None [actual]

**Metrics (planned):**
- Prometheus + Grafana — monitoring stack named in `IDEAS.md`; exporters/what-to-observe not yet defined.

**Logs:**
- Not detected. No logging framework or convention exists yet.

## CI/CD & Deployment

**Hosting (planned):**
- Cloudflare Pages — for the optional PWA (`IDEAS.md`). Backend bot hosting platform is **undecided** (no doc names one).

**CI Pipeline:**
- None [actual]. No workflow/CI config files exist.

## Webhooks & Callbacks

**Incoming:**
- None [actual]
- Planned: Telegram webhook for bot updates (polling vs webhook not yet decided — choose during first backend phase)

**Outgoing:**
- None [actual]
- Planned: none required by design; bot notifications to users are bot API calls, not webhooks

## Environment Configuration

**Required env vars (none exist yet — this is the target list for the first backend phase):**
- Telegram bot token
- Neon database URL (with `?sslmode=require` and PostGIS-enabled DB)
- Maptiler API key
- OSRM base URL (+ optional traffic-weighting config)
- Cloudflare R2 credentials (account ID, access key, secret, bucket) — **only if** snapshot storage is implemented in R2
- Resend API key (optional; likely defer avoid until email feature is justified)

**Secrets location:**
- Nothing exists. `.env` files are not present and should **not** be committed when introduced; no `.gitignore` exists yet — create one before adding any secret to disk (the repo is not currently a git repository).

## Gamification (planned feature, needs platform choices)

- Points for validated reports + leaderboards served through the Telegram bot (`IDEAS.md`). Requires: user scoring tables in Neon Postgres; no external service implied beyond Telegram itself.

---

*Integration audit: 2026-10-21*