# Stargazer

## Overview

Stargazer is a comprehensive web platform designed for amateur astronomers and astrophotography enthusiasts. The application helps users plan, track, and enhance their stargazing experiences by providing powerful tools for equipment management, location tracking, and astronomical insights.

## Vision and Mission

### Mission
To empower the astronomical community with modern, technology-driven tools that simplify planning, gear management, and discovery, making the universe accessible to everyone.

### Vision
To become the definitive one-stop-shop for astronomers—a modern, unified hub that integrates a fragmented landscape of distributed resources into a single, intuitive ecosystem for everything the night sky demands.

### Core Values
- **Innovation**: Leveraging AI and advanced data processing for better insights.
- **Accessibility**: Providing tools that are easy to use in the field and support multiple languages.
- **Community**: Fostering a space for sharing knowledge, locations, and experiences.
- **Precision**: Delivering accurate weather and astronomical data for successful sessions.

## Key Features

### 1. User Profiles and Authentication
- Seamless login using Google Account, Facebook, or similar OAuth providers.
- Secure and personalized user experience with theme preferences (Dark/Light mode).
- Profile management including language selection (English, Polish, Spanish, Portuguese, German).
- **Try Demo Mode**: Instantly explore all application features with pre-populated realistic astronomical data without needing to register.

