105 lines
5.1 KiB
Markdown
105 lines
5.1 KiB
Markdown
# 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*
|