A modern, modular dashboard for home and family organization built with SvelteKit and FastAPI.
# Clone the repository
git clone <your-repo-url>
cd dashboard
# Set up environment variables
cp templates/env_template.txt backend/.env
# Edit backend/.env with your API keys and settings
# Set up credentials (see Credentials section below)
cp templates/credentials_template.json backend/data/credentials.json
# Edit backend/data/credentials.json with your API keys
# Start the backend
cd backend
uv venv
.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux/macOS
uv pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000
# In a new terminal, start the frontend
cd frontend
npm install
npm run devVisit http://localhost:5173 to see your dashboard!
📚 Need detailed setup instructions? Check out our Getting Started Guide
- Google Calendar Sync: Real-time family events and appointments
- OAuth2 Authentication: Secure, token-based access
- Event Display: Clean, readable event cards with details
- Current Conditions: Real-time weather data
- 5-Day Forecast: Extended weather predictions
- Location Management: Geolocation, city/state, or zip code lookup
- Persistent Settings: Remembers your preferred location
- Smart Management: Add, edit, delete, and check off items
- Categories & Priorities: Organize with categories and priority levels
- Database Storage: Robust SQLite backend with async SQLAlchemy
- Auto-Migration: Seamless upgrade from legacy JSON storage
- Health Checks: Real-time system status via
/healthendpoint - Prometheus Metrics: Comprehensive monitoring via
/metricsendpoint - Performance Metrics: Dashboard and API monitoring with custom business metrics
- Error Tracking: Comprehensive error handling and logging
- Rate Limiting: Built-in rate limiting with metrics tracking
dashboard/
├── frontend/ # SvelteKit application
│ ├── src/
│ │ ├── lib/components/ # Reusable UI components
│ │ ├── stores/ # State management
│ │ └── routes/ # Page routes
│ └── package.json
├── backend/ # FastAPI application
│ ├── api/ # API endpoints
│ ├── models.py # Database models
│ ├── schemas/ # Pydantic schemas
│ └── requirements.txt
├── docs/ # 📚 Comprehensive documentation
│ ├── getting-started.md
│ ├── configuration.md
│ ├── troubleshooting.md
│ └── features/
└── data/ # Shared data storage
Frontend:
- SvelteKit - Full-stack web framework
- TypeScript - Type safety
- Tailwind CSS - Utility-first styling
- Vite - Build tool and dev server
Backend:
- FastAPI - Modern Python web framework
- SQLAlchemy - Async ORM
- SQLite - Lightweight database
- Pydantic - Data validation
- Prometheus - Metrics and monitoring
Integrations:
- Google Calendar API - Event management
- OpenWeatherMap API - Weather data
- Python 3.8+ with uv (recommended) or pip
- Node.js 18+ with npm, yarn, or pnpm
- Google Cloud Platform account for Calendar API
- OpenWeatherMap account for weather data
-
Google Calendar Setup:
- Create a project in Google Cloud Console
- Enable Google Calendar API
- Create OAuth2 credentials (Desktop application)
- Download credentials file
-
OpenWeatherMap Setup:
- Sign up at OpenWeatherMap
- Get your free API key
-
Configure Credentials:
cp templates/credentials_template.json backend/data/credentials.json # Edit backend/data/credentials.json with your actual credentials
Detailed setup instructions are available in our comprehensive documentation:
- Getting Started Guide - Quick setup and first steps
- Configuration Guide - Detailed API and environment setup
- Backend Setup - FastAPI server configuration
- Frontend Setup - SvelteKit application setup
The dashboard is organized into four main quadrants:
┌────────────────┬────────────────┐
│ 🌤️ Weather │ 🛒 Grocery │
│────────────────┼────────────────│
│ Current Weather│ Shopping List │
│ & Forecast │ & Household │
└────────────────┴────────────────┘
┌────────────────┬────────────────┐
│ 📅 Calendar │ 🧹 Chores │
│────────────────┼────────────────│
│ Family Events │ Household Task │
│ & Appointments │ & Reminders │
└────────────────┴────────────────┘
- Click any quadrant to expand for detailed view
- Weather widget supports location search and geolocation
- Grocery list allows adding, editing, and organizing items
- Calendar shows upcoming events with details
The dashboard is optimized for:
- Touchscreen kiosks
- Wall-mounted tablets
- Desktop and mobile browsers
- Large displays and projectors
- OAuth2 Authentication for Google Calendar
- Environment Variables for sensitive configuration
- Input Validation with Pydantic schemas
- CORS Protection for API endpoints
- Secure Credential Storage (never committed to git)
# Backend
cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000
# Frontend
cd frontend
npm run devSee deployment guides in the component READMEs:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow Conventional Commits for commit messages
- Write tests for new features
- Update documentation for API changes
- Follow the established code style and patterns
This project is licensed under the MIT License - see the LICENSE file for details.
- SvelteKit for the amazing frontend framework
- FastAPI for the modern Python backend
- Tailwind CSS for the utility-first styling
- Google Calendar API for calendar integration
- OpenWeatherMap for weather data
Made with ❤️ for families everywhere
📚 Ready to dive deeper? Start with our Getting Started Guide or explore the Documentation Hub.