### 2. Nova (AI Assistant)
Nova is a state-of-the-art AI astronomy assistant powered by Large Language Models:
- **Conversational Planning**: Ask Nova for equipment recommendations, sky insights, or planning advice.
- **Full CRUD Capabilities**: Manage your observations, locations, gear, and condition presets directly through natural language chat.
- **Sky Insights**: Receive personalized summaries of interesting celestial objects based on your specific equipment and current conditions.
- **Context Awareness**: Nova uses the Model Context Protocol (MCP) to access your observation history, catalog data, upcoming events, and event rarity.
- **Real-time Interaction**: Features streaming responses with typing effects and tool-usage notifications for a transparent experience.
- **Multiple AI Providers**: Support for OSS-GPT (open-source GPT via Scaleway), Google Gemini, DeepSeek (hosted on Scaleway's European cloud), and Ollama for fully local testing. Users can configure their preferred AI Agent in Profile settings.
- **Personality Selection**: Users can pick Nova's personality (Professional, Enthusiastic, or Storyteller) in Profile settings or directly from the Nova chat popup, changing the tone Nova uses while keeping all answers accurate.
- **Astrophotography Optimizer**: Nova can calculate pixel scale, Nyquist sampling, critical focus zone, and optimum exposure times based on gear and sky conditions.
- **Skymap Generation**: Nova can generate and display local sky maps for any celestial object with customizable plot options (zoom, magnitude limits, coordinate systems, object types).

### 3. Equipment Management
The heart of Stargazer is its robust equipment management system:
- **Digital Inventory**: Comprehensive tracking of:
  - Telescopes (including Smart Telescopes)
  - Eyepieces, Barlow lenses, and Diagonals
  - Cameras (DSLR and Dedicated Astro-cameras)
  - Binoculars
  - Optical Filters (UHC, OIII, Moon filters, etc.)
  - Adapters (spacers, thread converters)
- **Intelligent Analysis**:
  - Automatic calculation of magnification, exit pupil, and field of view (width, height, diagonal).
  - Visualization of the optical path and FOV on sky maps.
  - Recommendations for optimal equipment combinations for specific objects.
- **Advanced Technical Fields**: Read noise, quantum efficiency, thermal drift, mass (weight), and optical length tracking.
- **Image Sampling Status**: Classifies setups as Under-sampled, Well-sampled, or Over-sampled.
- **Exposure Calculations**: NPF Rule and Rule of 500 for optimum shutter speeds.
- **Telescope Central Obstruction**: Accounts for secondary mirror obstruction in reflector telescopes.
- **Equipment Factory**: Select reference equipment from a built-in database to auto-fill specifications.
- **Customizable Table Settings**: Toggle column visibility and reorder columns via drag-and-drop, with preferences stored in browser local storage.

### 4. Tonight's Sky
A personalized real-time overview of everything visible in the sky tonight:
- **Moon Phase**: Current phase icon and illumination percentage.
- **Planetary Positions**: Current positions and transit times of all visible planets.
- **Messier/Deep-Sky Objects**: List of observable deep-sky objects with visibility predictions.
- **ISS Passes**: Upcoming International Space Station flybys with peak magnitude.
- **Meteor Showers**: Active meteor shower information.
- **AI-Generated Observing Summary**: Personalized summary with full hourly weather breakdowns (temperature, clouds, precipitation, wind, visibility, fog, moon illumination, aurora).
- **Lazy-Loading Architecture**: Main page renders instantly; data-heavy sections load asynchronously.
- **SEO Optimized**: Auto-generated FAQ structured data, OG/Twitter metadata, Polish locative city names, translated moon phase names.
- **Server-Side Rendering (SSR)**: Heavy components rendered server-side when cached data is available for instant visibility to crawlers.
- **Dedicated Caching Layer**: Minimizes repeated astronomical calculations and API calls.
- **Location-Based URLs**: Easy bookmarking and sharing (e.g., /pl/tonight/warsaw/).

### 5. Astrophotography Calculator
A comprehensive set of tools for astrophotographers to optimize their imaging sessions:
- **Pixel Scale & Sampling**: Calculate pixel scale, Nyquist sampling, and critical focus zone.
- **SNR Calculations**: Signal-to-noise ratio displayed in decibels (dB) with sub-second exposure precision.
- **Advanced Technical Parameters**: Enhanced Camera and Telescope models with fields for read noise, quantum efficiency, and thermal drift.
- **Planetary Imaging Tools**:
  - Max Rotation Duration for Jupiter, Mars, and Saturn.
  - Ideal & Nyquist Focal Ratio calculations.
  - Atmospheric Dispersion assessment.
- **Automated Conditions Pre-filling**: Fetches Sky Quality (SQM) data from last observation or saved places.
- **Seeing & SQM Integration**: Real-time Seeing and SQM estimates for specific target transit times.
- **AI Integration**: Nova can help optimize gear pairings and exposure settings using dedicated MCP tools.

### 6. Target Selector (Discovery Engine)
Find your next imaging target with an intelligent discovery engine:
- **Suitability Scoring**: Equipment-specific scoring based on Altitude, Imaging Window, FOV fit, Moon interference, and Brightness.
- **Top Picks for Tonight**: Dynamic Broadband/Narrowband strategy toggles.
- **Color-Coded Scores**: Visual suitability indicators unified with the rest of the application.
- **Target Visibility**: Precise visibility calculations using local horizon data with "Visible only" toggle filtering.
- **Integrated Component**: Works seamlessly with observation details and equipment setups.

### 7. Polar Alignment Wizard
A guided tool to help achieve precise polar alignment:
- **Automatic Star Suggestion**: Recommends the best star for alignment.
- **RA Axis Calculation**: Calculates mount RA rotation.
- **Live Adjustment Feedback**: Visual correction map for real-time alignment guidance.
- **Standalone Tool**: Accessible directly from the Sky Guide menu, automatically links to current observation.

### 8. Observation Location Management
Track and analyze your favorite stargazing spots:
- **Personal Locations**: Detailed info including coordinates, elevation, and Bortle scale (light pollution).
- **Bortle Override**: Manually override the Bortle scale value for observation locations.
- **Community Places Map**: Color-coded markers (Green/Orange/Red) showing real-time observing conditions at community-shared locations with 24-hour staleness checks.
- **Map Integration**: Interactive maps with clickable markers and modal views for detailed exploration.
- **Moon Age & Distance**: Lunar observation planning data on place detail pages.
- **Sun & Moon Section**: Redesigned single-column layout with high-contrast labels.

### 9. Advanced Weather Monitoring
Tailored weather tracking for precision planning:
- **Forecasts**: Detailed multi-day forecasts for any registered location.
- **Condition Analysis**: Cloud cover, humidity, transparency, seeing, wind, visibility, fog, pressure, ozone, and aurora.
- **Seeing & Sky Brightness (SQM)**: Integrated advanced Seeing and SQM models with dedicated weather plots and configurable thresholds.
- **Cosmic Dashboard**: Weather Summary Bar with smooth gradient background representing hourly quality, interactive Mini-Dashboard tooltips, astronomical markers (Golden Hours, Astro Dark overlay), and Moon information panel.
- **Weather Check Tool**: Ad-hoc forecasts for any location without creating a formal observation, with dedicated results view.
- **Activity Presets**: One-click configuration for different activities like "Deep Sky", "Planetary", "Stargazing", "Astrophotography", "Aurora", "Moon", etc.
- **Hourly Summary**: Visual summary bars and detailed tables for night-long planning.
- **Weather Statistics Dashboard**: Track success rates, API performance, weather hurdles, and provider response times with global and user-specific charts.
- **StormGlass API Integration**: High-resolution global weather forecasts including cloud cover, visibility, and atmospheric conditions.
- **Moon Pre-check**: API calls skipped when astronomical conditions (like high Moon illumination) already make the night unsuitable.
- **Multiple Weather Providers**: Support for Pirate Weather and Meteoblue with per-location provider selection.

### 10. Sky Guide and Catalogs
A comprehensive resource for celestial navigation:
- **Extensive Catalogs**: Browse and search through NGC, Messier, Bright Stars, and Solar Objects.
- **Interactive Sky Maps**: Dynamic maps showing real-time positions, transit times, and altitude plots.
- **Visibility Predictions**: Real-time calculation of when objects are best visible from your location.
- **Popular Objects**: Discover trending targets based on community activity and seasonal visibility.
- **External Database Links**: Direct links to SIMBAD, ALADIN, and Astrobin for additional data and imagery.
- **Rise, Transit, and Set Times**: Dynamically calculated based on selected place or observation.
- **Dynamic Place Switching**: Selecting a different location instantly recalculates all astronomical data and updates the interactive sky map.
- **Server-Side Sorting**: Sort entire catalog datasets by any column.

### 11. Horizon Management
Accurate horizon profiles for better sky visibility predictions:
- **.hrz File Support**: Upload custom horizon definitions to reflect local obstacles.
- **Visual Grid Editor**: Interactive 72x19 grid (5-degree steps) to "paint" local horizon obstacles.
- **Tabbed Interface**: Seamless switching between visual Grid Editor and traditional manual text entry with bi-directional synchronization.
- **Per-Location/Activity Overrides**: Integrate Horizon settings into Places and Condition sets.

### 12. Session Tracking and History
Keep a detailed record of your journey through the stars:
- **Active Sessions**: Start/stop timers for live observation sessions.
- **Observation Logs**: Log specific objects seen, equipment used, and personal notes.
- **Statistics**: Monthly and yearly stats on your observing frequency, activity charts, popular objects, and gear usage.

### 13. Astronomical Event Predictions
Stay ahead of rare celestial phenomena:
- **Event Alerts**: Predictions for meteor showers, eclipses, conjunctions, planetary oppositions, ISS/Tiangong flybys, Jovian moon events (transits, shadows, eclipses, occultations), Saturn Ring Plane crossings, Moon Libration Maxima, Messier Culmination, Comet events, Greatest Elongation, Golden/Blue Hours, Seasons (Equinoxes/Solstices), Planet-Messier conjunctions, Jupiter GRS transits, Moon-Star conjunctions, and Planet Alignments.
- **Rarity Scale**: 1-5 rarity rating for all events to help prioritize observations.
- **Event Duration Tracking**: Duration tracking with "Visible only" filter as default.
- **Customized Timings**: Event details calculated specifically for your chosen location.
- **MCP Integration**: Events are accessible to the AI assistant for proactive planning advice.
- **Global Event Reuse**: Reusable events calculated once and shared across all locations for performance.

### 14. Smart Notification System
Automated alerts to ensure you never miss a clear sky:
- **Asynchronous Notifications**: Smart alerts for optimal conditions based on your custom thresholds, with background processing.
- **Rich Emails**: Personalized emails containing AI-generated sky insights, highlighted events, equipment reminders, and equipment tables.
- **Monthly Summary**: Personalized monthly overview of stargazing activity, weather checks, notifications, and equipment status.
- **Invite Friends**: Share observation plans and send automated weather alerts to your stargazing partners.
- **Daily Notifications Chart**: Track personalized alert history for the last 30 days.
- **Configurable Retries**: Automatic retries for email delivery with robust error handling.
- **Multi-Language Support**: Notifications handle individual recipient languages.

### 15. Stargazing Meetups
Organize and discover local stargazing events with the community:
- **Public Meetup List**: Browse upcoming public meetups with search, location-based radius filtering, and a publicly accessible page to attract new users.
- **"Use My Location"**: Browser geolocation with reverse-geocoded address display for instant radius-based search.
- **Saved Places Integration**: Use your existing observation places as meetup locations with automatic coordinate lookup.
- **Interactive Map Picker**: Create meetups with an interactive Leaflet map and draggable marker, matching the existing Place form UX.
- **RSVP System**: Mark yourself as Going, Interested, or Declined. Organizers can set attendee limits and make events private.
- **Attendee Management**: View who's going and who's interested. Organizer receives styled email notifications when someone joins.
- **Nearby Notifications**: Users receive email notifications when a new public meetup is created within their configurable radius (default 60 km, adjustable in Profile settings).
- **Admin Notifications**: Administrators are notified about new meetup creations for community oversight.
- **Community Map Integration**: Planned and active (non-past) public meetups appear as markers on the Community Places Map in Statistics — planned ones purple, active ones green with a pulsing effect.
- **My Meetups Dashboard**: Track meetups you've organized or joined in one place.
- **Owner Bypass**: Organizers always see their own meetups regardless of spatial filters, including private ones.

### 16. Project Transparency
Community-driven project sustainability:
- **Donation Tracking**: Display of recurring and one-time donations with real-time cost coverage breakdown.
- **Project Funding Summary**: Complete overview of project funding, infrastructure costs, and community support types.
- **Stripe Payment Support**: PLN donation integration for Polish users.
- **Support Navigation**: "Support" dropdown in main navigation for easy access.

### 17. About Us Page
- **Story Behind Stargazer Earth**: The platform's origin story.
- **Apts Guardian Fleet**: Introduction to specialized AI agents powering the platform.

### 18. Public Access & SEO
- **Public Catalogs**: Messier, NGC, and Bright Stars catalogs accessible without login.
- **SEO Metadata**: Comprehensive OG, Twitter Cards, JSON-LD structured data across all public pages.
- **XML Sitemaps**: Including individual pages for all 110 Messier objects, NGC targets, and Tonight's Sky location pages.
- **Guest Context Resolution**: Dynamic fallback to system defaults for guest users.

### 19. Demo Mode & Accessibility
- **Try Demo Mode**: Instantly explore all application features with pre-populated realistic astronomical data without needing to register.
- **Rich Demo Data**: Pre-configured with high-quality equipment (Celestron C8, ZWO ASI2600MC), world-class observing sites (Mauna Kea, Atacama Desert, Grand Canyon), and 30-day observation history.
- **Multi-Language Support**: English, Polish, Spanish, Portuguese, and German.
- **Dark/Light Mode**: Theme preference persisted across sessions.

## Target Users
- **Amateur Astronomers**: From beginners to advanced observers.
- **Astrophotography Enthusiasts**: Planning long-exposure sessions with precise weather and gear data.
- **Hobbyists**: Anyone interested in tracking the Moon, planets, or major celestial events.

## Technical Vision
- **Performance**: High-speed observation detail pages via advanced caching, distributed sharding, SSR for SEO-critical pages, and lazy-loading architecture.
- **Accessibility**: Multi-language support, responsive design, and dark/light mode for use in the field.
- **Innovation**: Leveraging AI to bridge the gap between complex astronomical data and user-friendly insights.
- **Infrastructure**: Preloading cron jobs, global event caching, distributed processing with memory management.

## Public API

Stargazer exposes a public, location-scoped REST API for developers (base URL `https://stargazer.earth/api/v1/`). It serves the same astronomy engine that powers the app: tonight's sky, astronomical events, catalog objects (Messier/NGC/Stars), moon and planets data, astro-weather (paid tier), astrophotography calculations, and AI conversational answers (pro tier).

- **Auth**: `Authorization: Bearer sg_live_<32 chars>` (API keys created in the developer portal at `/api/keys/`).
- **Discovery**: `GET /health` returns links to the OpenAPI schema (`/api/v1/openapi.json`), the hosted agent skill (`/api/v1/skill.md`) and this file.
- **Docs**: API reference at `/api/docs/`; machine-readable OpenAPI 3.0 schema at `/api/v1/openapi.json`.
- **Endpoints**: `/tonight`, `/events`, `/objects/visible`, `/objects/{catalog}/{name}`, `/moon`, `/planets`, `/weather/astro` (paid), `/calculations/astrophotography`, `/ask` (pro).
- **Answers**: `POST /ask` (pro tier) streams AI astronomy answers over server-sent events with live location data; tokens are metered against a per-account daily budget and billed as overage on pro subscriptions.
- **MCP server**: standard Model Context Protocol endpoint at `/api/v1/mcp` (paid tiers) with location-aware tools for sky objects, events, weather summaries and astrophotography calculations, plus tools that read and manage the API key owner's own equipment, observations, places and conditions — connect any MCP-capable client with `Authorization: Bearer <key>`.
- **Billing**: self-serve Stripe subscriptions from the developer portal — starter $3.99/mo, pro $9.99/mo (hourly usage metering reports `/ask` token overage). One subscription per account: all keys share the tier, and revoking a key never affects the subscription.
- **Errors**: uniform `{"error": {"code", "message", "request_id"}}` shape; `X-Request-ID` header on every response.
- **Rate limits**: per-account rpm/daily/monthly quotas by tier (free/starter/pro) — all keys of an account share one bucket; paid features (weather, answers) carry per-account daily caps.
- **Agent skill**: fetch `https://stargazer.earth/api/v1/skill.md` for example-first usage docs with curl examples.