CDP Adaptation & Action Explorer

A unified platform to synthesize fragmented environmental hazard data and siloed resilience best practices, helping cities, states, regions, and their partners drive Earth-positive action.

Deployment URLs are managed in Google Cloud Run. The VitePress docs are served from https://cdp-action-explorer.net/docs/. See docs/deployment.md for the current deployment topology.

📱 Preview

Explore local climate hazards and adaptation projects worldwide.

🚀 Getting Started

Please see SETUP.md for detailed installation instructions.

🏗 Architecture & Core Concepts

Overall App Structure

cdp-adapt-ex/
├── backend/           # FastAPI (Python 3.13)
│   ├── app/
│   │   ├── api/v1/    # Endpoint definitions & Pydantic schemas
│   │   ├── services/  # Business logic and external service clients
│   │   │   └── clients/database/ # Data Access Layer (Repositories)
│   │   ├── models/    # SQLModel database models
│   │   ├── shared/    # Config, security, logging
│   │   └── main.py    # FastAPI entry point
│   ├── pyproject.toml # Package management via `uv`
│   └── tests/         # Pytest suite
├── ai-server/         # Standalone OpenAI-compatible Ask the AI Explorer service
├── client/            # Auto-generated TypeScript API client
│   ├── scripts/       # Generation & patching scripts
│   └── src/           # Generated models and services
├── frontend/          # Angular 20 & Tailwind CSS
│   ├── src/app/
│   │   ├── core/      # Singleton services, guards, interceptors
│   │   ├── features/  # Domain features (Map, Chat, Hazard, etc.)
│   │   └── shared/    # Reusable components & UI building blocks
│   └── tailwind.config.js
├── data/              # Seed data, migration sources, and climate layer scripts
├── scripts/           # Cities, States and Regions BQ data pipeline (notebooks, BQ-side SQL helpers, validation)
├── tools/             # Repo-level developer utilities (docs build, frontend data sync)
├── docs/              # Canonical handoff and technical documentation
└── Makefile           # Project automation (install, test, lint)

The Cities, States and Regions 2025 data pipeline (notebook -> BQ -> Cloud SQL) is documented in docs/data_pipeline.md, which covers the four pipeline stages and the CloudSQL migration.

Infrastructure & Cloud Architecture

The platform is built on Google Cloud Platform (GCP).

• Compute (Cloud Run): The Angular frontend, FastAPI backend, and standalone AI server are containerized and hosted on Cloud Run.
• Database (Cloud SQL): PostgreSQL stores Cities, States and Regions analytical tables plus app-owned onboarding telemetry.
• AI & LLM: Ask the AI Explorer is served by the standalone ai-server, which exposes OpenAI-compatible chat and follow-up endpoints backed by Gemini.
• Geospatial: Google Maps powers the UI map, while Google Earth Engine provides hazard layer tiles through the backend.

🚀 Deployment

For detailed information on automatic CI/CD pipelines and manual deployment steps, please refer to the Deployment Documentation.

📚 Documentation Index

Topic	Description
🛠 SETUP.md	Step-by-step local development environment setup.
🤝 CONTRIBUTING.md	Guidelines for reporting bugs, suggesting features, and PR workflows.
📚 Docs Index	Canonical documentation map for backend, AI server, data, deployment, and translation.
🚀 Deployment Guide	CI/CD pipelines, Cloud Run configuration, and manual deployment.
🧪 Testing	Overview of testing strategies, or module-specific details in Backend Tests and Frontend Tests.
⚙️ Backend Docs	FastAPI architecture, services, and database repository pattern.
🤖 AI Server Docs	Ask the AI Explorer routes, prompt workflow, and testing notes.
📊 Data & DB Docs	Database schema, seed data, and data management details.
🔄 Data Pipeline	End-to-end runbook for full application data updates (BQ notebooks → Cloud SQL migration).
🎨 Frontend Docs	Angular 20 structure, Tailwind CSS usage, and component patterns.
🔒 SECURITY.md	Vulnerability reporting and security policies.
📄 LICENSE	Project licensing information.