Skip to content

README.md

Latest commit

 

History

History
252 lines (184 loc) · 8.33 KB

README.md

File metadata and controls

252 lines (184 loc) · 8.33 KB
Raw

Family Dashboard

A modern, modular dashboard for home and family organization built with SvelteKit and FastAPI.

License Python Node.js SvelteKit

🚀 Quick Start

# 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 dev

Visit http://localhost:5173 to see your dashboard!

📚 Need detailed setup instructions? Check out our Getting Started Guide

📋 Features

🗓️ Calendar Integration

  • Google Calendar Sync: Real-time family events and appointments
  • OAuth2 Authentication: Secure, token-based access
  • Event Display: Clean, readable event cards with details

🌤️ Weather Widget

  • 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

🛒 Grocery List

  • 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

📊 System Monitoring

  • Health Checks: Real-time system status via /health endpoint
  • Prometheus Metrics: Comprehensive monitoring via /metrics endpoint
  • 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

🏗️ Architecture

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

Technology Stack

Frontend:

Backend:

Integrations:

🔧 Setup

Prerequisites

  • 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

Credentials Setup

  1. Google Calendar Setup:

    • Create a project in Google Cloud Console
    • Enable Google Calendar API
    • Create OAuth2 credentials (Desktop application)
    • Download credentials file

  2. OpenWeatherMap Setup:

  3. Configure Credentials:

    cp templates/credentials_template.json backend/data/credentials.json
# Edit backend/data/credentials.json with your actual credentials

Installation

Detailed setup instructions are available in our comprehensive documentation:

🎯 Usage

Dashboard Overview

The dashboard is organized into four main quadrants:

┌────────────────┬────────────────┐
│  🌤️ Weather    │  🛒 Grocery   │
│────────────────┼────────────────│
│ Current Weather│ Shopping List  │
│ & Forecast     │ & Household    │
└────────────────┴────────────────┘
┌────────────────┬────────────────┐
│  📅 Calendar   │  🧹 Chores    │
│────────────────┼────────────────│
│ Family Events  │ Household Task │
│ & Appointments │ & Reminders    │
└────────────────┴────────────────┘

Key Interactions

  • 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

Mobile & Touch Support

The dashboard is optimized for:

  • Touchscreen kiosks
  • Wall-mounted tablets
  • Desktop and mobile browsers
  • Large displays and projectors

🔒 Security

  • 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)

🚀 Deployment

Development

# Backend
cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Frontend
cd frontend
npm run dev

Production

See deployment guides in the component READMEs:

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'feat: add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow Conventional Commits for commit messages
  • Write tests for new features
  • Update documentation for API changes
  • Follow the established code style and patterns

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Made with ❤️ for families everywhere

📚 Ready to dive deeper? Start with our Getting Started Guide or explore the Documentation Hub.