Development

This guide covers setting up a local development environment for Morning Drive.

Backend Development

Quick Start

Run the backend in development mode with auto-reload:

cd backend

# Copy environment configuration (first time only)
cp .env.example .env
# Edit .env with your API keys

# Start in development mode
./dev.sh

This script:

Automatically detects your machine's IP address
Starts the server with hot-reload enabled
Mounts source code so changes apply instantly
Starts MinIO for music storage

Auto-reload: When running via dev.sh, any changes to Python files in src/ will automatically reload the server. No rebuild required!

Alternative: Running Without Docker

cd backend

# Create a virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Copy environment configuration
cp .env.example .env
# Edit .env with your API keys

# Start the development server
python -m src.main

Running MinIO for Music Storage

# Start just the MinIO service (if not using dev.sh)
docker compose up -d minio

# MinIO Console: http://localhost:9001
# Default credentials: minioadmin / minioadmin

Viewing Logs

# Follow backend logs
docker compose logs -f morning-drive

# View last 100 lines
docker compose logs --tail 100 morning-drive

iOS App Development

Prerequisites

macOS with Xcode installed
Node.js 18+ and npm
CocoaPods (brew install cocoapods)

Initial Setup

cd MorningDriveApp

# Install JavaScript dependencies
npm install

# Install iOS native dependencies
cd ios && pod install && cd ..

Starting the Metro Bundler

Metro is the JavaScript bundler for React Native. It must be running for the app to load:

# Start Metro (keep this terminal open)
npx react-native start

# Metro runs on http://localhost:8081

Running on iOS Simulator

# In a new terminal, run the app
npx react-native run-ios

# Or specify a simulator
npx react-native run-ios --simulator="iPhone 15 Pro"

Running on Physical iPhone

Connect your iPhone via USB
Open ios/MorningDriveApp.xcworkspace in Xcode
Select your device from the device dropdown
Click the Run button (or press Cmd+R)

First-time setup: You'll need to configure code signing in Xcode with your Apple Developer account.

Connecting the App to Metro (Physical Device)

When running on a physical device, the app needs to connect to Metro on your computer:

# Find your computer's IP address
ipconfig getifaddr en0  # macOS

On your iPhone:

Shake the device to open the React Native dev menu
Tap "Configure Bundler"
Enter your computer's IP (e.g., 192.168.1.100) and port 8081
Tap "Reload"

Connecting the App to Backend Server

The app also needs to connect to the Morning Drive backend:

Open the app and go to Settings
In the Server URL field, enter your backend URL (e.g., http://192.168.1.100:8000)
Tap "Save & Connect"

Tip: The backend admin panel shows the server URL you need. Log in at http://localhost:8000/admin to see it.

Troubleshooting

Problem	Solution
App shows white screen	Make sure Metro is running. Shake device and tap "Reload"
Settings page stuck loading	Backend is unreachable. Check server URL in Settings (always visible at top)
"Unable to load script"	Metro not reachable. Check IP and port in bundler settings
Metro shows "BUNDLE" but app doesn't update	Shake device and tap "Reload", or restart Metro
Can't connect to backend	Ensure phone and computer are on same WiFi network

Running Tests

Backend Tests

cd backend
pytest

# Run with coverage
pytest --cov=src

iOS Tests

cd MorningDriveApp
npm test

Code Quality

Backend Linting

# Run ruff linter
ruff check src/

# Auto-fix issues
ruff check src/ --fix

# Format code
ruff format src/

iOS Linting

# Run ESLint
npm run lint

# Fix auto-fixable issues
npm run lint -- --fix

Project Structure

good-morning/
├── backend/
│   ├── src/
│   │   ├── api/          # REST API routes
│   │   ├── agents/       # Claude content generation
│   │   ├── tools/        # Data fetching (news, sports, weather)
│   │   ├── audio/        # TTS and audio mixing
│   │   ├── storage/      # Database and file storage
│   │   └── templates/    # Website HTML templates
│   ├── assets/           # Audio assets (intro, outro, transitions)
│   ├── data/             # SQLite database, generated audio
│   └── tests/            # Test suite
└── MorningDriveApp/      # React Native iOS app
    ├── src/
    │   ├── screens/      # App screens
    │   ├── components/   # Reusable components
    │   ├── services/     # API client, audio player
    │   └── store/        # State management (Zustand)
    ├── ios/              # Native iOS project
    └── docs/             # iOS distribution guides

Custom Audio Assets

Replace placeholder audio in backend/assets/:

intro.mp3 - Intro music/jingle
transition.mp3 - Transition sound between segments
outro.mp3 - Outro music

Useful Commands

# View backend logs
docker-compose logs -f morning-drive

# Restart a specific service
docker-compose restart morning-drive

# Access MinIO console
open http://localhost:9001

# Check API documentation
open http://localhost:8000/api/docs

Morning Drive

Documentation