Architecture Overview

System Architecture

TerraGuard is composed of five deployable services that work together to ingest, enrich, analyze, and present disaster event data, plus a search layer that runs inside the Backend API. Each service is independently deployable and communicates over HTTP APIs.

Service Responsibilities

tg-event-processor (Go)

The event processor handles deterministic ingestion of disaster events from external data sources. It uses a pluggable adapter pattern — each data source (GDACS, USGS, NHC) has its own adapter that normalizes raw feed data into a common event schema. The processor runs on a polling schedule, deduplicates incoming events against existing records, and writes normalized events directly to PostgreSQL.

tg-backend-api (Python/FastAPI)

The backend API is the central orchestration layer. It serves the REST API consumed by the frontend, manages AI agent workflows, coordinates the enrichment pipeline through Inngest jobs, handles authentication via Clerk, and delivers notifications. It depends on all three support services at runtime.

tg-frontend (Next.js 15)

The frontend provides the user interface — an interactive map with disaster event markers, filtering and search, event detail views, AI summary generation, knowledge base browsing, report creation, and team management. It communicates exclusively with the backend API.

Search Layer (inside the Backend API)

Search is not a standalone service. It runs inside the Backend API as the app/common/search_providers.py module, exposing search_web() and search_news(). The module calls Serper.dev (Google web + news) as the primary provider and falls back to Brave Search only when Serper errors. Both providers normalize into a single SearchResult shape. There is no SearXNG metasearch engine and no Tor proxy in the request path.

tg-web-crawler-api (Go + Python)

The web crawler fetches and extracts content from URLs discovered by the search layer. The Go server manages an async job queue with bounded concurrency, while a Python worker (using crawl4ai) handles browser-based crawling. A 4-level strategy fallback chain (Basic, Patient, Undetected with Xvfb, Proxy) ensures high extraction success rates.

geopop-api (Rust)

The GeoPop API provides reverse geocoding, population density analysis, and exposure assessment. Given coordinates and a radius, it returns affected population estimates, country identification, administrative regions, and land/sea detection. Built in Rust for high performance on large population grid datasets.

Data Flow

The platform processes disaster data through four stages:

1. Ingestion

The event processor polls GDACS, USGS, and NHC on configured intervals. Each adapter parses the source-specific format (XML feeds, JSON APIs, advisory bulletins) and produces a normalized event record. Events are matched against existing records by source ID to handle updates.

2. Enrichment

When new or updated events arrive, the backend API triggers an Inngest-driven enrichment pipeline:

1. GeoPop Query — Reverse geocode the event location, assess population exposure
2. Web Search — The backend's search layer (Serper primary, Brave fallback) finds relevant news articles and situation reports
3. Content Validation — An LLM-based news filter agent evaluates each search result for relevance
4. Web Crawling — Validated URLs are sent to the crawler for full content extraction
5. Vector Indexing — Extracted content is embedded and stored in pgVector for semantic search

3. Analysis & Scoring

Events are scored and prioritized based on multiple factors: source alert level, population exposure, event measurements (magnitude, wind speed, etc.), and the volume and severity of corroborating news. This scoring feeds into the notification engine to determine which teams should be alerted.

4. Presentation & Notification

The frontend presents enriched events through an interactive map and list interface. The notification engine evaluates organization matrices to route alerts to the appropriate teams via email and Telegram, with scheduled follow-ups at configurable intervals.

Port Assignments

Infrastructure Dependencies

Next Steps

• Quick Start — Run the platform locally
• System Architecture (Detailed) — Deep dive into service internals
• Event Processing Pipeline — Detailed ingestion flow