Skip to content

About

AI-assisted sunset color forecasting with live weather, solar geometry, seven-day outlooks, predicted palettes, vibrancy scores, and ideal viewing windows. Upload the real sky for private color comparison and optional AI interpretation. A bilingual Next.js and FastAPI experience powered by Open-Meteo and OpenAI.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Afterglow sunset logo

afterglow.

View the golden hour.

Sunset intelligence for people who appreciate beautiful skies.
Afterglow predicts the evening palette from live atmospheric data and lets you compare it with a sunset photo. The website also offers an optional AI interpretation.

Live Site Next.js FastAPI OpenAI Tests

Open Afterglow ↗ · iPhone & Mac · Architecture · Quick start · API


Peach Coral Rose Lavender Twilight
🟧 🟠 🩷 🟪 🌌

The sky, before it happens

Traditional weather apps tell you whether it will rain. Afterglow is designed around the emotional decision hiding underneath the forecast:

Open Afterglow → see tonight’s sky → decide whether to go outside.

For any supported location, Afterglow presents:

  • a five-color predicted sunset palette;
  • a 0–100 vibrancy score and confidence estimate;
  • the best local-time viewing window;
  • cloud-layer, humidity, precipitation, and visibility context;
  • a seven-evening outlook with the strongest sunset highlighted;
  • private photo verification using perceptual color comparison; and
  • an optional OpenAI vision reading on the website with a color story, atmospheric interpretation, forecast match, and photography tip.

The sunset visualization is explicitly an interpretation of forecast conditions, not a fabricated photograph of the future.

AI sky readings

Afterglow's forecast itself remains a transparent atmospheric heuristic. On the website, the optional AI reading runs after a visitor selects a sunset photo and chooses Read this sky with AI. The vision reading describes the visible palette and mood, offers a cautious atmospheric interpretation, compares the photograph with the forecast, suggests a photography technique, and returns a visual match score.

The initial palette comparison never leaves the browser. For an AI reading, the browser resizes the selected image before sending it to the Site worker. The OpenAI credential stays server-side, requests are throttled, Afterglow does not persist the image, and the upstream request uses store: false.

Experience

Tonight The week ahead Close the loop + AI
Live local sunset time, palette, vibrancy, confidence, and a natural-language reading. Seven comparable evenings with uncertainty that grows with forecast horizon. Compare colors privately, then optionally ask AI to interpret the photographed sky against the forecast.

The interface is mobile-first, keyboard accessible, reduced-motion aware, and intentionally unlike a conventional weather dashboard.

To share a city, choose Change location in Tonight’s Forecast, then select Share forecast and paste the copied link. It opens directly to the selected city’s latest forecast. Links made from your device location use approximate coordinates.

Afterglow on iPhone and Mac

The public website is available now. The SwiftUI apps for iPhone and Mac are in this repository and pending public distribution. Both use the same production forecast API and work without sign-in.

Choose a city or use approximate device location through Core Location. The apps keep a same-day forecast on the device for outages. Photo comparison runs on-device, using Apple Vision to help mask foreground subjects and perceptual color distance to compare the palettes. Choose a photo from your library on iPhone or open an image file on Mac.

The Apple app setup guide covers both native targets, iOS 17+ and macOS 14+.

Architecture

Afterglow system architecture
Click the diagram for a full-size view.

The public Next.js site and native SwiftUI clients share a hosted Site Worker. It computes forecasts from Open-Meteo or 7Timer and saves validated weather in D1 for outages. Photo comparison runs locally in each client. The web app can also request an optional OpenAI reading through the worker.

The repository also contains a FastAPI modular monolith for durable snapshots, queues, private object storage, and self-hosted or AWS deployments.

