arah2/.planning/codebase/INTEGRATIONS.md

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/... — legacy remote placeholders in mockups (tool-generated assets). The logo placeholder has been replaced with the local project logo (assets/MASTER_FILE-arah2_logo.svg); any remaining remote URLs are non-logo placeholders.

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