Dawnward

Arrive ready, not wrecked.

Dawnward is a free jet lag optimization app that generates personalized schedules for adapting to new timezones. It uses the same circadian science models found in clinical research—light exposure timing, melatonin, and caffeine strategy—to help you shift your body clock before and after travel.

Live at dawnward.app

---

How It Works

Your body has a master clock (the suprachiasmatic nucleus) that controls when you feel alert and when you feel sleepy. Jet lag happens when this internal clock is out of sync with your destination timezone.

Dawnward uses the Forger99 circadian model to calculate:

• When to seek light — Bright light at the right time shifts your clock forward or backward
• When to avoid light — Light at the wrong time can shift you the wrong direction
• Melatonin timing — Low-dose melatonin (0.5mg) taken at the right time accelerates adaptation
• Caffeine strategy — When coffee helps alertness vs. when it disrupts sleep

The app generates a day-by-day schedule starting several days before your flight, accounting for your normal sleep schedule, flight times, and how aggressive you want the shift to be.

---

Features

• Trip planning — Enter your origin, destination, and flight times
• Multi-leg trips — Chain flights (SFO → NRT → SIN) with proper layover handling
• Prep days — Start shifting 1-7 days before departure
• Schedule intensity — Choose gentle, balanced, or aggressive adaptation
• Mobile-first UI — Check your schedule on your phone
• No account required — Generate schedules without signing up
• User accounts — Sign in with Google to save trips and preferences
• Trip history — View and manage your saved trips
• Shareable URLs — Share your schedule with travel companions
• Google Calendar sync — Push your schedule to Google Calendar with one click
• Saved preferences — Set default wake/sleep times and intervention preferences

---

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
Styling	Tailwind CSS v4, shadcn/ui
Circadian Model	Python (Forger99 via Arcascope)
Database	Prisma Postgres
Auth	NextAuth.js v5 (Google)
Hosting	Vercel

---

Development

Prerequisites

• Bun (or Node.js 20+)
• Python 3.9+

Setup

# Install dependencies
bun install
pip install -r requirements.txt  # Python deps for circadian model

# Run development server
bun dev

Open http://localhost:3000.

Environment Variables

For auth features, create .env.development.local with:

# Database (Prisma Postgres)
DATABASE_URL="postgres://..."

# Auth.js v5
AUTH_SECRET="<generate with: openssl rand -base64 32>"

# Google OAuth
GOOGLE_CLIENT_ID="<from Google Cloud Console>"
GOOGLE_CLIENT_SECRET="<from Google Cloud Console>"

To set up Google OAuth:

1. Go to Google Cloud Console
2. Create OAuth 2.0 credentials (Web application)
3. Add redirect URI: http://localhost:3000/api/auth/callback/google

Then run migrations:

bun prisma migrate dev

Project Structure

src/
├── app/              # Next.js pages and API routes
│   ├── trips/        # Trip history (auth required)
│   ├── settings/     # User preferences (auth required)
│   ├── science/      # Science explainer page
│   └── api/          # API endpoints
├── components/       # React components
│   └── ui/           # shadcn/ui components
├── lib/              # Utilities and helpers
└── types/            # TypeScript types

api/_python/
├── circadian/        # Schedule generation
│   ├── science/      # PRC, markers, sleep pressure
│   └── scheduling/   # Phase generator, intervention planner
└── tests/            # Python tests

design_docs/          # Specifications and design decisions

---

MCP Interface (for AI Assistants)

Dawnward exposes a Model Context Protocol (MCP) endpoint that allows AI assistants like Claude to answer jet lag questions using real circadian science.

Endpoint: POST https://dawnward.app/api/mcp

Available Tools

Tool	Description
calculate_phase_shift	Quick timezone shift calculation and difficulty assessment
get_adaptation_plan	Full day-by-day adaptation schedule with interventions

Example: Calculate Phase Shift

curl -X POST https://dawnward.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "calculate_phase_shift",
      "arguments": {
        "origin_timezone": "America/Los_Angeles",
        "destination_timezone": "Asia/Tokyo"
      }
    }
  }'

Example: Get Adaptation Plan

curl -X POST https://dawnward.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_adaptation_plan",
      "arguments": {
        "origin_timezone": "America/Los_Angeles",
        "destination_timezone": "Asia/Tokyo",
        "departure_datetime": "2026-02-15T11:30",
        "arrival_datetime": "2026-02-16T15:45",
        "prep_days": 3,
        "usual_wake_time": "07:00",
        "usual_sleep_time": "23:00"
      }
    }
  }'

Rate Limiting

• 100 requests per hour per IP address
• No authentication required

---

The Science

Dawnward's approach is based on published circadian research:

• Phase Response Curves — Khalsa et al. (2003) for light, Burgess et al. (2010) for melatonin
• Two-Process Model — Borbély (1982) for sleep pressure
• Shift limits — Eastman & Burgess guidelines (~1-1.5h/day safe shifting)

The algorithm estimates your circadian phase (CBTmin) from your sleep schedule, then calculates optimal intervention windows using phase response curves. It respects physiological limits to avoid antidromic shifts (shifting the wrong direction).

For full details, see design_docs/science-methodology.md.

---

Contributing

Contributions welcome. Before submitting a PR:

bun run lint
bun run typecheck
bun run test:run
bun run lint:python
bun run test:python

---

Credits

• Circadian modeling — Based on the Arcascope circadian library
• UI components — shadcn/ui
• Icons — Lucide

---

Disclaimer

Dawnward is not medical advice. Consult a healthcare provider for sleep disorders or medical conditions. The schedules are recommendations based on circadian science models—individual results vary.