Layer Responsibilities
Next.js web Editorial UI, location search, query lifecycle, deterministic sky visualization, responsive interactions
SwiftUI iPhone and Mac apps City selection, optional Core Location, live and saved forecasts, an interactive sunset timeline, and on-device Vision-assisted photo comparison
Hosted site worker Shared forecast API, weather validation and failover, D1 forecast snapshots, static assets, optional AI analysis
FastAPI application Validation, forecast orchestration, immutable snapshots, uploads, evaluations, OpenAPI
Forecast domain Solar position, sunset windows, atmospheric feature engineering, palettes, vibrancy, confidence
Data layer PostgreSQL records, Redis cache and RQ jobs, local/S3-compatible private image storage
Offline ML Leakage-safe feature building, time/location splits, model training, artifact and metric output
Infrastructure Docker Compose locally; ECS, RDS, ElastiCache, S3, ECR, and CloudWatch-ready Terraform for AWS

Read the deeper architecture notes and deployment guide.

How the forecast works

location
   ↓
live weather + local sunset time (Open-Meteo or 7Timer backup)
   ↓
cloud layers · humidity · visibility · precipitation · forecast horizon
   ↓
solar geometry + atmospheric heuristic baseline
   ↓
palette · vibrancy · confidence · best viewing window

The self-hosted API can also store an immutable prediction snapshot for observed-photo evaluation.

The production model is deliberately labeled heuristic. Weather APIs do not directly forecast sunset colors, and this project does not claim trained-model performance without a representative labeled dataset and a real held-out evaluation.

Technology

Product Data and intelligence Delivery
Next.js 15, React 19, TypeScript Python 3.12, FastAPI, Pydantic Docker and Docker Compose
SwiftUI for iPhone and Mac Core Location and Apple Vision XcodeGen and Xcode
TanStack Query, Motion, Tailwind CSS SQLAlchemy, Alembic, PostgreSQL AWS ECS Fargate starter
Accessible responsive components Redis, RQ, Pillow, scikit-learn Terraform and GitHub Actions
Deterministic CSS sky renderer Open-Meteo weather and geocoding, 7Timer backup Public afterglow.jonzhang.dev worker deployment
Bilingual English/Chinese experience OpenAI vision sky interpretation Server-side secrets and request throttling

Repository map

afterglow/
├── apps/web/                  # Next.js App Router experience
├── apps/ios/                  # Shared SwiftUI app source and iPhone/Mac targets
├── services/site-worker/      # Hosted forecast API, D1 snapshots, and optional AI
├── scripts/                   # Site build, preview, and production smoke checks
├── services/api/              # FastAPI modular monolith + migrations
├── services/worker/           # Redis/RQ background jobs
├── ml/
│   ├── features/              # Reproducible feature construction
│   ├── training/              # Leakage-aware training entrypoint
│   └── evaluation/            # Model promotion contract
├── infrastructure/terraform/  # AWS production starter
├── tests/load/                # k6 scenario
├── docs/                      # Architecture and deployment notes
├── docker-compose.yml
└── .env.example

Quick start

Docker Compose

The complete local stack includes the web app, API, PostgreSQL, Redis, and the RQ worker.

cp .env.example .env
docker compose up --build
Service URL
Afterglow http://localhost:3000
API http://localhost:8000
OpenAPI http://localhost:8000/docs

Web stack without Docker

Use Python 3.12+, Node.js 22+, and pnpm.

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate

pip install -r services/api/requirements.txt
alembic -c services/api/alembic.ini upgrade head
uvicorn services.api.app.main:app --reload --port 8000

In another terminal:

pnpm install
pnpm --dir apps/web dev

Native iPhone and Mac apps

Generate the Xcode project from apps/ios/project.yml. The Apple app setup guide has the build and test instructions for the Afterglow and AfterglowMac schemes.

Configuration

Copy .env.example and adjust only what your environment needs.

Variable Purpose Local default
NEXT_PUBLIC_API_URL Browser-facing FastAPI origin http://localhost:8000
NEXT_PUBLIC_WEATHER_PROXY Same-origin weather proxy used by the hosted Site unset (direct locally)
NEXT_PUBLIC_SITE_URL Canonical production origin https://afterglow.jonzhang.dev
DATABASE_URL SQLAlchemy connection SQLite natively; PostgreSQL in Compose
REDIS_URL Cache, locks, and RQ redis://localhost:6379/0
UPLOAD_DIRECTORY Development photo storage data/uploads
MAX_UPLOAD_BYTES Upload ceiling 10485760
S3_BUCKET Enables private S3-compatible storage unset
S3_ENDPOINT_URL Optional compatible endpoint unset
OPEN_METEO_TIMEOUT_SECONDS Upstream request timeout 10
ALLOWED_ORIGINS CORS allowlist http://localhost:3000
OPENAI_API_KEY Optional server-side AI sky readings unset
OPENAI_MODEL Vision-capable Responses API model gpt-4.1-mini

