CityScope
A fast, beautiful city weather and information app. Search any city and see
its current weather, hourly and 7-day forecast, air quality, local time, and
currency — all in one dashboard, with no account or login required.
Originally built as a small Ballerina "integration" project for the WSO2
Engineering Intern application; rebuilt into a full product: the Ballerina
backend now runs a versioned, cached, rate-limited API, and the frontend is a
complete multi-view weather app instead of a single search box.
Live demo: https://cityscope-stephan.vercel.app (the first request after a quiet spell takes a few extra seconds while the backend wakes up)
Screenshots
Home dashboard — current weather, hourly/daily forecast, air quality,
currency, and analytics for one city:
Compare view — current conditions for 2–4 cities side by side:
Features
- City search with autocomplete and disambiguation (e.g. "Colombo" is a
city in both Sri Lanka and Brazil — search shows both, and picking one is
unambiguous even though both share a name)
- Current weather — temperature, feels-like, humidity, wind, pressure,
visibility, UV index, sunrise/sunset
- Hourly forecast (next 24h) with a temperature chart
- 7-day forecast
- Air quality (US AQI, PM2.5, PM10, ozone, plain-language category)
- Local time & timezone, computed from the city's real UTC offset — never
guessed from longitude
- Currency display and a live converter between any two currencies
- Interactive map to search and jump to a city
- City comparison (2–4 cities, side by side, with a chart)
- Weather analytics — 7-day temperature/rain trend charts and range stats
- Travel snapshot — a simple, rule-based read on today's conditions
(explicitly not AI — see Technical decisions)
- Recent searches & pinned cities, stored in
localStorage only
- Light/dark mode and °C/°F, the latter defaulting to whichever unit
the searched city's own country actually uses (Celsius almost everywhere,
Fahrenheit for the US and a handful of others) until you override it
- No login, no account, no paywall — everything works immediately
Tech stack
- Backend: Ballerina (Swan Lake) — HTTP service, concurrent upstream
calls, in-memory TTL caching, fixed-window rate limiting, unit tests
- Frontend: vanilla HTML/CSS/JS, no framework, no build step
- Map: Leaflet + Esri (ArcGIS Online) World Dark Gray Base tiles
- Data: Open-Meteo (geocoding, forecast, air
quality) and open.er-api.com (currency)
— both free and keyless
Third-party services & licenses
| Asset | License / tier | Attribution |
|---|
| Leaflet 1.9.4 (map library, loaded from the unpkg CDN) | BSD-2-Clause | Not required on-page |
| Esri World Dark Gray Base map tiles | Free, keyless basemap tier | Required — rendered automatically by Leaflet's attribution control on the Map view ("Esri — Esri, HERE, Garmin, © OpenStreetMap contributors, and the GIS user community") |
| Open-Meteo (weather, air quality, geocoding) | Free tier | Called server-side only |
| open.er-api.com (currency) | Free tier | Called server-side only |
Icons are hand-authored inline SVG (no icon font/library). No webfonts are
loaded — the UI uses the system font stack only. No raster images are used in
the frontend. Full detail on what each third party can see, and what
CityScope's own hosting logs, is in the Privacy Policy.
Architecture
flowchart TD
UI["CityScope Frontend<br/>vanilla JS, multi-view"] --> API["Ballerina API<br/>/api/v1 · cache + rate limit"]
API --> GEO["Geocoding<br/>(Open-Meteo)"]
API --> WX["Weather<br/>(Open-Meteo)"]
API --> AQ["Air Quality<br/>(Open-Meteo)"]
API --> FX["Currency<br/>(open.er-api.com)"]
classDef stage fill:#6C5CE7,stroke:#4834B0,color:#fff
class API stage
GET /api/v1/snapshot/{city} geocodes the city once, then fires the weather,
air quality, and currency requests concurrently with Ballerina's
start/wait — none of the three depends on another's result, so they run
in parallel instead of one after another. Weather is essential (its failure
fails the request); air quality and currency are each optional — if one
upstream is down, the snapshot still returns with that field set to null
rather than failing outright.
Caching strategy
A small hand-rolled in-memory TTL cache sits in front of every upstream call,
keyed by coordinates (weather/air quality) or city name (geocoding) or
currency code (FX rates) — never by this service's own derived response
shape, so a cache hit still recomputes weather descriptions/AQI categories
fresh while skipping the network round-trip.
| Data | TTL | Why |
|---|
| Geocoding | 24h | A city's coordinates don't move |
| Weather | 5 min | Balances freshness against upstream load |
| Air quality | 10 min | Changes more slowly than weather |
| Currency | 30 min | Exchange rates update a few times a day at most |
Rate limiting
A single global fixed-window limiter (60 requests/minute by default,
configurable — see backend/Config.toml.example) protects the free-tier
upstream APIs, which this whole service shares one quota with regardless of
which caller triggered the request. It's deliberately global rather than
per-client: per-IP limiting would need every resource function to switch to
the manual http:Caller-response pattern instead of typed returns, a much
larger change for a demo-scale service.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
