# cassandra/home-information architecture

> Architecture diagram of the GitHub repository cassandra/home-information, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cassandra/home-information
- Repository: https://github.com/cassandra/home-information

## Overview

#### 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`.

Main entry points: [`src/hi/apps/entity/entity_manager.py`](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/entity/entity_manager.py) (Entities & managers), [`src/hi/hi_grid_view.py`](https://github.com/cassandra/home-information/blob/staging/src/hi/hi_grid_view.py) (Spatial workspace), [`src/hi/apps/location/models.py`](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/location/models.py) (Locations & SVG maps), [`src/hi/apps/event/event_manager.py`](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/event/event_manager.py) (Events & controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & UI"]
  node_django_entrypoints{{"Django HTTP entry points<br/>Django runtime<br/>[urls.py]"}}
  node_manage_cli["Management CLI<br/>Django CLI<br/>[manage.py]"]
  node_workspace_ui["Spatial workspace<br/>server-rendered UI<br/>[hi_grid_view.py]"]
  node_location_maps["Locations &amp; SVG maps<br/>location domain<br/>[models.py]"]
  node_svg_factory["SVG item factory<br/>map renderer"]
end

subgraph group_domain["Home Domain"]
  node_entity_domain["Entities &amp; managers<br/>core domain<br/>[entity_manager.py]"]
  node_attributes["Typed attributes<br/>domain records<br/>[models.py]"]
  node_collections["Collections<br/>domain organization<br/>[models.py]"]
  node_state_panels["Entity state panels<br/>UI registry"]
end

subgraph group_integration["Integrations"]
  node_integration_gateway{{"Integration gateway<br/>normalization boundary"}}
  node_integration_workflows["Sync workflows<br/>connector/importer/referencer"]
  node_service_adapters["External service adapters<br/>integration adapters<br/>[integration.py]"]
end

subgraph group_automation["Automation &amp; Monitoring"]
  node_sensor_monitoring["Sensor responses &amp; monitors<br/>monitoring"]
  node_event_control["Events &amp; controllers<br/>automation<br/>[event_manager.py]"]
  node_alerts_notifications["Alerts &amp; notifications<br/>alarm delivery<br/>[alert_manager.py]"]
  node_security["Security status<br/>security aggregation"]
end

subgraph group_operations["Operations &amp; Data"]
  node_background_weather["Background tasks &amp; weather<br/>periodic orchestration"]
  node_health["Aggregate health<br/>health provider"]
  node_persistence[("Django ORM storage<br/>application database")]
  node_redis[("Redis support<br/>shared infrastructure<br/>[redis_client.py]")]
  node_simulator["Built-in simulator<br/>development services"]
  node_production_container["Production container<br/>deployment"]
end

node_django_entrypoints -->|"routes requests"| node_workspace_ui
node_manage_cli -->|"manages"| node_persistence
node_workspace_ui -->|"renders and edits"| node_location_maps
node_location_maps -->|"builds visual items"| node_svg_factory
node_svg_factory -->|"positions entities"| node_entity_domain
node_workspace_ui -->|"renders state"| node_state_panels
node_entity_domain -->|"owns typed data"| node_attributes
node_collections -->|"organizes"| node_entity_domain
node_location_maps -->|"persists placement"| node_persistence
node_entity_domain -->|"persists"| node_persistence
node_integration_workflows -->|"normalizes through"| node_integration_gateway
node_service_adapters -->|"discover and sync"| node_integration_workflows
node_integration_gateway -->|"reconciles entities"| node_entity_domain
node_sensor_monitoring -->|"feeds rules"| node_event_control
node_event_control -->|"raises alarms"| node_alerts_notifications
node_event_control -->|"invokes controllers"| node_entity_domain
node_sensor_monitoring -->|"provides monitored state"| node_security
node_background_weather -->|"runs periodically"| node_sensor_monitoring
node_background_weather -->|"maps weather alerts"| node_alerts_notifications
node_health -->|"exposes status"| node_workspace_ui
node_simulator -.->|"substitutes external APIs"| node_service_adapters
node_production_container -->|"serves"| node_django_entrypoints
node_redis -.->|"shared support"| node_background_weather

click node_django_entrypoints "https://github.com/cassandra/home-information/blob/staging/src/hi/urls.py"
click node_manage_cli "https://github.com/cassandra/home-information/blob/staging/src/manage.py"
click node_workspace_ui "https://github.com/cassandra/home-information/blob/staging/src/hi/hi_grid_view.py"
click node_location_maps "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/location/models.py"
click node_svg_factory "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/location/svg_item_factory.py"
click node_entity_domain "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/entity/entity_manager.py"
click node_attributes "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/attribute/models.py"
click node_collections "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/collection/models.py"
click node_state_panels "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/entity/state_panel_registry.py"
click node_integration_gateway "https://github.com/cassandra/home-information/blob/staging/src/hi/integrations/integration_gateway.py"
click node_integration_workflows "https://github.com/cassandra/home-information/blob/staging/src/hi/integrations/integration_manager.py"
click node_service_adapters "https://github.com/cassandra/home-information/blob/staging/src/hi/services/hass/integration.py"
click node_sensor_monitoring "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/sense/sensor_response_manager.py"
click node_event_control "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/event/event_manager.py"
click node_alerts_notifications "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/alert/alert_manager.py"
click node_security "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/security/security_manager.py"
click node_background_weather "https://github.com/cassandra/home-information/blob/staging/src/hi/background_tasks.py"
click node_health "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/system/aggregate_health_provider.py"
click node_redis "https://github.com/cassandra/home-information/blob/staging/src/hi/apps/common/redis_client.py"
click node_simulator "https://github.com/cassandra/home-information/blob/staging/src/hi/simulator/services/service_simulator.py"
click node_production_container "https://github.com/cassandra/home-information/blob/staging/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_django_entrypoints,node_manage_cli,node_workspace_ui,node_location_maps,node_svg_factory toneBlue
class node_entity_domain,node_attributes,node_collections,node_state_panels toneAmber
class node_integration_gateway,node_integration_workflows,node_service_adapters toneMint
class node_sensor_monitoring,node_event_control,node_alerts_notifications,node_security toneRose
class node_background_weather,node_health,node_persistence,node_redis,node_simulator,node_production_container toneIndigo
```

## Components

### Runtime & UI

- [Django HTTP entry points](https://github.com/cassandra/home-information/blob/staging/src/hi/urls.py): Django runtime · URL root and ASGI/WSGI application servers. · `src/hi/urls.py`
- [Management CLI](https://github.com/cassandra/home-information/blob/staging/src/manage.py): Django CLI · `src/manage.py`
- [Spatial workspace](https://github.com/cassandra/home-information/blob/staging/src/hi/hi_grid_view.py): server-rendered UI · Grid and location views render home records on floor plans. · `src/hi/hi_grid_view.py`
- [Locations & SVG maps](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/location/models.py): location domain · Persisted locations and SVG placement bridge the visual and domain models. · `src/hi/apps/location/models.py`
- [SVG item factory](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/location/svg_item_factory.py): map renderer · `src/hi/apps/location/svg_item_factory.py`

### Home Domain

- [Entities & managers](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/entity/entity_manager.py): core domain · Home items and devices are managed as internal entities. · `src/hi/apps/entity/entity_manager.py`
- [Typed attributes](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/attribute/models.py): domain records · Attaches values, documents, notes, media, history, and soft-delete state. · `src/hi/apps/attribute/models.py`
- [Collections](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/collection/models.py): domain organization · `src/hi/apps/collection/models.py`
- [Entity state panels](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/entity/state_panel_registry.py): UI registry · Selects type-specific device state rendering. · `src/hi/apps/entity/state_panel_registry.py`

### Integrations

- [Integration gateway](https://github.com/cassandra/home-information/blob/staging/src/hi/integrations/integration_gateway.py): normalization boundary · Normalizes external records into internal domain concepts. · `src/hi/integrations/integration_gateway.py`
- [Sync workflows](https://github.com/cassandra/home-information/blob/staging/src/hi/integrations/integration_manager.py): connector/importer/referencer · Discovers, previews, synchronizes, imports, and links remote records. · `src/hi/integrations/integration_manager.py`
- [External service adapters](https://github.com/cassandra/home-information/blob/staging/src/hi/services/hass/integration.py): integration adapters · Home Assistant, Frigate, ZoneMinder, HomeBox, Immich, and Paperless-ngx adapters. · `src/hi/services/hass/integration.py`

### Automation & Monitoring

- [Sensor responses & monitors](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/sense/sensor_response_manager.py): monitoring · Processes sensor updates, history, and periodic monitored state. · `src/hi/apps/sense/sensor_response_manager.py`
- [Events & controllers](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/event/event_manager.py): automation · Rules trigger actions that invoke controllers or alarms. · `src/hi/apps/event/event_manager.py`
- [Alerts & notifications](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/alert/alert_manager.py): alarm delivery · Queues user-visible/audio alarms and email delivery. · `src/hi/apps/alert/alert_manager.py`
- [Security status](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/security/security_manager.py): security aggregation · Aggregates monitored state into security modes and views. · `src/hi/apps/security/security_manager.py`

### Operations & Data

- [Background tasks & weather](https://github.com/cassandra/home-information/blob/staging/src/hi/background_tasks.py): periodic orchestration · Runs subsystem work and weather source, aggregate, and alert processing. · `src/hi/background_tasks.py`
- [Aggregate health](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/system/aggregate_health_provider.py): health provider · Aggregates subsystem health for UI/API status. · `src/hi/apps/system/aggregate_health_provider.py`
- **Django ORM storage**: application database · Models and migrations persist local-first application data.
- [Redis support](https://github.com/cassandra/home-information/blob/staging/src/hi/apps/common/redis_client.py): shared infrastructure · `src/hi/apps/common/redis_client.py`
- [Built-in simulator](https://github.com/cassandra/home-information/blob/staging/src/hi/simulator/services/service_simulator.py): development services · Provides substitute APIs, scenes, faults, and weather sources. · `src/hi/simulator/services/service_simulator.py`
- [Production container](https://github.com/cassandra/home-information/blob/staging/Dockerfile): deployment · Docker runs behind Nginx, Supervisor, and Gunicorn. · `Dockerfile`

## Connections

- Django HTTP entry points → Spatial workspace: routes requests
- Management CLI → Django ORM storage: manages
- Spatial workspace → Locations & SVG maps: renders and edits
- Locations & SVG maps → SVG item factory: builds visual items
- SVG item factory → Entities & managers: positions entities
- Spatial workspace → Entity state panels: renders state
- Entities & managers → Typed attributes: owns typed data
- Collections → Entities & managers: organizes
- Locations & SVG maps → Django ORM storage: persists placement
- Entities & managers → Django ORM storage: persists
- Sync workflows → Integration gateway: normalizes through
- External service adapters → Sync workflows: discover and sync
- Integration gateway → Entities & managers: reconciles entities
- Sensor responses & monitors → Events & controllers: feeds rules
- Events & controllers → Alerts & notifications: raises alarms
- Events & controllers → Entities & managers: invokes controllers
- Sensor responses & monitors → Security status: provides monitored state
- Background tasks & weather → Sensor responses & monitors: runs periodically
- Background tasks & weather → Alerts & notifications: maps weather alerts
- Aggregate health → Spatial workspace: exposes status
- Built-in simulator → External service adapters: substitutes external APIs
- Production container → Django HTTP entry points: serves
- Redis support → Background tasks & weather: shared support