The hosted /api/v1/forecast/weekly endpoint calculates the palette, vibrancy, and viewing window. It validates Open-Meteo weather and tries 7Timer when the first source is unavailable or incomplete. The backup uses three-hour samples and omits visibility and rain probability. If both feeds fail, the worker can return the last valid forecast for the same city and local day from D1, with its original retrieval time, for up to 12 hours. Web city search can use a bundled index adapted from GeoNames under CC BY 4.0. The optional OpenAI key is a protected runtime secret. AI photo readings consume OpenAI API usage.

API surface

The hosted website and native clients use GET /api/v1/forecast/weekly and GET /api/weather/geocoding. The hosted website also uses POST /api/ai/analyze for optional readings.

The self-hosted FastAPI service provides the following endpoints:

GET  /api/v1/locations/search?q=...
GET  /api/v1/forecast
GET  /api/v1/forecast/weekly
GET  /api/v1/forecast/{prediction_id}
POST /api/v1/observations
GET  /api/v1/evaluations/{prediction_id}
GET  /health
GET  /ready

The interactive FastAPI schema is available at /docs.

Quality

# Backend unit and API integration tests
pytest

# Frontend component tests and production build
pnpm --dir apps/web test
pnpm --dir apps/web build
pnpm test:worker

# Browser and load checks
pnpm --dir apps/web test:e2e
k6 run tests/load/forecast.js

CI checks the Python API and migration, then builds the hosted Worker and runs the web, storage, and browser tests against that build. The production smoke check opens a real city share link and checks the rendered sunset and forecast's local date.

For native development, see the Apple app test instructions.

pnpm --dir apps/web exec playwright install chromium
pnpm smoke:forecast

ML contract

The trained-model pipeline is present but intentionally not promoted to production without real labels.

python -m ml.training.train \
  --input data/labeled_sunsets.csv \
  --output ml/artifacts

Any candidate must beat the deterministic baseline using splits separated by both time and location. Evaluation should report palette Delta E, dominant-color accuracy, vibrancy MAE, confidence calibration, and performance across location, season, camera source, and forecast horizon.

See the complete evaluation contract.

Important limitations

  • Ordinary weather forecasts do not fully observe aerosols, smoke layers, terrain obstruction, or localized marine layers.
  • Camera exposure, white balance, HDR, editing, crop, and foreground pixels affect observed-color evaluation.
  • The current CIE76 nearest-palette comparison is product feedback, not a scientific accuracy claim.
  • The public worker stores short-lived weather snapshots for outage recovery. The full local/AWS architecture also stores prediction evaluations and supports queues and private object storage.
  • AI sky readings are visual interpretations, not measurements of aerosols, pollution, or safety-critical weather conditions.

Roadmap

  • Build a consented, timestamped, geolocated sunset image dataset
  • Add smoke, aerosol, and terrain-horizon signals where licensing permits
  • Add authenticated personal observation history and deletion controls
  • Calibrate confidence against measured out-of-sample error
  • Promote a trained model only after baseline-beating evaluation

Deployment

Paid infrastructure is never provisioned automatically. Review the deployment guide and current provider pricing before applying Terraform.


Built for the few minutes each day that never happen the same way twice.

afterglow. · View the golden hour.

About

AI-assisted sunset color forecasting with live weather, solar geometry, seven-day outlooks, predicted palettes, vibrancy scores, and ideal viewing windows. Upload the real sky for private color comparison and optional AI interpretation. A bilingual Next.js and FastAPI experience powered by Open-Meteo and OpenAI.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages