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.
Open Afterglow ↗ · iPhone & Mac · Architecture · Quick start · API
Peach |
Coral |
Rose |
Lavender |
Twilight |
|---|---|---|---|---|
| 🟧 | 🟠 | 🩷 | 🟪 | 🌌 |
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.
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.
| 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.
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+.
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.
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.
| 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 |
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
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 |
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 8000In another terminal:
pnpm install
pnpm --dir apps/web devGenerate 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.
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.
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 /readyThe interactive FastAPI schema is available at /docs.
# 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.jsCI 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:forecastThe 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/artifactsAny 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.
- 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.
- 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
- Public website: afterglow.jonzhang.dev
- iPhone and Mac: native builds from the repository, public distribution pending
- Local: Docker Compose or native processes
- AWS-ready: ECS Fargate, RDS PostgreSQL, ElastiCache Redis, private S3, ECR, CloudWatch, and Terraform
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.