Nocturn

Transform your sleep into art.

Project Structure

nocturn/
├── backend/           # Python FastAPI backend
│   ├── app/
│   │   ├── main.py    # API entry point
│   │   ├── config.py  # Configuration
│   │   └── providers/ # Oura, Whoop, Apple Health integrations
│   ├── requirements.txt
│   └── .env.example
└── frontend/          # Next.js frontend (coming soon)

Setup

1. Create Python Environment

cd backend
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env with your API credentials

3. Run the API

uvicorn app.main:app --reload --port 8000

Visit http://localhost:8000 to verify it's running.

---

Developer Account Setup

Oura Ring

1. Go to https://cloud.ouraring.com/oauth/applications
2. Sign in with your Oura account
3. Click "Create New Application"
4. Fill in:
   • Application Name: Nocturn
   • Description: Transform sleep data into art
   • Redirect URI: http://localhost:8000/auth/oura/callback
5. Save the Client ID and Client Secret to your .env file

Scopes needed: personal, daily, sleep, heartrate

Whoop

1. Go to https://developer-dashboard.whoop.com
2. Sign in with your Whoop account
3. Create a Team (if you haven't already)
4. Click "Create App"
5. Fill in:
   • App Name: Nocturn
   • Redirect URIs: http://localhost:8000/auth/whoop/callback
   • Scopes: Select all read scopes:
     • read:sleep
     • read:recovery
     • read:cycles
     • read:profile
     • read:body_measurement
6. Save the Client ID and Client Secret to your .env file

---

API Endpoints (Planned)

Auth

• GET /auth/oura/login - Start Oura OAuth flow
• GET /auth/oura/callback - Oura OAuth callback
• GET /auth/whoop/login - Start Whoop OAuth flow
• GET /auth/whoop/callback - Whoop OAuth callback

Sleep Data

• GET /sleep/nights - List available nights
• GET /sleep/night/{date} - Get single night's data

Generation

• POST /generate/interpret - Interpret sleep data
• POST /generate/image - Generate art from interpretation

---

Tech Stack

• Backend: Python, FastAPI, Supabase
• Frontend: Next.js, TypeScript, Tailwind (coming)
• AI: Claude (interpretation), DALL-E/SDXL (image generation)
• 3D: TBD (Meshy, Tripo, or similar)