Hestia

Project Overview

Hestia is a family-centric smart home dashboard designed to run on low-power devices — primarily a Raspberry Pi Zero mounted on a wall. It displays a live family calendar, weather conditions, to-do lists, shopping lists, meal plans, and news headlines, all driven by a FastAPI backend with real-time WebSocket updates. Configuration is handled from any browser through a React management app, while the wall display runs a lightweight HTMX + Alpine.js client in Chromium kiosk mode.

Technical Implementation

• Layered API Architecture: A versioned FastAPI backend (/api/v1) exposes focused routers for auth, families, displays, widgets, calendar integrations, weather, news, RSS, and WebSockets — each kept to a single responsibility.
• Multi-Protocol Calendar Sync: Dedicated integration clients for Google Calendar (OAuth 2.0), Microsoft Graph (MSAL), and CalDAV (RFC 4791) all follow the same boundary pattern, surfacing clean CalendarEvent typed contracts. Credentials are stored encrypted at rest using Fernet symmetric encryption.
• Real-Time Updates: A ConnectionManager class maintains per-display WebSocket connection sets, allowing the backend to broadcast widget data changes instantly to any active wall display without polling.
• Async Task Infrastructure: Celery workers handle background calendar syncs and weather refresh cycles, scheduled by Celery Beat with Redis as both broker and result backend — keeping API response times independent of external service latency.
• Defense-in-Depth Security: The middleware stack applies CORS, trusted host, content-type, and request-size validation before requests reach route handlers. A composite rate limiter (IP + user + global) with exponential backoff, bcrypt password hashing with timing-attack protection, and full WebAuthn/passkey support are baked in at the core layer.
• Dual Frontend Strategy: The wall display prioritises minimal resource consumption (Jinja2 templates + HTMX for server-driven updates), while the config app uses React 18 + TypeScript for a richer management experience. Shared TypeScript types live in an @hestia/shared npm workspace package, keeping contracts consistent across both frontends.

Development Journey

Hestia started as a straightforward idea: replace a static family whiteboard with a live, always-on display. The first iteration focused purely on showing a calendar and basic weather data on a Raspberry Pi. As the project grew, it became clear that a proper multi-tenant data model was needed — families, members, multiple displays, and configurable widget layouts — which drove the PostgreSQL + SQLAlchemy 2.0 data layer. Calendar integration was added incrementally, first Google, then Microsoft Graph, then CalDAV, each time refining the boundary pattern to keep external API volatility from leaking into the rest of the codebase. Authentication evolved from simple password auth into a full WebAuthn passkey implementation to avoid passwords on shared household accounts.

Key Features

• Live wall display running on Raspberry Pi Zero in Chromium kiosk mode
• Multi-calendar sync: Google Calendar, Microsoft Graph, and CalDAV (iCloud, Nextcloud, etc.)
• Family-scoped data model with role-based membership (admin / member / viewer)
• WebAuthn passkey authentication — no passwords required
• Real-time widget updates via WebSocket broadcast
• Configurable widget layouts per display with JSONB-stored grid and theme settings
• Background task workers for calendar sync, weather refresh, and RSS polling
• Shared TypeScript type library across React config app and display client
• Structured JSON logging with PII redaction and per-request trace IDs