A sophisticated, AI-powered weather-aware activity planner that helps you schedule your week intelligently. SkyCoach automatically classifies your tasks (using OpenAI), fetches real-time weather data, and recommends the best times to do each activity based on weather suitability. Built with React, TypeScript, FastAPI, and OpenAI.
- Two-Step OpenAI Pipeline: Rephrases your task input for clarity, then classifies it as Indoor or Outdoor suitable
- Intelligent Understanding: Handles typos, abbreviations, and natural language variations seamlessly
- Context-Aware Judgment: Distinguishes between "work" (Indoor) and "work outside" (Outdoor)
- Fallback Capability: Local ML classifier trained on the activity corpus when OpenAI unavailable
- Browser Geolocation API: Auto-detects user's GPS coordinates
- Nominatim Reverse Geocoding: Converts coordinates to city names automatically
- Manual City Selection: Override detection with manual city input
- Location Persistence: Saves location preference to localStorage across sessions
- Clear/Reset Functionality: Easy button to clear saved location and re-detect
- OpenWeatherMap API: Live weather data (temperature, humidity, wind speed, precipitation)
- 7-Day Forecast: Visual weather forecast for planning your entire week
- Hourly Breakdown: Detailed 48-hour forecast with hourly granularity
- Dynamic Scoring: Adjusts activity suitability scores based on weather conditions
- Weather-Aware Recommendations: Suggests optimal weather windows for activities
- Weekly Planner: Visualize all tasks with weather overlay for the next 7 days
- Smart Sequencing: Recommends best order to complete tasks based on weather suitability
- Color-Coded Classification: Tasks marked as Indoor (blue) or Outdoor (orange) for quick visual parsing
- Confidence Scores: AI provides confidence percentage for each classification
- Dashboard: Quick overview of current weather and upcoming tasks
- Todo Manager: Create, track, and manage your task list
- Timetable: Schedule tasks across days with visual time blocks
- Planner: Advanced weekly scheduler with weather-aware recommendations
- Glassmorphism Design: Frosted glass effect cards with modern aesthetics
- GSAP Animations: Smooth, performant entrance and transition effects
- Tailwind CSS: Utility-first styling for consistent, responsive design
- Dark Theme: Eye-friendly dark interface with purple/blue color scheme
- Mobile-First: Fully responsive layouts that work on all device sizes
- Weather Backgrounds: Dynamic visual feedback based on current conditions
- localStorage: Client-side storage for user preferences and location
- Session State: Zustand-like hook patterns for React state management
- Task History: Maintains list of recent analyses for reference
Complete documentation is available in the /docs folder:
-
System Architecture - Full system design, data flow, deployment strategies, and scaling considerations
-
Backend Services:
- AI Engine - OpenAI integration, two-step classification pipeline, fallback mechanisms
- Auto-Judge - Activity judgment and scoring logic
- Scoring Engine - Weather-based score calculation and penalty/bonus application
- Maps - Location visualization and geospatial features
- API Routes - Complete REST API endpoint reference with request/response schemas
-
Frontend:
- Components - Detailed React component breakdown and usage patterns
- Services - API client, HTTP utilities, and data fetching patterns
- Hooks - Custom React hooks (usePreferredCity, useTaskStore, useApi, etc.)
-
Data Models:
- Data Models - TypeScript/Python type definitions and schemas
- Activity Corpus - Comprehensive activity dataset and classification examples
┌─────────────────────────────────────────────────────────────────────────┐
│ Frontend (React + TypeScript) │
│ ┌─────────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ Activity Input │ │ Dashboard │ │ Planner (7-Day Calendar) │ │
│ │ (GPS + Manual) │ │ (Overview) │ │ (Weather + Tasks) │ │
│ └────────┬────────┘ └──────────────┘ └──────────────────────────┘ │
│ │ │ │
│ ┌────────▼──────────────────────────────▼──────┐ │
│ │ React Hooks & State Management │ │
│ │ • usePreferredCity (Location persistence) │ │
│ │ • useTaskStore (Task management) │ │
│ │ • useApi (API client wrapper) │ │
│ └────────┬─────────────────────────────────────┘ │
│ │ HTTP/REST │
└───────────┼─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Backend (FastAPI + Python) │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ API Routes Layer │ │
│ │ POST /api/analyze-task (Task classification) │ │
│ │ POST /api/weather (Get weather for city) │ │
│ │ POST /api/geocode (Reverse geocoding) │ │
│ └────────┬────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────▼─────────────────────────────────────────────────────────┐ │
│ │ AI Engine (Two-Step Classification) │ │
│ │ │ │
│ │ Step 1: Rephrase (OpenAI) │ │
│ │ "washin my car" → "Washing my car" │ │
│ │ │ │
│ │ Step 2: Classify (OpenAI) │ │
│ │ Input: "Washing my car" + Location: "New York" │ │
│ │ Output: { classification: "Outdoor", confidence: 0.95 } │ │
│ │ │ │
│ │ Fallback: Local ML classifier (Decision Tree / Random Forest / │ │
│ │ Gradient Boosting with cross-validation) │ │
│ │ When: OpenAI key unavailable or API rate limits │ │
│ │ Accuracy: selected by 5-fold cross-validation on activity data │ │
│ └────────┬─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────▼─────────────────────────────────────────────────────────┐ │
│ │ External Services Integration │ │
│ │ • OpenAI GPT-4o-mini (Task classification) │ │
│ │ • OpenWeatherMap (Weather data & forecasts) │ │
│ │ • Nominatim (Reverse geocoding: coords → city name) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Data Storage & Persistence │
│ • Browser localStorage (user location, task preferences) │
│ • Session State (current tasks, UI state) │
│ • OpenWeatherMap Cache (temporary weather data) │
└─────────────────────────────────────────────────────────────────────────┘
Input: "washin my car"
Prompt: "Clean up informal language while preserving intent"
Output: "Washing my car"
Purpose: Normalize user input for more consistent classification
Input: "Washing my car"
Context: Location: "New York", Time: "Monday 2 PM"
Prompt: "Is this activity better done indoors or outdoors?
Consider weather, time of day, and location"
Output: {
"classification": "Outdoor",
"reasoning": "Car washing is inherently an outdoor activity",
"confidence": 0.95
}
Purpose: Determine if activity is better suited for indoor or outdoor conditions
Fallback Behavior (when OpenAI key unavailable):
Local ML classifier trained on the activity corpus:
- Decision Tree, Random Forest, and Gradient Boosting candidates
- 5-fold cross-validation to pick the best model
- Domain overrides keep clear fitness/outdoor tasks like gym as Outdoor- User Input → ActivityInput component with GPS detection
- Location Resolution → Browser Geolocation → Nominatim reverse geocoding → city name
- Task Submission → POST
/api/analyze-taskwith task text and location - AI Classification → Two-step OpenAI pipeline (rephrase + classify)
- Weather Fetch → POST
/api/weatherto get forecast for location - Task Recommendation → Planner displays optimal scheduling based on:
- Classification (Indoor/Outdoor)
- Weather forecast (next 7 days)
- User's preferred time windows
- Persistence → Task saved to localStorage and displayed in Todo/Planner/Timetable views
Weather suitability affects task scoring based on classification:
| Classification | Weather Factor | Impact | Details |
|---|---|---|---|
| 🏃 Outdoor | Clear/Sunny | ✅ +30% | Ideal conditions |
| 🏃 Outdoor | Cloudy | ✅ +10% | Acceptable |
| 🏃 Outdoor | Light Rain | Reduced suitability | |
| 🏃 Outdoor | Heavy Rain | ❌ -80% | Not recommended |
| 🏃 Outdoor | Wind > 15mph | Reduced comfort | |
| 🏠 Indoor | Rain/Storm | ✅ +20% | Enhanced suitability |
| 🏠 Indoor | Temperature > 30°C | ✅ +10% | Air conditioning benefit |
| 🏠 Indoor | Clear Weather | Might prefer outdoors |
- Node.js 18+ and npm
- Python 3.11+
- OpenAI API Key (optional for demo mode, required for full AI features)
- Get one at platform.openai.com
- OpenWeatherMap API Key (optional for demo, recommended for live weather)
- Get one at openweathermap.org
cd "Project Ai"# Create virtual environment
python -m venv venv
# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txtcd frontend
# Install Node dependencies
npm install
# Create .env file for frontend configuration
# Add these optional variables:
VITE_OPENAI_MODEL=gpt-4o-mini # Default OpenAI model
VITE_API_URL=http://localhost:8000 # Backend API addressTerminal 1 - Backend:
# From project root
python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reloadTerminal 2 - Frontend:
# From frontend directory
npm run devFrontend will be available at http://localhost:5173
Backend API at http://localhost:8000
# Build and run both services
docker-compose up --build
# Services will be available at:
# Frontend: http://localhost
# Backend API: http://localhost:8000# Required for full AI features
OPENAI_API_KEY=sk-your-openai-key-here
OPENAI_MODEL=gpt-4o-mini
# Required for weather features
OPENWEATHER_API_KEY=your-openweather-key-here
# Optional: Redis cache (for production)
REDIS_URL=redis://localhost:6379
# Optional: Logging
LOG_LEVEL=INFOVITE_OPENAI_MODEL=gpt-4o-mini
VITE_API_URL=http://localhost:8000- Launch the frontend (http://localhost:5173)
- Enable GPS - Click "Detect My Location" in ActivityInput to auto-detect
- Browser will request location permission
- City name will auto-populate
- Enter Activity - Type what you want to do (typos OK!)
- Examples: "gonna wash my car", "going to gym", "work from home"
- View Results - See classification, confidence, and recommendations
All features work in demo mode when API keys are absent:
- Task classification uses the local ML fallback classifier
- Weather shows cached/simulated data
- Location detection still works via browser geolocation
1. Set Your Location
- Click "📍 Detect My Location" to use browser geolocation (auto-detects GPS)
- Or manually enter city name in the location input field
- Your location is saved automatically for future sessions
- Click "Clear Saved Location" to reset and re-detect
2. Add Activities to Your Todo
- On the Todo Page: Click "Add New Task" and type your activity
- Examples: "wash my car", "go to gym", "work from home", "have lunch"
- Don't worry about typos or informal language - AI will understand
- Press Enter or click Add to save
3. View in Planner (7-Day Forecast)
- Go to the Planner Page to see weather-aware scheduling
- Tasks are color-coded:
- 🔵 Blue = Indoor suitable activities
- 🟠 Orange = Outdoor suitable activities
- Each task shows:
- AI confidence percentage
- Current suitability for that day
- Weather influence on recommendation
- UI displays optimal ordering for tasks based on weather ✅
4. Check Your Timetable
- Navigate to Timetable Page for time-based scheduling
- See all tasks organized by day
- Visual calendar view with task distribution
5. View Dashboard
- Dashboard Page shows quick overview:
- Current weather and location
- Today's forecast
- Upcoming tasks
- Quick stats
Location Management
- Persistent across browser sessions (localStorage)
- Switch between GPS auto-detect and manual entry
- Reverse geocoding converts coordinates → city name
- Click location card to edit
Task Analysis Details
- View AI confidence scores for each classification
- Read the reasoning behind Indoor/Outdoor classification
- See weather factors affecting suitability:
- Temperature changes
- Rainfall probability
- Wind speed impact
- Humidity levels
Weather Integration
- Live 7-day forecast for your location
- Hourly breakdown available on hover
- Weather icons indicate conditions
- Temperature ranges help plan outdoor activities
Drag & Drop Reordering (in Todo/Timetable)
- Reorder tasks to match suggested sequence
- Drag task cards to different days
- System auto-saves changes
ActivityInput (Navigation Header)
- Quick location selector (GPS or manual)
- City name display with edit capability
- Clear location button for reset
- Shows current location mode (Auto/Manual)
WeatherCard
- Current conditions for selected location
- Large temperature display
- Weather description and icons
- Wind, humidity, and UV index
TaskCard (Planner View)
- Task name
- Color-coded classification (Indoor/Outdoor)
- AI confidence percentage
- Suitability indicator for that day
- Weather reasoning from OpenAI
ScoreGauge
- Circular progress indicator with percentage
- Color changes based on suitability (Red to Green)
- Animated entrance effect (GSAP)
- Smooth transitions on value change
WeatherBackground
- Dynamic background changes per weather condition
- Smooth animations and transitions
- Glassmorphism effect on cards
- Responsive to weather updates
- Enter - Add new task (from input field)
- Ctrl+L - Focus location input
- Escape - Close modals/dialogs
- ✅ Mobile: Single column, stacked layout
- ✅ Tablet: 2-column grid
- ✅ Desktop: 3+ column layouts
- ✅ All breakpoints tested (320px → 2560px)
- GSAP-powered entrance effects
- Smooth gauge filling animations
- Card hover effects (glassmorphism depth)
- Weather background transitions
- Cross-fade between views
Project Ai/
│
├── 📄 README.md # This file
├── 📄 requirements.txt # Python dependencies
├── 📄 docker-compose.yml # Docker orchestration
├── 📄 INSTALLATION_GUIDE.md # Detailed setup instructions
├── 📄 FULL_STACK_SETUP.md # Full-stack deployment guide
├── 📄 QUICK_REFERENCE.md # Quick command reference
├── 📄 AUTO_JUDGE_FEATURE.md # Auto-judge feature documentation
├── 📄 BACKEND_API.md # Backend API reference
│
├── 🔧 Backend (FastAPI + Python)
│ ├── backend/
│ │ ├── __init__.py
│ │ ├── main.py # FastAPI app initialization
│ │ ├── Dockerfile # Backend containerization
│ │ │
│ │ ├── api/
│ │ │ ├── __init__.py
│ │ │ └── routes.py # API endpoints (/analyze-task, /weather, /geocode)
│ │ │
│ │ └── schemas/
│ │ ├── __init__.py
│ │ └── models.py # Pydantic schemas (request/response models)
│ │
│ ├── services/ # Business logic layer
│ │ ├── __init__.py
│ │ ├── ai_engine.py # Two-step OpenAI pipeline + fallback classifier
│ │ ├── auto_judge.py # Activity judgment logic
│ │ ├── geolocation.py # Location handling (reverse geocoding)
│ │ └── maps.py # Map generation utilities
│ │
│ ├── core/ # Core functionality
│ │ ├── __init__.py
│ │ ├── pipeline.py # Processing pipeline orchestration
│ │ └── scoring_engine.py # Weather-based scoring algorithm
│ │
│ ├── models/ # Data models and classes
│ │ ├── __init__.py
│ │ └── data_classes.py # TaskAnalysis, AnalysisRequest, etc.
│ │
│ ├── plugins/ # Extensible plugins
│ │ ├── __init__.py
│ │ ├── normalization.py # Input normalization
│ │ ├── quality.py # Quality checks
│ │ └── registry.py # Plugin registry
│ │
│ ├── themes/ # Theme configuration
│ │ ├── __init__.py
│ │ └── styles.py # Style definitions
│ │
│ ├── utils/ # Utility functions
│ │ └── __init__.py
│ │
│ ├── components/ # Reusable components (Python)
│ │ ├── __init__.py
│ │ ├── animations.py # Animation utilities
│ │ ├── cards.py # Card components
│ │ ├── gauges.py # Gauge components
│ │ ├── layout.py # Layout utilities
│ │ ├── responsive.py # Responsive design helpers
│ │ └── ui.py # UI utilities
│ │
│ └── tests/
│ └── test_analyze_coordinates.py # Regression tests (10 tests)
│
├── 🎨 Frontend (React + TypeScript + Vite)
│ ├── frontend/
│ │ ├── package.json # npm dependencies
│ │ ├── tsconfig.json # TypeScript configuration
│ │ ├── vite.config.ts # Vite build configuration
│ │ ├── tailwind.config.js # Tailwind CSS setup
│ │ ├── playwright.config.ts # E2E test configuration
│ │ ├── index.html # HTML entry point
│ │ ├── Dockerfile # Frontend containerization
│ │ ├── nginx.conf # Nginx web server config
│ │ │
│ │ ├── src/
│ │ │ ├── main.tsx # React entry point
│ │ │ ├── App.tsx # Main App component
│ │ │ │
│ │ │ ├── components/ # Reusable React components
│ │ │ │ ├── ActivityInput.tsx # Location + activity input form
│ │ │ │ ├── AlternativesCard.tsx # Alternative suggestions
│ │ │ │ ├── AnalysisResult.tsx # Classification results display
│ │ │ │ ├── AppShell.tsx # Main app layout shell
│ │ │ │ ├── Header.tsx # Navigation header
│ │ │ │ ├── ScoreCard.tsx # Task score display
│ │ │ │ ├── ScoreGauge.tsx # Animated circular gauge
│ │ │ │ ├── TaskCard.tsx # Individual task card
│ │ │ │ ├── WeatherBackground.tsx # Dynamic weather background
│ │ │ │ ├── WeatherCard.tsx # Weather display card
│ │ │ │ └── index.ts # Component exports
│ │ │ │
│ │ │ ├── hooks/ # Custom React hooks
│ │ │ │ ├── useApi.ts # API client wrapper
│ │ │ │ ├── usePreferredCity.ts # Location persistence
│ │ │ │ └── useTaskStore.ts # Task state management
│ │ │ │
│ │ │ ├── pages/ # Page components
│ │ │ │ ├── Dashboard.tsx # Dashboard/home page
│ │ │ │ ├── PlannerPage.tsx # 7-day weather planner
│ │ │ │ ├── TimetablePage.tsx # Calendar/timeline view
│ │ │ │ └── TodoPage.tsx # Task list management
│ │ │ │
│ │ │ ├── services/ # API and utility services
│ │ │ │ ├── api.ts # API client configuration
│ │ │ │ └── Attached Element... (misc)
│ │ │ │
│ │ │ ├── styles/
│ │ │ │ └── globals.css # Global styles
│ │ │ │
│ │ │ ├── types/ # TypeScript type definitions
│ │ │ │ ├── api.ts # API response types
│ │ │ │ └── tasks.ts # Task types
│ │ │ │
│ │ │ └── utils/ # Utility functions
│ │ │
│ │ ├── public/ # Static assets
│ │ │ └── _redirects # Redirect rules (Netlify)
│ │ │
│ │ └── e2e/ # End-to-end tests
│ │ └── location-auto.spec.ts # Location detection tests
│ │
│ └── netlify.toml # Netlify deployment config
│
└── 📖 docs/
├── README.md # Documentation index
├── architecture/
│ └── system_design.md # Full system architecture
├── backend/
│ ├── ai_engine.md # AI pipeline detailed docs
│ ├── auto_judge.md # Auto-judge feature
│ ├── api_routes.md # API reference
│ ├── maps.md # Maps functionality
│ └── scoring_engine.md # Scoring algorithm
├── frontend/
│ ├── components.md # Component documentation
│ ├── hooks.md # Hooks documentation
│ └── services.md # Services documentation
└── datasets/
├── data_models.md # TypeScript/Python types
└── activity_corpus.md # Activity examples
Backend Core
backend/main.py- FastAPI app init, middleware setup, CORS configurationbackend/api/routes.py- ALL API endpoints (analyze-task, weather, geocode)services/ai_engine.py- Two-step OpenAI pipeline, rephrase + classify, fallback rulesservices/geolocation.py- Nominatim integration for reverse geocodingmodels/data_classes.py- Pydantic models for all request/response schemas
Frontend Core
frontend/src/App.tsx- Navigation router, main layoutfrontend/src/hooks/usePreferredCity.ts- Location state persistence (localStorage)frontend/src/hooks/useTaskStore.ts- Task list managementfrontend/src/hooks/useApi.ts- Wrapped fetch with error handlingfrontend/src/pages/PlannerPage.tsx- Main 7-day scheduler (OpenAI classification)frontend/src/services/api.ts- Typed API client with VITE env vars
Configuration
requirements.txt- Python packages (FastAPI, OpenAI, requests, etc.)frontend/package.json- Node packages (React, Vite, Tailwind, etc.)docker-compose.yml- Multi-container orchestration (frontend + backend)
# ========== OPENAI CONFIGURATION ==========
# Required: Your OpenAI API key from platform.openai.com
OPENAI_API_KEY=sk-prod-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Optional: Model selection (defaults to gpt-4o-mini)
OPENAI_MODEL=gpt-4o-mini
# ========== WEATHER DATA ==========
# Required: OpenWeatherMap API key from openweathermap.org
OPENWEATHER_API_KEY=your-openweather-key-here
# ========== OPTIONAL: REDIS CACHING ==========
# For production deployments with multiple backend instances
REDIS_URL=redis://localhost:6379
# ========== LOGGING ==========
# Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_LEVEL=INFO
# ========== DEPLOYMENT ==========
# Frontend URL (for CORS configuration)
FRONTEND_URL=http://localhost:5173
# API environment (development, staging, production)
ENVIRONMENT=development# ========== API CONFIGURATION ==========
# Backend API URL
VITE_API_URL=http://localhost:8000
# OpenAI model to use (must match backend)
VITE_OPENAI_MODEL=gpt-4o-mini
# ========== FEATURE FLAGS ==========
# Enable/disable features (optional)
VITE_ENABLE_WEATHER=true
VITE_ENABLE_FORECAST=true
VITE_ENABLE_MAPS=falseScoring Engine Parameters (in core/scoring_engine.py):
# Weather thresholds
RAIN_THRESHOLD_MM = 0.0
WIND_THRESHOLD_MPH = 15.0
HEAT_THRESHOLD_C = 30.0
# Scoring multipliers (adjustment allowed)
OUTDOOR_RAIN_PENALTY = -80 # % penalty for outdoor tasks in rain
OUTDOOR_WIND_PENALTY = -30 # % penalty for outdoor tasks in wind
INDOOR_RAIN_BONUS = +20 # % bonus for indoor tasks in rain
INDOOR_HEAT_BONUS = +10 # % bonus for indoor tasks in heatAPI Queue & Rate Limiting:
- OpenAI: Default rate limits apply (40K RPM for gpt-4o-mini)
- OpenWeather: Free tier = 60 calls/min
- Nominatim: ~1-2 requests max per second
| Technology | Version | Purpose |
|---|---|---|
| React | 18+ | UI framework |
| TypeScript | 5.3+ | Type safety |
| Vite | 5.0+ | Build tool & dev server |
| Tailwind CSS | 3.3+ | Utility-first styling |
| GSAP | 3.12+ | Animations |
| React Query | 4.x+ | Server state management |
| Zustand | 4.x+ | Client state management |
| Technology | Version | Purpose |
|---|---|---|
| FastAPI | 0.104+ | Web framework |
| Python | 3.11+ | Runtime |
| Pydantic | 2.0+ | Data validation |
| OpenAI Python | Latest | AI classification |
| Requests | 2.31+ | HTTP client |
| Geopy | 2.4+ | Reverse geocoding |
| Uvicorn | 0.24+ | ASGI server |
| Technology | Purpose |
|---|---|
| Docker | Containerization |
| Docker Compose | Multi-container orchestration |
| Nginx | Reverse proxy, static serving |
| Playwright | E2E testing |
| Vite | Fast frontend builds |
| Service | Purpose | Pricing |
|---|---|---|
| OpenAI GPT-4o | Task classification | Pay-as-you-go (~$0.00015 per task) |
| OpenWeatherMap | Weather data & forecasts | Free tier available (60 calls/min) |
| Nominatim | Reverse geocoding | Free, OSM-powered |
| Browser Geolocation API | GPS coordinates | Native browser API |
POST /api/analyze-task
Request:
{
"text": "going to gym",
"location": "New York",
"use_openai": true,
"openai_api_key": "sk-...",
"openai_model": "gpt-4o-mini"
}
Response:
{
"classification": "Outdoor",
"reasoning": "Going to gym is typically an outdoor activity due to...",
"confidence": 0.92,
"original_text": "going to gym",
"processed_text": "Going to gym"
}
POST /api/weather?city=New+York
Response:
{
"city": "New York",
"temperature": 22.5,
"condition": "Partly Cloudy",
"humidity": 65,
"wind_speed": 12.5,
"forecast": [
{
"dt": 1685836800,
"temp_max": 24.2,
"temp_min": 19.1,
"condition": "Sunny"
},
...
]
}
POST /api/geocode
Request:
{
"latitude": 40.7128,
"longitude": -74.0060
}
Response:
{
"city": "New York",
"country": "United States",
"latitude": 40.7128,
"longitude": -74.0060
}
For full API documentation, see BACKEND_API.md
Run Python regression tests:
# From project root
python -m pytest tests/ -v
# Run specific test file
python -m pytest tests/test_analyze_coordinates.py -v
# Run with coverage
python -m pytest tests/ --cov=services --cov=coreCurrent Test Coverage:
- ✅ 10 regression tests for classification behavior
- ✅ Tests validate: gym→Outdoor, work→Indoor, work outside→Outdoor
- ✅ Tests use the local ML fallback classifier (no API key required)
- ✅ Tests verify OpenAI pipeline with mock responses
- 📌 Location detection tested via e2e (Playwright)
Run E2E tests with Playwright:
# Install browsers (first time only)
npx playwright install
# Run e2e tests
npm run test:e2e
# Run specific test
npx playwright test location-auto.spec.ts
# Run with UI
npx playwright test --ui
# Debug mode
npx playwright test --debugCurrent E2E Test Coverage:
- ✅ Location auto-detection flow
- ✅ Manual location entry
- ✅ Task classification
- ✅ Navigation between pages
# TypeScript type checking
cd frontend && npm run type-check
# Backend type checking (optional mypy)
mypy backend/ services/Problem: Classification feature not working Solution:
- Set
OPENAI_API_KEYin your.envfile - Restart backend:
Stop-Process -Name pythonthen restart uvicorn - Ensure frontend sends
use_openai=truein request
Problem: Weather not showing for location Solution:
- Verify
OPENWEATHER_API_KEYin.env - Check that city name is valid (use geolocation API to verify)
- Try different city: "New York" instead of "ny"
- Check OpenWeather rate limits (60/min on free tier)
Problem: Browser geolocation not working Solution:
- Check browser permissions (Settings → Privacy → Location)
- Ensure site is accessed over HTTPS (required for geolocation)
- Clear browser cache and refresh page
- Manually enter city name as fallback
- Check browser console for specific errors
Problem: Frontend can't reach backend API Solution:
- Verify backend is running:
http://localhost:8000/docs - Check VITE_API_URL in
frontend/.env.local - Ensure FRONTEND_URL in backend
.envmatches frontend URL - Clear browser cache + hard refresh (Ctrl+Shift+R)
- Check browser console for exact error message
Problem: Tasks disappear after refresh Solution:
- Check browser localStorage is enabled
- Verify browser isn't in private/incognito mode (disables localStorage)
- Check browser storage quota (DevTools → Application → Storage)
- Clear other extensions that might interfere
- Try different browser to isolate issue
Problem: AI classifier not differentiating tasks properly Solution:
- Ensure OpenAI API key is set and working
- Check backend logs:
tail -f <backend_log_file> - Try simpler task names: "gym" instead of "gonna go to the gym later"
- Verify fallback classifier logic in
services/ai_engine.py - Test API directly:
curl -X POST http://localhost:8000/api/analyze-task -d '{"text":"gym"}'
Problem: npm run build exits with errors
Solution:
- Check TypeScript errors:
npm run type-check - Update dependencies:
npm install - Clear cache:
rm -rf node_modules package-lock.json && npm install - Check for circular imports in components/
- Verify all imports match actual file paths
Problem: Backend fails to start Solution:
# Find process using port 8000
netstat -ano | findstr :8000
# Kill process (Windows PowerShell)
Stop-Process -Id <PID> -Force
# Or use different port
python -m uvicorn backend.main:app --port 8001# Build images
docker-compose build
# Run services
docker-compose up
# Run in background
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down-
Security
- Use environment variables for all secrets (never hardcode)
- Enable HTTPS/SSL in Nginx configuration
- Set strong CORS origins (
FRONTEND_URLin backend.env) - Rate limit API endpoints
- Validate all user inputs
-
Performance
- Enable Redis caching for weather data (set
REDIS_URL) - Use CDN for static frontend assets
- Implement request queueing for OpenAI calls
- Monitor API rate limits
- Cache geocoding results
- Enable Redis caching for weather data (set
-
Monitoring
- Use application performance monitoring (APM)
- Log all API errors and exceptions
- Monitor OpenAI API usage and costs
- Track frontend performance (load times)
- Set up alerts for service failures
-
Database (Future Enhancement)
- Consider adding PostgreSQL for task history
- Implement user accounts and authentication
- Store location preferences per user
- Track usage statistics
We welcome contributions! Here's how to get started:
-
Fork the repository
# On GitHub, click "Fork" -
Create a feature branch
git checkout -b feature/your-feature-name
-
Make your changes
- Follow existing code style
- Add tests for new functionality
- Update documentation
-
Testing before commit
# Backend tests python -m pytest tests/ -v # Frontend tests npm run test:e2e # Type checking npm run type-check mypy backend/
-
Commit with clear messages
git commit -m "feat: add new feature description" -
Push and create PR
git push origin feature/your-feature-name # Then create PR on GitHub
- Python: Follow PEP 8 (Black formatter)
- TypeScript: Follow ESLint rules in config
- Comments: Add comments for complex logic
- Naming: Use clear, descriptive names
- User authentication & multi-user support
- Task history and analytics dashboard
- Advanced filtering (by date, category, etc.)
- Mobile app (React Native)
- Calendar integration (Google Calendar, Outlook)
- Weather alerts and notifications
- Task categories/tags system
- Collaborative task planning (shared locations)
- Export to calendar formats (ICS, etc.)
- AI-powered smart suggestions
- Bundle Size: ~150KB gzipped (React + Tailwind + GSAP)
- Page Load Time: < 2s on 4G
- Time to Interactive: < 3s
- Lighthouse Score: 85+ (on desktop)
Optimization Strategies:
- Code splitting by page
- Image compression and WebP support
- Service Worker for offline capability
- Lazy loading of components
- Memoization of expensive calculations
- API Response Time: < 500ms for classify (with OpenAI)
- Weather Fetch: < 1s (OpenWeatherMap API)
- Geocoding: < 500ms (Nominatim)
- Fallback Classifier: Fast local ML inference after model training
Optimization Strategies:
- Cache weather data for 1 hour
- Batch geolocation requests
- Connection pooling for external APIs
- Async task processing
- Database indexing (future)
- OpenAI task classification
- Location detection & persistence
- Weather integration
- 7-day planner view
- Responsive UI
- Docker deployment
- User authentication
- Task history & analytics
- Advanced filtering
- Notification system
- Calendar sync
- Mobile app
- AI-powered insights
- Collaborative planning
- Activity recommendations based on habit
- Integration with fitness trackers
- Documentation: See
/docsfolder - Issues: Create GitHub issue for bugs
- Discussions: Use GitHub Discussions for questions
- Email: [Add contact email if applicable]
MIT License - Feel free to use and modify for any purpose!
MIT License
Copyright (c) 2024 SkyCoach AI
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
Let the weather guide your day!