cassandra/home-information

Purpose and Runtime Entry Points

Home Information is a local-first Django application for spatially organizing home records, devices, controls, and security data on floor-plan/location views. HTTP entry points are the Django URL root and ASGI/WSGI servers: src/hi/urls.py, src/hi/asgi.py, src/hi/wsgi.py; src/manage.py is the management CLI. Production runs in Docker behind Nginx/Supervisor/Gunicorn (Dockerfile, package/docker_entrypoint.sh, src/bin/docker-start-gunicorn.sh).

Presentation and Spatial Workspace

The server-rendered Bootstrap/JavaScript UI centers on the reusable grid view and location-backed visual maps. Root views/templates provide the application shell; location views render and edit SVG floor plans, positioned entities, and collections.

• src/hi/hi_grid_view.py

• src/hi/apps/location/models.py

• src/hi/apps/location/svg_item_factory.py

• src/hi/apps/location/edit/views.py

Flow: browser interactions use static JS and Django routes; views invoke managers/models and return HTML fragments/pages. SVG geometry and persisted placement form the boundary between visual presentation and the domain model.

Core Home Domain

Entities represent home items/devices; locations and collections organize them; typed attributes attach documents, notes, values, thumbnails, history, and soft-delete behavior. Entity state panels select type-specific rendering for cameras, thermostats, smoke detectors, or a fallback.

• src/hi/apps/entity/models.py

• src/hi/apps/entity/entity_manager.py

• src/hi/apps/attribute/models.py

• src/hi/apps/entity/state_panel_registry.py

• src/hi/apps/collection/models.py

Integration Gateway and Synchronization

The integrations layer is the normalization boundary between third-party systems and internal entities, controllers, events, locations, and external references. Connector workflows discover/preview/synchronize remote data; importer and referencer workflows ingest or link external records. Integration metadata and identity fields allow sync reconciliation.

• src/hi/integrations/integration_gateway.py

• src/hi/integrations/integration_manager.py

• src/hi/integrations/connector/integration_connector.py

• src/hi/integrations/importer/integration_importer.py

• src/hi/integrations/referencer/integration_referencer.py

Concrete adapters support Home Assistant, Frigate, ZoneMinder, HomeBox, Immich, and Paperless-ngx under src/hi/services/, each using clients, converters, controllers/connectors, and integration registrations (for example src/hi/services/hass/integration.py, src/hi/services/frigate/frigate_connector.py).

Automation, Monitoring, and Notification Flow

Sensor updates/history feed event rules and monitor status. Event actions can invoke controllers or alarms; alert and notification queues manage user-visible/audio alarms and email delivery. Security aggregates relevant monitored state into modes/views.

• src/hi/apps/sense/sensor_response_manager.py

• src/hi/apps/event/event_manager.py

• src/hi/apps/control/controller_manager.py

• src/hi/apps/alert/alert_manager.py

• src/hi/apps/notify/notification_manager.py

• src/hi/apps/security/security_manager.py

Background Health and Weather

Periodic/background orchestration is centralized at src/hi/background_tasks.py; subsystems expose monitors and health providers aggregated into UI/API status. Weather independently discovers configured data sources, fetches/converts interval data, tracks daily aggregates, and can map weather alerts into alarms.

• src/hi/apps/system/aggregate_health_provider.py

• src/hi/apps/monitor/periodic_monitor.py

• src/hi/apps/weather/weather_manager.py

• src/hi/apps/weather/weather_source_manager.py

• src/hi/apps/weather/weather_alert_alarm_mapper.py

External weather sources include NWS, Open-Meteo, Sunrise-Sunset.org, and USNO.

Persistence, Deployment, and Simulation

Django ORM models/migrations persist application data; README specifies SQLite as the default local storage. Redis support exists in shared infrastructure (src/hi/apps/common/redis_client.py) and AWS utilities are isolated (src/hi/apps/common/aws_manager.py). Configuration is environment/Django-settings based: src/hi/settings/base.py, src/hi/settings/production.py.

A built-in simulator provides controllable substitute APIs, scenes, faults, and weather sources for development/testing without real integrations: src/hi/simulator/services/service_simulator.py, src/hi/simulator/scenes/player.py, src/hi/simulator/weather_sources/registry.py.