# Weather Trip

English | [简体中文](README.zh-CN.md)

[Weather Trip](https://weather-trip.aicake.io) is a bilingual weather travel tool for choosing where to go by forecast. It lets travelers compare global cities by temperature, rain, humidity, weather type, wind, elevation, and travel-friendly comfort signals before they commit to a destination.

## Product

Weather Trip is built for people who know the kind of weather they want, not necessarily the city they want. Instead of opening one city forecast at a time, users can scan a world weather map, filter destinations by future conditions, and compare city forecasts in one place.

The public product has two main tools:

- [World Weather Map](https://weather-trip.aicake.io/weather-map/) shows future weather across selected regions, countries, and cities with map layers for weather, temperature, humidity, precipitation, wind, elevation, and comfort.
- [City Finder](https://weather-trip.aicake.io/city-finder/) lets users set weather preferences first, then find cities that match those preferences over the next forecast window.

Weather Trip is a public data product. The free version is intentionally static: public pages read city indexes, vector map tiles, and weather packages from static files. User requests do not connect to a runtime database and do not call a Worker API.

## Live Site

- Product: [https://weather-trip.aicake.io](https://weather-trip.aicake.io)
- English weather map: [https://weather-trip.aicake.io/weather-map/](https://weather-trip.aicake.io/weather-map/)
- Chinese weather map: [https://weather-trip.aicake.io/zh/weather-map/](https://weather-trip.aicake.io/zh/weather-map/)
- City finder: [https://weather-trip.aicake.io/city-finder/](https://weather-trip.aicake.io/city-finder/)

## Architecture

```text
Astro static build -> Cloudflare Pages
city index + map tiles -> committed public data
weather/current.json + forecast package -> Cloudflare R2
daily refresh -> GitHub Actions
```

The repository is organized around static generation and public runtime assets:

```text
apps/web/       # Astro static public pages; English at / and Chinese at /zh
packages/       # Shared weather types, weather codes, and static wire decoders
data/           # Offline sources, manual inputs, generated assets, and review reports
scripts/        # Tourism destination, country tier, city, map boundary, and weather package generators
docs/           # Product, data flow, runtime, and launch documentation
infra/          # Cloudflare configuration tracked for production resources
```

## Quick Start

```bash
npm install
npm run dev
```

Local development reads committed public data. Public site settings (domain, Umami, public weather data URL) live in `apps/web/src/domain/site-config.ts`. Real `.env.*` files are not committed; use `apps/web/.env.example` for `.env.development` / `.env.production`, and the root `.env.deploy.example` for `.env.deploy.production`. Set `PUBLIC_CARTO_API_KEY` in `apps/web/.env.production`, run `npm run pages:env:sync`, then rebuild and deploy through the Git release workflow. The command syncs allowlisted variables to Pages production without triggering a deployment. Cloudflare tool credentials belong in the root `.env.deploy.production`, separate from Web build variables. See [environment configuration](docs/specs/51-runtime.md#env-与公开配置) for authentication and local development.

## Common Commands

```bash
npm run check
npm run build
npm run static:tourism
npm run static:country-tier-candidates
npm run static:profiles
npm run static:cities
npm run static:geo
npm run static:geo:tiles
```

Low-frequency country tiers, city indexes, and map boundaries are generated by the matching `static:*` scripts and committed to Git. See `docs/specs/31-data-flow.md` for the full data flow.

Weather data is refreshed separately. To fetch Open-Meteo forecasts for the current city list, run:

```bash
npm run weather:refresh -- --source=open-meteo
```

Production uses Cloudflare Pages for `apps/web/dist`, Cloudflare R2 for weather packages, and GitHub Actions for daily refreshes. See `docs/specs/50-launch.md` for launch and rollback details.

## License

Project code is open source under [GPL-3.0](./LICENSE).

The `Weather Trip` name, logo, and domains are not included in the code license. If you fork or build a product from this project, use your own name, logo, and domains, and credit the original project to avoid confusion with the public site.