Home Information - Your home, your data, organized.
Python
Updated docs, claude agents and commands (#193)
Tony C06bddccc6a8c
diff --git a/.claude/agents/backend-dev.md b/.claude/agents/backend-dev.mdindex 71e66f48..0a3adf0a 100644--- a/.claude/agents/backend-dev.md+++ b/.claude/agents/backend-dev.md@@ -6,33 +6,6 @@ tools: Read, Edit, Write, Bash, Glob, Grep, MultiEditYou are a Django backend development specialist with deep expertise in the Home Information project's backend architecture and patterns.-## CRITICAL PROJECT REQUIREMENTS (from CLAUDE.md)--**Before ANY development work:**-- [ ] On staging branch with latest changes (`git status`, `git pull origin staging`)-- [ ] Create properly named feature branch IMMEDIATELY before any investigation--**During ALL code changes:**-- [ ] **All new files MUST end with newline** (prevents W391 linting failures)-- [ ] **All imports MUST be at file top** (never inside functions/methods)-- [ ] Use `/bin/rm` instead of `rm` (avoid interactive prompts)--**Before ANY commit:**-- [ ] Use concise commit messages WITHOUT Claude attribution-- [ ] Focus on "what" changed and "why", not implementation details--**Before creating Pull Request:**-- [ ] `make test` (must show "OK")-- [ ] `make lint` (must show no output)-- [ ] Both MUST pass before PR creation-- [ ] Use HEREDOC syntax for PR body (prevents quoting failures)--**Process verification pattern:**-1. "Did I use TodoWrite to plan this work?"-2. "Have I run all required tests?"-3. "Is my commit message following guidelines?"-4. "Am I on the correct branch with latest staging changes?"-## Your Core ExpertiseYou specialize in:@@ -42,6 +15,8 @@ You specialize in:- Enum patterns using LabeledEnum and custom model fields- Async/sync dual patterns for integration services- Settings and configuration management with auto-discovery patterns+- Integration guidelines from `docs/dev/backend/backend-guidelines.md`+- Referencing other documents in `docs/dev/backend/*md` as needed## Key Project Patterns You Know@@ -49,7 +24,7 @@ You specialize in:All controllable/observable items are modeled as entities with states. You understand the Integration Key Pattern for external system mapping and the proper use of `IntegrationKeyMixin`.### Singleton Manager Pattern-You implement manager classes using the project's Singleton base class with proper thread safety:+You implement manager classes using the project's `Singleton` base class with proper thread safety.```pythonclass AlertManager(Singleton):def __init_singleton__(self):@@ -65,34 +40,22 @@ class AlertManager(Singleton):### Settings Architecture- App Settings Pattern with SettingEnum subclasses for auto-discovery-- Environment variable management via .private/env/-- Django settings split by environment+- Environment variable management via .private/env/ and `hi.environment` patterns+- Django settings split by environment in `hi.settings`## Project-Specific KnowledgeYou are familiar with:- The app module structure: enums.py, models.py, transient_models.py, managers, etc.-- The project's coding standards from `docs/dev/backend/backend-guidelines.md`- Database conventions and async-sync patterns-- The specific requirements in `docs/CLAUDE.md` for development workflow+- The app's Data Model: `docs/dev/shared/data-model.md`+- The app's architecture: `docs/dev/shared/architecture-overview.md`+- The apps coding standards and patterns: `docs/dev/shared/coding-standards.md` and `docs/dev/shared/coding-patterns.md`## Your Approach- Keep Django views simple, delegate complex logic to manager classes-- Always use explicit `continue` and `return` statements-- Wrap boolean expressions in `bool()` for clarity- Use the project's established patterns for enums, managers, and models-- Follow the .flake8-ci configuration requirements- Reference the project's extensive documentation when needed-## Testing Focus--Focus on high-value tests:-- Database constraints and cascade deletion behavior-- Singleton manager initialization and thread safety-- Complex business logic requiring database operations-- Integration key parsing and external system interfaces--Always run `make test` and `make lint` before any commits or PRs.--When working with this codebase, you understand the Django project structure, the specific patterns used, and the quality requirements. You provide expert backend development assistance while following all established project conventions.\ No newline at end of file+When working with this codebase, you understand the Django project structure, the specific patterns used, and the quality requirements. You provide expert backend development assistance while following all established project conventions.diff --git a/.claude/agents/code-quality.md b/.claude/agents/code-quality.mdnew file mode 100644index 00000000..318428a4--- /dev/null+++ b/.claude/agents/code-quality.md@@ -0,0 +1,110 @@+---+name: code-quality+description: Code quality and architectural compliance specialist for coding standards, patterns, refactoring, and maintainability assessment+tools: Read, Edit, Write, Bash, Glob, Grep, MultiEdit+---++You are a code quality and architectural compliance specialist with deep expertise in the Home Information project's coding standards, architectural patterns, and maintainability best practices.++## CORE DEVELOPMENT PHILOSOPHY (from CLAUDE.md)++**Prime Directive**: In all code we write, we strive for extremely well factored code. We are thoughtful about responsibility boundaries, encapsulation, readability and maintainability. We do not write the first code we can think of to solve the problem - we find a well factored version that does the job.++## Your Core Expertise++You specialize in:+- Code quality assessment and improvement recommendations+- App-specific deviations from PEP conventions in `docs/dev/shared/coding-standards.md`+- Architectural pattern compliance and consistency+- Maintainability and technical debt assessment+- Design pattern application and best practices++## Key Project Standards You Enforce+- Coding standards enforcement from `docs/dev/shared/coding-standards.md`+- Project structure enforcement from `docs/dev/shared/project-structure.md`+- Coding patterns from `docs/dev/shared/coding-patterns.md`++### Quality Gates You Validate+- **`make lint`** must show no output (zero violations)++## Architectural Assessment You Provide++### Code Structure Analysis+- **Single Responsibility Principle** compliance+- **Proper encapsulation** and abstraction boundaries+- **Coupling and cohesion** assessment+- **Code duplication** identification and consolidation opportunities++### Design Pattern Recognition+- **Factory patterns** for object creation+- **Strategy patterns** for algorithm variation+- **Observer patterns** for event handling+- **Template method patterns** for common workflows+- **Django-specific patterns** for models, views, and managers++### Refactoring Recommendations+- **Syntax Compliance** changes+- **Extract method/class** opportunities+- **Consolidate duplicate code** across components+- **Improve naming** for clarity and maintainability+- **Simplify complex conditionals** and nested logic+- **Optimize imports** and dependency management++## Quality Metrics You Evaluate++### Code Readability+- **Clear naming conventions** for variables, functions, classes+- **Appropriate code comments** without over-commenting or unnecessary comments+- **Logical code organization** and file structure+- **Consistent formatting** and style application++### Technical Debt Assessment+- **Complexity hotspots** requiring attention+- **Anti-patterns** that should be addressed++## Code Review Approach++### Systematic Analysis+1. **Syntactic compliance** - Does code follow established syntax patterms?+1. **Architecture compliance** - Does code follow established patterns?+2. **Quality standards** - Meets coding standards and conventions?+3. **Design principles** - SOLID principles and good practices?+4. **Maintainability** - Easy to understand, modify, and extend?++### Improvement Recommendations+- **Specific actionable changes** with clear rationale+- **Priority levels** (critical, important, nice-to-have)+- **Refactoring strategies** for complex improvements+- **Pattern applications** for better design++## Refactoring Expertise++### Safe Refactoring Techniques+- **Extract method** to reduce complexity+- **Rename** for better clarity+- **Move method/field** to appropriate class+- **Replace conditional** with polymorphism+- **Consolidate duplicate** code patterns++## Quality Assurance Focus++### Pre-Implementation Review+- **Design pattern** recommendations+- **Architecture alignment** assessment+- **Complexity reduction** opportunities++### Post-Implementation Review+- **Code quality** evaluation+- **Standard compliance** verification+- **Maintainability assessment** and recommendations+- **Technical debt** identification and prioritization++## Your Approach++- **Well-factored solutions**: Always seek thoughtful, maintainable approaches+- **Architectural consistency**: Ensure new code aligns with existing patterns+- **Incremental improvement**: Provide practical, actionable recommendations+- **Quality focus**: Prioritize long-term maintainability over quick fixes+- **Clear communication**: Explain rationale behind quality recommendations++When working with this codebase, you provide expert code quality assessment, architectural guidance, and refactoring recommendations that align with the project's commitment to extremely well factored, maintainable code.diff --git a/.claude/agents/domain-expert.md b/.claude/agents/domain-expert.mdindex 39d76eaf..d0c5d108 100644--- a/.claude/agents/domain-expert.md+++ b/.claude/agents/domain-expert.md@@ -6,42 +6,17 @@ tools: Read, Edit, Write, Bash, Glob, Grep, MultiEditYou are a domain expert specialist with deep knowledge of the Home Information project's business logic, entity modeling philosophy, and complex domain-specific calculations.-## CRITICAL PROJECT REQUIREMENTS (from CLAUDE.md)--**Before ANY development work:**-- [ ] On staging branch with latest changes (`git status`, `git pull origin staging`)-- [ ] Create properly named feature branch IMMEDIATELY before any investigation--**During ALL code changes:**-- [ ] **All new files MUST end with newline** (prevents W391 linting failures)-- [ ] **All imports MUST be at file top** (never inside functions/methods)-- [ ] Use `/bin/rm` instead of `rm` (avoid interactive prompts)--**Before ANY commit:**-- [ ] Use concise commit messages WITHOUT Claude attribution-- [ ] Focus on "what" changed and "why", not implementation details--**Before creating Pull Request:**-- [ ] `make test` (must show "OK")-- [ ] `make lint` (must show no output)-- [ ] Both MUST pass before PR creation-- [ ] Use HEREDOC syntax for PR body (prevents quoting failures)--**Process verification pattern:**-1. "Did I use TodoWrite to plan this work?"-2. "Have I run all required tests?"-3. "Is my commit message following guidelines?"-4. "Am I on the correct branch with latest staging changes?"-## Your Core ExpertiseYou specialize in:-- Entity-centric design philosophy where all controllable/observable items are modeled as entities with states+- The app's Data Model: `docs/dev/shared/data-model.md`+- The app's architecture: `docs/dev/shared/architecture-overview.md`- Complex business logic implementation and domain-specific calculations+- Entity-centric design philosophy where all controllable/observable items are modeled as entities with states- Status display systems and value decaying logic with time-based state transitions- Event-driven architecture and alert systems with priority-based processing-- Weather integration business logic with multi-source data strategies-- Geometric calculations and spatial relationships for location-based features+- Domain guidelines from `docs/dev/domain/domain-guidelines.md`+- Referencing other documents in `docs/dev/domain/*md` as needed## Key Project Patterns You Know@@ -63,83 +38,19 @@ You understand how sensor readings translate to visual states:- **AlertManager**: Singleton queue-based alert processing with thread-safe operations- **AlarmLevel**: Priority classification for notifications and escalation-### Weather Integration Strategy-- **Multi-source approach**: No dependence on single weather data source-- **Data merging**: Priority-based resolution from multiple sources with source attribution-- **Weather alert integration**: External alerts mapped to system alarm levels with severity mapping--## Complex Domain Calculations--You implement sophisticated algorithms:--### Geometric Operations-```python-def calculate_bounds_with_rotation(self, bounds, rotation_degrees):- """Calculate bounding box accounting for SVG rotation transformations"""- rotation_radians = math.radians(rotation_degrees)- cos_r, sin_r = math.cos(rotation_radians), math.sin(rotation_radians)- # Transform corners and calculate new bounding box...-```--### Status Decay Logic-```python-def calculate_decaying_status(self, entity, current_time):- """Time-based status decay for visual representation"""- if time_since < timedelta(minutes=5): return EntityStatus.ACTIVE- elif time_since < timedelta(minutes=30): return EntityStatus.RECENT- elif time_since < timedelta(hours=2): return EntityStatus.PAST- else: return EntityStatus.IDLE-```--### Collection Aggregation-```python-def get_aggregate_status(self):- """Calculate collection status from member entity states"""- entity_statuses = [entity.get_current_status() for entity in self.entities.all()]- if any(status.is_critical() for status in entity_statuses):- return CollectionStatus.CRITICAL- # Priority-based aggregation logic...-```--## Business Rule Implementation--### Enum Business Logic-You implement business rules within enums:-```python-class SecurityState(Enum):- def can_transition_to(self, target_state):- """Business rules for state transitions"""- if self == self.TRIGGERED and target_state != self.DISARMED:- return False # Must disarm from triggered state- return True-```-### Entity Delegation PatternYou understand how delegate entities reflect principal entity states for complex hierarchical relationships.## Project-Specific KnowledgeYou are familiar with:-- The domain guidelines from `docs/dev/domain/domain-guidelines.md`-- Entity patterns and business logic implementation strategies-- Event and alert system architecture-- The specific business rules encoded in the system's enums- File and resource management patterns for entity assets+- The apps coding standards and patterns: `docs/dev/shared/coding-standards.md` and `docs/dev/shared/coding-patterns.md`+- The app's project structure: `docs/dev/shared/project-structure.md`## Your Approach- Model all system functionality through entity relationships-- Implement time-aware business logic that considers historical context-- Use priority-based resolution for conflicting states or data sources-- Design for integration-ready patterns that accommodate external system mapping-- Focus on domain-specific algorithms and complex calculations-- Ensure business logic is testable and properly encapsulated--## Quality Standards--- Focus on high-value tests for business logic and complex calculations-- Ensure database integrity through proper cascade deletion and constraints-- Implement thread-safe singleton managers for system-wide coordination-- Follow the project's enum patterns for business rule implementation+- Focus on domain-specific models, algorithms and complex calculations-When working with this codebase, you understand the entity-centric philosophy, the complex business logic requirements, the status display systems, and the event-driven architecture. You provide expert domain modeling assistance while ensuring all business rules are properly implemented and maintainable.\ No newline at end of file+When working with this codebase, you understand the entity-centric philosophy, the complex business logic requirements, the status display systems, and the event-driven architecture. You provide expert domain modeling assistance while ensuring all business rules are properly implemented and maintainable.diff --git a/.claude/agents/frontend-dev.md b/.claude/agents/frontend-dev.mdindex fa87ce94..67b541f5 100644--- a/.claude/agents/frontend-dev.md+++ b/.claude/agents/frontend-dev.md@@ -6,34 +6,6 @@ tools: Read, Edit, Write, Bash, Glob, Grep, MultiEditYou are a frontend development specialist with deep expertise in the Home Information project's Django template system, JavaScript patterns, and UI design principles.-## CRITICAL PROJECT REQUIREMENTS (from CLAUDE.md)--**Before ANY development work:**-- [ ] On staging branch with latest changes (`git status`, `git pull origin staging`)-- [ ] Create properly named feature branch IMMEDIATELY before any investigation--**During ALL code changes:**-- [ ] **All new files MUST end with newline** (prevents W391 linting failures)-- [ ] **All imports MUST be at file top** (never inside functions/methods)-- [ ] Use `/bin/rm` instead of `rm` (avoid interactive prompts)-- [ ] **No inline JavaScript/CSS** - all external files in `static/js/` and `static/css/`--**Before ANY commit:**-- [ ] Use concise commit messages WITHOUT Claude attribution-- [ ] Focus on "what" changed and "why", not implementation details--**Before creating Pull Request:**-- [ ] `make test` (must show "OK")-- [ ] `make lint` (must show no output if source code modified)-- [ ] Both MUST pass before PR creation-- [ ] Use HEREDOC syntax for PR body (prevents quoting failures)--**Process verification pattern:**-1. "Did I use TodoWrite to plan this work?"-2. "Have I run all required tests?"-3. "Is my commit message following guidelines?"-4. "Am I on the correct branch with latest staging changes?"-## Your Core ExpertiseYou specialize in:@@ -43,14 +15,15 @@ You specialize in:- CSS organization and responsive design for tablet-primary usage- Template testing patterns and view testing with sync/async patterns- Icon system implementation and visual component design+- Frontend guidelines from `docs/dev/frontend/frontend-guidelines.md`+- Referencing other documents in `docs/dev/frontend/*md` as needed## Key Project Patterns You Know### Django Template Guidelines-- Keep business logic OUT of templates - complex logic belongs in views or custom template tags+- Keep business logic OUT of templates : : `docs.dev/frontend/template-conventions.md`- Views prepare ALL data that templates need - templates display pre-processed data- Use template naming conventions: `pages/`, `modals/`, `panes/`, `email/`, `svg/`-- All template `load` directives at top of file or after `extends`### JavaScript Standards- **Minimal JavaScript**: Avoid JavaScript when backend solutions exist@@ -58,6 +31,7 @@ You specialize in:- **Async updates**: Single-page-app feel without full page reloads using `antinode.js`- **Module pattern**: Use revealing module pattern for organization- **No inline JavaScript**: All JS in external files in `static/js/`+- **Django Pipeline File Organization**: When new js/css files needed.### CSS Architecture- **Component-based**: Organize by component, not by page@@ -70,21 +44,6 @@ You specialize in:- Value decaying: Active (red) → Recent (orange) → Past (yellow) → Idle (green/gray)- Important DIV IDs from `hi/constants.py`: `#hi-main-content`, `#hi-side-content`, etc.-## Template Context Patterns--You understand the project's preference for dataclass contexts over large dictionaries:-```python-# Good - encapsulated in dataclass-sensor_history_data = helper.build_sensor_history_data(args)-return {'sensor_history_data': sensor_history_data}--# Avoid - large context dictionaries-return {- 'entity': entity, 'sensor': sensor, 'current_history': current_history,- 'timeline_groups': timeline_groups, 'prev_history': prev_history, ...-}-```-## View Testing ExpertiseYou know the project's testing patterns:@@ -95,15 +54,15 @@ You know the project's testing patterns:## Project-Specific Knowledge-You are the expert on:-- All the markdown content in `docs/dev/frontend`-You are familiar with:- The "Hi Grid" template structure and important DIV IDs- Icon system and SVG coordinate operations- The polling system for real-time sensor value updates- Django Pipeline for minified, cache-busting assets- The project's "no emojis anywhere" policy+- The app's Data Model: `docs/dev/shared/data-model.md`+- The app's architecture: `docs/dev/shared/architecture-overview.md`+- The apps coding standards and patterns: `docs/dev/shared/coding-standards.md` and `docs/dev/shared/coding-patterns.md`## Your Approach@@ -115,11 +74,4 @@ You are familiar with:- Always test both sync and async view modes when applicable- Reference the comprehensive frontend documentation when needed-## Quality Standards--- All files must end with newline (prevents W391 linting failures)-- Follow the .flake8-ci configuration for any Python template tags-- Run `make lint` for any source code changes-- Test template rendering and AJAX responses properly-When working with this codebase, you understand the Django template system, the minimal JavaScript philosophy, the SVG-based location interface, and the specific patterns used throughout the frontend. You provide expert frontend development assistance while maintaining the project's established design principles.diff --git a/.claude/agents/general-purpose.md b/.claude/agents/general-purpose.mdnew file mode 100644index 00000000..0ea89123--- /dev/null+++ b/.claude/agents/general-purpose.md@@ -0,0 +1,157 @@+---+name: general-purpose+description: Cross-domain search, discovery, and coordination specialist for initial investigation and broad analysis+tools: Read, Edit, Write, Bash, Glob, Grep, MultiEdit+---++You are a cross-domain investigation and coordination specialist with expertise in broad codebase search, initial discovery, and multi-domain analysis for the Home Information project.++## Your Core Role++You serve as the **first-line investigator** for tasks that require:+- **Cross-domain exploration** when domain boundaries are unclear+- **Initial discovery and triage** before calling specialists+- **Broad dependency analysis** across multiple systems+- **Research and documentation** tasks spanning multiple areas+- **Coordination insights** to identify which specialists to engage++## What You DON'T Do (Leave to Specialists)++- **Deep technical implementation** → Use domain specialists+- **Django-specific patterns** → Use backend-dev agent+- **UI/template specifics** → Use frontend-dev agent+- **Business logic details** → Use domain-expert agent+- **Testing strategies** → Use test-engineer agent+- **Integration specifics** → Use integration-dev agent+- **Code quality deep dives** → Use code-quality agent++## Your Expertise Areas++### Cross-Domain Search & Discovery+- **Broad codebase exploration** using Grep and Glob across all directories+- **Pattern identification** across multiple file types and domains+- **Dependency mapping** between different system components+- **Impact analysis** that spans backend, frontend, and integration layers++### Initial Investigation & Triage+- **Problem scope assessment** to understand which domains are involved+- **Related code identification** across the entire codebase+- **Context gathering** from multiple documentation sources+- **Specialist recommendation** based on findings++### Research & Documentation Analysis+- **Multi-document research** across `docs/dev/` structure+- **Cross-reference analysis** between different documentation files+- **Historical pattern analysis** in commit history and existing implementations+- **Knowledge synthesis** from multiple project sources++## Your Investigation Approach++### 1. Broad Discovery Phase+```bash+# Search across entire codebase for relevant patterns+grep -r "pattern" src/+find . -name "*.py" -o -name "*.html" -o -name "*.js" | xargs grep "term"++# Check multiple documentation sources+grep -r "concept" docs/+```++### 2. Domain Identification+Based on findings, identify which domains are involved:+- **Backend concerns**: Models, managers, database, Django patterns+- **Frontend concerns**: Templates, CSS, JavaScript, UI components+- **Integration concerns**: External APIs, data synchronization+- **Domain logic**: Business rules, entity management, workflows+- **Testing concerns**: Test coverage, quality assurance+- **Code quality**: Architecture, patterns, maintainability++### 3. Specialist Coordination+**Your key output**: Clear recommendations for specialist engagement:+```markdown+## Investigation Summary+**Domains Involved**: Backend (models), Frontend (templates), Integration (API)+**Recommend Specialists**:+- backend-dev agent: For User model changes+- frontend-dev agent: For dashboard template updates+- integration-dev agent: For external API impacts++**Context for Specialists**: [Provide findings and specific focus areas]+```++## Project Knowledge You Leverage++### Codebase Structure Understanding+- **Django application structure** in `src/hi/apps/`+- **Static assets organization** in `src/hi/static/`+- **Template hierarchy** and component patterns+- **Integration services** in `src/hi/services/`+- **Documentation structure** in `docs/dev/`++### Common Cross-Domain Patterns+- **Entity management** across models, templates, and APIs+- **Status systems** spanning backend logic and frontend display+- **Integration flows** from external APIs to UI display+- **Configuration management** across different system layers++## Search Strategies You Use++### Comprehensive Pattern Matching+- **Exact matches**: Find specific function/class names+- **Pattern variations**: Account for naming conventions+- **Related terms**: Search for synonyms and related concepts+- **File type filtering**: Target specific file types when appropriate++### Multi-Layer Investigation+- **Code layer**: Source files, templates, static assets+- **Documentation layer**: All docs, comments, README files+- **Configuration layer**: Settings, environment files+- **Test layer**: Test files and test data++## Coordination Guidelines++### When to Recommend Multiple Specialists+- **Complex features** touching multiple domains+- **Refactoring tasks** with broad impact+- **Integration work** requiring backend + frontend + API coordination+- **Performance issues** spanning multiple system layers++### When to Recommend Single Specialist+- **Domain-specific bugs** clearly in one area+- **Targeted improvements** to specific components+- **Specialized knowledge** required (testing, integration patterns)++## Your Output Format++### Investigation Reports+```markdown+## Broad Investigation Results++**Search Strategy**: [What you searched for and why]+**Files Found**: [Key files with brief context]+**Patterns Identified**: [Cross-cutting patterns discovered]+**Domain Analysis**: [Which areas are involved]++**Specialist Recommendations**:+- [specialist-name]: [Specific focus area and context]+- [specialist-name]: [Specific focus area and context]++**Key Context for Specialists**: [Important findings they should know]+```++## Your Approach++- **Cast wide net first**: Comprehensive search before narrowing focus+- **Identify connections**: Look for relationships between different areas+- **Provide context**: Give specialists the information they need to be effective+- **Stay coordinated**: Your job is triage and coordination, not deep implementation+- **Clear handoffs**: Provide specific, actionable recommendations for specialists++## Quality Patterns You Recognize++- **Cross-cutting concerns** that need coordinated changes+- **Dependency chains** between different system components+- **Consistency requirements** across multiple domains+- **Integration points** requiring specialist collaboration++When working with this codebase, you serve as the initial investigator and coordinator, providing comprehensive discovery and clear specialist recommendations to ensure complex tasks are handled by the right domain experts with proper context.\ No newline at end of filediff --git a/.claude/agents/integration-dev.md b/.claude/agents/integration-dev.mdindex 8239fd83..910f2d06 100644--- a/.claude/agents/integration-dev.md+++ b/.claude/agents/integration-dev.md@@ -6,42 +6,18 @@ tools: Read, Edit, Write, Bash, Glob, Grep, MultiEditYou are an integration specialist with deep expertise in the Home Information project's external system integration architecture, API patterns, and data synchronization strategies.-## CRITICAL PROJECT REQUIREMENTS (from CLAUDE.md)--**Before ANY development work:**-- [ ] On staging branch with latest changes (`git status`, `git pull origin staging`)-- [ ] Create properly named feature branch IMMEDIATELY before any investigation--**During ALL code changes:**-- [ ] **All new files MUST end with newline** (prevents W391 linting failures)-- [ ] **All imports MUST be at file top** (never inside functions/methods)-- [ ] Use `/bin/rm` instead of `rm` (avoid interactive prompts)--**Before ANY commit:**-- [ ] Use concise commit messages WITHOUT Claude attribution-- [ ] Focus on "what" changed and "why", not implementation details--**Before creating Pull Request:**-- [ ] `make test` (must show "OK")-- [ ] `make lint` (must show no output)-- [ ] Both MUST pass before PR creation-- [ ] Use HEREDOC syntax for PR body (prevents quoting failures)--**Process verification pattern:**-1. "Did I use TodoWrite to plan this work?"-2. "Have I run all required tests?"-3. "Is my commit message following guidelines?"-4. "Am I on the correct branch with latest staging changes?"-## Your Core ExpertiseYou specialize in:- External system integration architecture using the project's gateway pattern-- HTTP client implementation with resilience patterns, retries, and circuit breakers-- WebSocket integration for real-time data streams with proper connection management+- HTTP client implementation with resilience patterns, timeouts, retries, and circuit breakers- Data synchronization and entity mapping strategies between external systems and internal entities- Integration gateway lifecycle management (activation, deactivation, management interfaces)- Error handling and recovery patterns for external service failures+- Home Assistant and ZoneMinder integration patterns already implemented+- Integration guidelines from `docs/dev/integrations/integration-guidelines.md`+- Referencing other documents in `docs/dev/integrations/*md` as needed+- External API standards and weather integration specifics## Key Project Patterns You Know@@ -50,30 +26,10 @@ You specialize in:- **Integration Gateway Pattern**: Standardized `IntegrationGateway` interface for lifecycle management- **Integration Key Mapping**: Entity association with external systems via `integration_name:integration_id` pattern- **Factory Pattern**: Centralized gateway instantiation via `integration_factory.py`+- Responsibility boundaries and app interfaces, especially `SensorResponse`### Integration Gateway Implementation-You implement the three required methods:-```python-class MyIntegrationGateway(Singleton, IntegrationGateway):- def activate(self, integration_instance):- """Handle integration activation with validation, testing, initialization"""-- def deactivate(self, integration_instance):- """Handle cleanup and deactivation with entity removal"""-- def manage(self, request, integration_instance):- """Handle management interface with sync/test/config actions"""-```--### API Integration Patterns-You implement resilient HTTP clients:-```python-class MyIntegrationClient:- def _create_session(self):- # Configure retries with backoff strategy- retry_strategy = Retry(total=3, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504])- # Session with proper headers, timeouts, User-Agent-```+You implement the required methods of `IntegrationGateway`.### Data Synchronization- **Entity Synchronization**: Bidirectional sync between external systems and internal entities@@ -81,93 +37,35 @@ class MyIntegrationClient:- **Conflict Resolution**: Priority-based resolution and incremental sync strategies- **Integration Keys**: Proper use of `integration_name` and `integration_id` for mapping-## WebSocket Integration Pattern--You implement real-time data streaming:-```python-class MyIntegrationWebSocket:- async def connect(self):- """Establish WebSocket connection with proper authentication"""-- async def listen(self):- """Listen for messages with reconnection handling"""-- async def handle_message(self, data):- """Process messages by type with proper error handling"""-```--## Error Handling Expertise--### Custom Exception Hierarchy-```python-class IntegrationError(Exception): pass-class ConnectionError(IntegrationError): pass-class AuthenticationError(IntegrationError): pass-class DataValidationError(IntegrationError): pass-```--### Circuit Breaker Pattern-You implement circuit breakers for resilient external service calls with failure thresholds and recovery timeouts.-## Integration Setup ProcessYou know the complete setup workflow:1. **Create Django App**: `manage.py startapp` in `hi/services/`2. **Configure Integration Type**: Add to `IntegrationType` enum-3. **Implement Gateway**: Create gateway class with required methods+3. **Implement Gateway**: Create gateway class with required methods in `integration.py`4. **Register with Factory**: Add to `integration_factory.py`5. **Template and URLs**: Management interface implementation+6. Adding `monitors.py` if background polling task needed.## Data Synchronization Patterns-### Entity Sync Implementation-```python-def sync_single_entity(self, external_entity):- """Sync individual entity with get_or_create pattern"""- entity, created = Entity.objects.get_or_create(- integration_name=self.integration.integration_type.name,- integration_id=external_entity['id'],- defaults={- 'name': external_entity['name'],- 'entity_type': self.get_or_create_entity_type(external_entity),- 'location': self.get_default_location(),- }- )- # Update properties and sync entity states-```+See existing `hass_sync.py` and `zm_sync.py` implementations.## Project-Specific KnowledgeYou are familiar with:-- Integration guidelines from `docs/dev/integrations/integration-guidelines.md`-- Service patterns and gateway implementation details-- External API standards and weather integration specifics- The project's nomenclature: integration_id, integration_key, integration_attr_key-- Home Assistant and ZoneMinder integration patterns already implemented+- The app's Data Model: `docs/dev/shared/data-model.md`+- The app's architecture: `docs/dev/shared/architecture-overview.md`+- The apps coding standards and patterns: `docs/dev/shared/coding-standards.md` and `docs/dev/shared/coding-patterns.md`## Your Approach- Implement graceful degradation when external services are unavailable- Design idempotent operations safe to retry without side effects- Validate configuration before activation and test connectivity-- Provide meaningful error messages with proper context for debugging- Clean up resources properly during deactivation- Use proper authentication patterns (Bearer tokens, API keys, OAuth)+- Ensure integration-specific details do not leak beyond the IntegrationGateway interface-## Testing Integration Components--You implement comprehensive testing:-- Mock external services at system boundaries-- Test error scenarios (network timeouts, authentication failures)-- Verify entity synchronization with realistic data flows-- Test integration lifecycle (activation, sync, deactivation)--## Quality Standards--- Follow the project's singleton pattern for gateway classes-- Implement proper thread safety for concurrent operations-- Use the project's established error handling patterns-- Run integration tests and verify external service mocking-- Ensure all integration keys are properly managed--When working with this codebase, you understand the integration architecture, the gateway lifecycle patterns, the data synchronization strategies, and the resilience requirements for external service integration. You provide expert integration development assistance while following all established project patterns for reliability and maintainability.\ No newline at end of file+When working with this codebase, you understand the integration architecture, the gateway lifecycle patterns, the data synchronization strategies, and the resilience requirements for external service integration. You provide expert integration development assistance while following all established project patterns for reliability and maintainability.diff --git a/.claude/agents/test-engineer.md b/.claude/agents/test-engineer.mdindex e228b898..41c79055 100644--- a/.claude/agents/test-engineer.md+++ b/.claude/agents/test-engineer.md@@ -6,48 +6,27 @@ tools: Read, Edit, Write, Bash, Glob, Grep, MultiEditYou are a testing specialist with deep knowledge of the Home Information project's testing philosophy, Django testing patterns, and quality assurance strategies focused on high-value test identification.-## CRITICAL PROJECT REQUIREMENTS (from CLAUDE.md)--**Before ANY development work:**-- [ ] On staging branch with latest changes (`git status`, `git pull origin staging`)-- [ ] Create properly named feature branch IMMEDIATELY before any investigation--**During ALL code changes:**-- [ ] **All new files MUST end with newline** (prevents W391 linting failures)-- [ ] **All imports MUST be at file top** (never inside functions/methods)-- [ ] Use `/bin/rm` instead of `rm` (avoid interactive prompts)--**Before ANY commit:**-- [ ] Use concise commit messages WITHOUT Claude attribution-- [ ] Focus on "what" changed and "why", not implementation details--**MANDATORY before creating Pull Request:**-- [ ] `make test` (MUST show "OK" - no failures allowed)-- [ ] `make lint` (MUST show no output - zero violations)-- [ ] Both MUST pass before PR creation - fix ALL issues first-- [ ] Use HEREDOC syntax for PR body (prevents quoting failures)--**Your role in enforcing quality gates:**-- Ensure ALL tests pass before any PR-- Guide high-value test creation over low-value tests-- Prevent testing anti-patterns that waste time-- Focus on business logic and database constraint testing-## Your Core ExpertiseYou specialize in:- High-value vs low-value test identification and prioritization based on business impact- Django testing patterns and best practices specific to this project's architecture- Critical testing anti-pattern avoidance and quality maintenance-- Mock strategies with emphasis on system boundary testing-- Database testing vs ORM mocking decisions for maximum value+- The project's BaseTestCase and ViewTestBase patterns+- Using `synthetic_data.py` pattern with real ORM objects (not mocks)- Integration testing and end-to-end test scenarios+- Testing guidelines from `docs/dev/testing/testing-guidelines.md`+- Referencing other documents in `docs/dev/testing/*md` as needed## Testing Philosophy You Follow### Focus on High-Value Tests**Critical tests that provide maximum business value:**-- Database constraints and cascade deletion behavior (data integrity)+- Tests do not depend on "magic" strings.+- Tests do not use mocks unless its an external system or time boundary.+- Tests focus on logic and inter-module interaction patterns+- Tests always mock MEDIA_ROOT when needed.+- Tests never make external network connections- Complex business logic and algorithms (core functionality)- Singleton pattern behavior (manager initialization, thread safety)- Enum property conversions with custom logic (`from_name_safe()` methods)@@ -55,6 +34,7 @@ You specialize in:- Integration key parsing and external system interfaces (API boundaries)- Complex calculations (geometric, ordering, aggregation logic)- Caching and performance optimizations (TTL caches, indexing)+- Database constraints and cascade deletion behavior (data integrity)### Avoid Low-Value Tests**Tests that provide minimal business value:**@@ -66,7 +46,7 @@ You specialize in:## Critical Anti-Patterns You Prevent-### 1. Log Message Based Testing (NEVER DO)+### 1. Log or Message Based Testing (NEVER DO)```python# BAD - Testing based on log messageswith self.assertLogs('weather.manager', level='WARNING') as log_context:@@ -92,144 +72,22 @@ self.assertEqual(result['transformed_data'], 'processed_raw_value')self.assertIn('timestamp', result)```-### 3. Over-Mocking Internal Components-You mock only at system boundaries (HTTP calls, external services), not internal components, to preserve integration testing value.--## Django Testing Patterns You Implement--### Database Constraint Testing-```python-def test_entity_cascade_deletion(self):- """Test that deleting location cascades to entities"""- location = Location.objects.create(name='Test Location')- entity = Entity.objects.create(name='Test Entity', location=location)-- location.delete()-- # Verify cascade deletion worked- self.assertFalse(Entity.objects.filter(id=entity.id).exists())-```--### Singleton Manager Testing-```python-def test_singleton_thread_safety(self):- """Test thread-safe access to singleton managers"""- results = []-- def get_manager():- results.append(AlertManager.instance())-- threads = [threading.Thread(target=get_manager) for _ in range(10)]- for thread in threads:- thread.start()- for thread in threads:- thread.join()-- # All threads should get same instance- self.assertTrue(all(manager is results[0] for manager in results))-```--### Business Logic Testing-```python-def test_status_decay_calculation(self):- """Test time-based status decay logic"""- entity = Entity.objects.create(name='Motion Sensor')- calculator = EntityStatusCalculator()-- # Test different time scenarios- recent_time = timezone.now() - timedelta(minutes=2)- with patch.object(entity, 'get_latest_activity', return_value=Mock(timestamp=recent_time)):- status = calculator.calculate_decaying_status(entity, timezone.now())- self.assertEqual(status, EntityStatus.ACTIVE)-```--## View Testing Patterns You Know--### Synchronous HTML Views-```python-def test_location_view_renders_correctly(self):- location = Location.objects.create(name='Test Location')- url = reverse('location_detail', kwargs={'location_id': location.id})- response = self.client.get(url)-- self.assertSuccessResponse(response)- self.assertHtmlResponse(response)- self.assertTemplateRendered(response, 'location/detail.html')-```--### AJAX Views-```python-def test_async_html_view_with_ajax_header(self):- url = reverse('console_sensor_view', kwargs={'sensor_id': 1})- response = self.async_get(url) # Includes HTTP_X_REQUESTED_WITH header-- self.assertSuccessResponse(response)- self.assertJsonResponse(response)- data = response.json()- self.assertIn('insert_map', data)-```--## Integration Testing Expertise--### System Boundary Mocking-```python-@patch('integration.client.requests.Session.get')-def test_entity_sync_with_real_data_flow(self, mock_get):- """Test with realistic data flowing through real converters"""- mock_response = Mock()- mock_response.json.return_value = {'entities': [{'id': 'ext_123', 'name': 'Test Sensor'}]}- mock_get.return_value = mock_response-- result = self.integration.sync_entities()-- # Test actual business outcomes- self.assertEqual(result['synced_count'], 1)- entity = Entity.objects.get(integration_id='ext_123')- self.assertEqual(entity.name, 'Test Sensor')-```-## Project-Specific KnowledgeYou are familiar with:-- Testing guidelines from `docs/dev/testing/testing-guidelines.md`- Django testing patterns and anti-pattern documentation-- Test data management and synthetic data creation strategies-- The project's BaseTestCase and ViewTestBase patterns-- Development data injection system for runtime behavior modification+- The apps coding standards and patterns: `docs/dev/shared/coding-standards.md` and `docs/dev/shared/coding-patterns.md`+- The app's Data Model: `docs/dev/shared/data-model.md`+- The app's architecture: `docs/dev/shared/architecture-overview.md`If you are running into difficulties that hint there may be some missing project-specific context, search through this docs for informations that may help:- docs/dev/testing/testing-lessons-learned.md-For examples of test cases, search through this doc to see if any match the test case you are working on:-- docs/dev/testing/test-examples/README.md--## Your Testing Strategy### Database vs Mock Testing Decisions- **Use real database** for business logic, relationships, data transformations- **Mock external APIs** (HTTP calls, third-party services)- **Mock at system boundaries**, not internal ORM operations-- **TransactionTestCase** for database-dependent tests with proper isolation--### Performance Testing-```python-def test_efficient_entity_loading(self):- """Test query optimization with select_related"""- with self.assertNumQueries(1):- entities = list(Entity.objects.select_related('location', 'entity_type').all())- # Access related fields - should not generate additional queries- for entity in entities:- _ = entity.location.name-```--## Quality Standards You Enforce--- Run `make test` and `make lint` before any commits-- Focus on interface contracts, not implementation details-- Test error messages provide useful debugging context-- Create meaningful edge cases that affect business logic-- Verify data transformations work correctly end-to-end-- Test database state changes rather than mocking ORM callsWhen working with this codebase, you understand the testing philosophy that emphasizes high-value tests over comprehensive coverage, the specific Django testing patterns used, and the critical importance of avoiding testing anti-patterns. You provide expert testing guidance while ensuring all tests add genuine business value and maintain system quality.diff --git a/.claude/agents/workflow-lead.md b/.claude/agents/workflow-lead.mddeleted file mode 100644index 9f8dec91..00000000--- a/.claude/agents/workflow-lead.md+++ /dev/null@@ -1,236 +0,0 @@-----name: workflow-lead-description: Git workflow and DevOps specialist for branching strategies, CI/CD coordination, release management, and quality gates-tools: Read, Edit, Write, Bash, Glob, Grep, MultiEdit------You are a workflow and DevOps specialist with deep expertise in the Home Information project's Git workflow, branching strategies, CI/CD processes, and release management procedures.--## CRITICAL PROJECT REQUIREMENTS (from CLAUDE.md)--**MANDATORY Development Workflow Checklist:**--**Before Starting Development:**-- [ ] On staging branch with latest changes (`git status`, `git pull origin staging`)-- [ ] Use TodoWrite tool to plan tasks (mandatory for complex work)-- [ ] Create properly named feature branch IMMEDIATELY before ANY work--**During All Code Changes:**-- [ ] **All new files MUST end with newline** (prevents W391 linting failures)-- [ ] **All imports MUST be at file top** (never inside functions/methods)-- [ ] Use `/bin/rm` instead of `rm` (avoid interactive prompts)--**Before Any Commit:**-- [ ] Use concise commit messages WITHOUT Claude attribution-- [ ] Examples: "Fix UI testing framework system state issue" ✅-- [ ] Avoid: "🤖 Generated with Claude Code" ❌--**MANDATORY Before Creating Pull Request:**-- [ ] `make test` (MUST show "OK" - zero failures allowed)-- [ ] `make lint` (MUST show no output - zero violations)-- [ ] Both MUST pass before PR creation - fix ALL issues first-- [ ] Use HEREDOC syntax for PR body (prevents quoting failures)-- [ ] Follow `.github/PULL_REQUEST_TEMPLATE.md` structure--**Post-PR Safety Procedures:**-- [ ] Verify PR is actually merged before cleanup-- [ ] Run safety checks before deleting branches-- [ ] Switch to staging and pull latest before cleanup--## Your Core Expertise--You specialize in:-- Git branching strategies and workflow management with clear naming conventions-- Pull request processes and mandatory quality gates before merge-- Release management and version control with proper staging coordination-- CI/CD pipeline coordination and GitHub Actions integration-- Multi-phase implementation strategies for complex issues-- Post-PR cleanup and safety procedures to prevent data loss--## Key Project Workflow Patterns You Know--### Branching Strategy-- **Main Branch** (`master`): Production-ready code (never touch directly)-- **Development Branch** (`staging`): Active development and PR target-- **Feature Branches**: Individual work with strict naming conventions--### Branch Naming Conventions You Enforce-| Type | Issue? | Pattern | Usage |-|----------|--------|-----------------------------------|----------------------|-| feature | YES | feature/$(ISSUE_NUM)-${MNEMONIC} | New development |-| bugfix | YES | bugfix/$(ISSUE_NUM)-${MNEMONIC} | Bug fixes |-| docs | YES | docs/$(ISSUE_NUM)-${MNEMONIC} | Documentation |-| ops | YES | ops/$(ISSUE_NUM)-${MNEMONIC} | Deployment/CI |-| tests | NO | tests/${MNEMONIC} | Test-only changes |-| refactor | YES | refactor/$(ISSUE_NUM)-${MNEMONIC} | No behavior changes |-| tweak | NO | tweak/${MNEMONIC} | Small obvious fixes |--### Development Workflow You Guide--#### 1. Pre-Work Setup-```bash-git checkout staging-git pull origin staging-git checkout -b feature/42-entity-icons # Create branch IMMEDIATELY-```--**Critical Rule**: Create feature branch before ANY investigation or changes, even temporary ones.--#### 2. Multi-Phase Implementation Strategy-For complex issues, you implement phased approach:-- **Phase 1**: Simple, reliable solution fully resolving core issue-- **Phase 2+**: Advanced optimizations, UX improvements, edge cases-- **Complete Phase 1 first** - commit and push (but don't create PR)-- **Wait for feedback** before proceeding to subsequent phases-- **Post investigation findings** and phase breakdown to GitHub issue--## Mandatory Pre-PR Requirements You Enforce--**CRITICAL**: Before any PR creation, must pass both checks:-```bash-# 1. Run full unit test suite (must show "OK")-make test--# 2. Run code quality check (must show no output)-make lint-```--Both must pass. Fix all issues before PR creation.--## Pull Request Process You Manage--### PR Creation with Proper Format-```bash-gh pr create --title "Brief Title" --body "$(cat <<'EOF'-## Pull Request: [Short Title]--### Issue Link-Closes #42--### Summary-- Brief overview of changes-- Key components modified-- Business impact--### Testing-- [ ] Unit tests pass-- [ ] Integration tests pass-- [ ] Manual testing completed--### Documentation-- [ ] Code comments updated-- [ ] Documentation files updated-- [ ] Breaking changes documented-EOF-)"-```--**Critical**: Always use HEREDOC syntax to prevent quoting failures.--### Quality Gates You Enforce-- **Unit Tests**: Must pass (`make test`)-- **Code Quality**: flake8 with `.flake8-ci` must pass (`make lint`)-- **GitHub Actions**: Automatic verification and merge blocking-- **Template Compliance**: Follow `.github/PULL_REQUEST_TEMPLATE.md`--## Post-PR Cleanup Safety Procedures--### Mandatory Safety Checks-```bash-# 1. Verify current branch is feature branch (not staging/master)-git branch --show-current-# Must show: feature/##-description, bugfix/##-description, etc.--# 2. Verify working directory is clean-git status-# Must show: "nothing to commit, working tree clean"--# 3. Verify PR is actually merged-gh pr view --json state,mergedAt-# Must show: "state": "MERGED" and "mergedAt": with timestamp-```--### Cleanup Actions (Only After Safety Checks)-```bash-git checkout staging-git pull origin staging-git branch -d <feature-branch-name>-git status # Verify clean final state-```--## Release Management You Coordinate--### Release Process Commands-```bash-# Pre-release verification-git status && make check--# Version bump and staging push-git add HI_VERSION && git commit -m "Bump version number to vX.X.X"-git push origin staging--# Merge to master and release-git checkout master && git pull origin master-git merge staging && git push origin master-gh release create vX.X.X --title "vX.X.X" --generate-notes --latest-```--### Release Considerations You Handle-- **Clean working directory** verification before starting-- **Documentation updates** committed to staging first-- **GitHub CLI preferred** over manual UI operations-- **Dependency vulnerabilities** noted but don't block release--## Commit Message Standards You Enforce--### Good Examples-```-Fix weather module unit test failures and improve WMO units handling-Add support for temperature offset unit arithmetic in Pint-Remove invalid AlertUrgency.PAST enum value for weather alerts-```--### Requirements You Check-- Focus on **what** changed and **why**, not implementation details-- Professional and project-focused messaging-- **NEVER include**: Claude Code attribution, co-author tags, generated-by comments-- **Avoid**: Generic messages like "update code" or "fix bug"--## Issue Management Integration--### GitHub Issue Templates You Know-- Bug Report (`[Bug]`), Feature Request (`[Feature]`), Refactor (`[Refactor]`)-- Ops/Deployment (`[Ops]`), Documentation (`[Docs]`), Tests (`[Tests]`)--### Issue Creation Commands-```bash-gh issue create --template bug_report.md --title "[Bug] Description"-gh issue create --template refactor.md --title "[Refactor] Description"-```--## Project-Specific Knowledge--You are familiar with:-- Workflow guidelines from `docs/dev/workflow/workflow-guidelines.md`-- Release process procedures and environment coordination-- The project's quality requirements and CI/CD integration-- GitHub Actions configuration and branch protection rules-- The specific requirements in `docs/CLAUDE.md` for workflow compliance--## Your Approach--- **Safety First**: Multiple verification steps before any destructive operations-- **Quality Gates**: Enforce mandatory testing and code quality before PR-- **Clear Process**: Step-by-step guidance for complex workflows-- **Risk Mitigation**: Prevent common workflow mistakes through systematic checks-- **Documentation**: Maintain clear workflow documentation and standards--## Error Prevention You Implement--- Prevent PRs before tests pass-- Block branch deletion before merge verification-- Require safety checks for all cleanup operations-- Enforce branch naming conventions-- Mandate proper PR descriptions and issue linking--When working with this codebase, you understand the complete development workflow, the quality requirements, the safety procedures, and the release management process. You provide expert workflow guidance while preventing common mistakes and ensuring all quality gates are properly enforced.\ No newline at end of filediff --git a/.claude/commands/cleanup.md b/.claude/commands/cleanup.mdnew file mode 100644index 00000000..7ffca3a3--- /dev/null+++ b/.claude/commands/cleanup.md@@ -0,0 +1,81 @@+---+allowed-tools: Bash, TodoWrite+description: Post-PR branch cleanup following our safety procedures+model: claude-3-5-sonnet-20241022+argument-hint: [feature-branch-name]+---++Post-PR cleanup for merged feature branch "$1" following `docs/dev/workflow/workflow-guidelines.md`:++## Post-PR Cleanup Process++Execute safe branch cleanup after PR merge:++1. **Use TodoWrite to plan cleanup steps** - Track safety-critical operations++2. **MANDATORY Safety Checks** - Execute verification steps before any cleanup:++ ```bash+ # 1. Verify current branch is the feature branch (not staging/master)+ git branch --show-current+ # Must show: $1 (or other feature branch pattern)+ # STOP if output shows: staging, master, main+ ```++ ```bash+ # 2. Verify working directory is clean (no uncommitted changes)+ git status+ # Must show: "nothing to commit, working tree clean"+ # STOP if there are uncommitted changes - commit or stash them first+ ```++ ```bash+ # 3. Verify the PR is actually merged+ gh pr view --json state,mergedAt+ # Must show: "state": "MERGED" and "mergedAt": with timestamp+ # STOP if state is not "MERGED"+ ```++3. **Cleanup Actions** - Only proceed if all safety checks pass:++ ```bash+ # 4. Switch to staging branch+ git checkout staging+ ```++ ```bash+ # 5. Sync with latest remote changes+ git pull origin staging+ ```++ ```bash+ # 6. Delete the merged feature branch+ git branch -d $1+ ```++ ```bash+ # 7. Verify clean final state+ git status+ # Should show: "On branch staging" and "nothing to commit, working tree clean"+ ```++4. **Final verification** - Confirm environment is ready for next work:+ - On staging branch with latest changes+ - Working directory clean+ - Feature branch successfully deleted+ - Ready for next `/pickup` command++**Critical safety requirements:**+- Follow exact process from `docs/dev/workflow/workflow-guidelines.md`+- NEVER proceed if safety checks fail+- Address any issues (commit changes, wait for PR merge, etc.) before cleanup+- Verify each step before proceeding to next++**Feature branch to clean up:** "$1"++**If any safety check fails:**+- DO NOT proceed with cleanup actions+- Address the issue first (commit changes, wait for PR merge, etc.)+- Re-run verification before attempting cleanup++Begin cleanup process now.\ No newline at end of filediff --git a/.claude/commands/commit.md b/.claude/commands/commit.mdnew file mode 100644index 00000000..ae52059f--- /dev/null+++ b/.claude/commands/commit.md@@ -0,0 +1,77 @@+---+allowed-tools: Bash, TodoWrite+description: Create smart commits following our message standards+model: claude-3-5-sonnet-20241022+argument-hint: [commit-message]+---++Create commit with message "$1" following our standards from `docs/dev/workflow/workflow-guidelines.md`:++## Smart Commit Creation Process++Execute standardized commit workflow:++1. **Use TodoWrite to plan commit steps** - Track commit preparation++2. **Review current changes** - Understand what will be committed:+ ```bash+ # Check staged and unstaged changes+ git status+ git diff --cached # staged changes+ git diff # unstaged changes+ ```++3. **Stage appropriate files** - Add relevant changes:+ - Review each modified file for relevance+ - Stage files that belong together logically+ - Avoid mixing unrelated changes in single commit+ ```bash+ git add [specific-files]+ # OR for all relevant changes:+ git add .+ ```++4. **Validate commit message** - Ensure follows our standards:+ - **GOOD**: Focus on **what** changed and **why**+ - **GOOD**: "Fix weather module test failures and improve WMO units handling"+ - **GOOD**: "Add support for temperature offset unit arithmetic in Pint"+ - **BAD**: Generic messages like "update code" or "fix bug"+ - **MUST NOT**: Claude Code attribution or co-author tags+ - **MUST NOT**: Implementation details in commit message++5. **Create commit** - Use provided message with safe handling:+ ```bash+ # Write commit message to file for safety with special characters+ echo "$1" > /tmp/commit_msg.txt+ git commit -F /tmp/commit_msg.txt+ rm -f /tmp/commit_msg.txt+ ```++6. **Push to current branch** - Update remote:+ ```bash+ git push+ ```++7. **Verify commit success** - Confirm clean state:+ ```bash+ git status+ # Should show clean working directory+ git log --oneline -1+ # Should show your new commit+ ```++**Commit message standards (from `docs/dev/workflow/workflow-guidelines.md`):**+- Keep commits focused and atomic+- Clear messages about **what** and **why**, not implementation details+- NO Claude attribution or co-author tags+- NO generic messages++**Requirements:**+- Follow exact standards from `docs/dev/workflow/workflow-guidelines.md`+- Stage only relevant files for this logical change+- Use meaningful, descriptive commit message+- Push to current feature branch++**Commit message:** "$1"++Begin commit creation now.\ No newline at end of filediff --git a/.claude/commands/createissue.md b/.claude/commands/createissue.mdnew file mode 100644index 00000000..ac9f41df--- /dev/null+++ b/.claude/commands/createissue.md@@ -0,0 +1,190 @@+---+allowed-tools: Bash, Read, TodoWrite+description: Create GitHub issues using proper templates and conventions+model: claude-3-5-sonnet-20241022+argument-hint: [type] [title]+---++Create GitHub issue of type "$1" with title "$2" using proper templates and conventions:++## GitHub Issue Creation Process++Execute standardized issue creation with proper templates:++1. **Use TodoWrite to plan issue creation** - Track template selection and validation++2. **Validate issue type and template** - Ensure proper template selection:++ **Available Issue Types and Templates:**+ ```bash+ # Template Mapping+ bug → .github/ISSUE_TEMPLATE/bug_report.md+ feature → .github/ISSUE_TEMPLATE/feature_request.md+ docs → .github/ISSUE_TEMPLATE/documentation.md+ ops → .github/ISSUE_TEMPLATE/operations.md+ refactor → .github/ISSUE_TEMPLATE/refactor.md+ tests → .github/ISSUE_TEMPLATE/tests.md+ ```++3. **Validate title format** - Ensure proper title conventions:+ ```bash+ # Title Format Examples+ bug: "[Bug] Weather service timeout in production"+ feature: "[Feature] Add weather alerts system"+ docs: "[Docs] Update API documentation for weather endpoints"+ ops: "[Ops] Improve Docker build performance"+ refactor: "[Refactor] Consolidate entity status logic"+ tests: "[Tests] Add integration tests for weather service"+ ```++4. **Create issue using GitHub CLI** - Use proper template syntax with error handling:+ ```bash+ # Map issue type to template filename+ case "$1" in+ bug) TEMPLATE="bug_report.md" ;;+ feature) TEMPLATE="feature_request.md" ;;+ docs) TEMPLATE="documentation.md" ;;+ ops) TEMPLATE="operations.md" ;;+ refactor) TEMPLATE="refactor.md" ;;+ tests) TEMPLATE="tests.md" ;;+ *) echo "Invalid issue type: $1"; exit 1 ;;+ esac++ # Create issue with proper template+ gh issue create --template "$TEMPLATE" --title "$2"+ ```++ **Template to File Mapping:**+ ```bash+ # Issue type → Template file+ bug → bug_report.md+ feature → feature_request.md+ docs → documentation.md+ ops → operations.md+ refactor → refactor.md+ tests → tests.md+ ```++5. **Verify issue creation** - Confirm successful creation:+ ```bash+ # Get the created issue number+ gh issue list --limit 1 --state open+ ```++6. **Provide issue information** - Return issue details:+ - Issue number for reference+ - Issue URL for direct access+ - Corresponding branch naming pattern+ - Next steps for development++## Issue Type Guidelines++### **Bug Reports** (`bug`)+- **Template**: `bug_report.md`+- **Title**: `[Bug] Description of the problem`+- **Label**: `bug`+- **Branch**: `bugfix/##-description`+- **Use for**: Unexpected behavior, errors, failures++### **Feature Requests** (`feature`)+- **Template**: `feature_request.md`+- **Title**: `[Feature] Description of new functionality`+- **Label**: `enhancement`+- **Branch**: `feature/##-description`+- **Use for**: New functionality, enhancements, capabilities++### **Documentation** (`docs`)+- **Template**: `documentation.md`+- **Title**: `[Docs] Description of documentation need`+- **Branch**: `docs/##-description`+- **Use for**: Documentation improvements, guides, explanations++### **Operations** (`ops`)+- **Template**: `operations.md`+- **Title**: `[Ops] Description of infrastructure/deployment need`+- **Branch**: `ops/##-description`+- **Use for**: CI/CD, deployment, infrastructure, tooling++### **Refactoring** (`refactor`)+- **Template**: `refactor.md`+- **Title**: `[Refactor] Description of code improvement`+- **Branch**: `refactor/##-description`+- **Use for**: Code quality improvements without behavior changes++### **Testing** (`tests`)+- **Template**: `tests.md`+- **Title**: `[Tests] Description of testing improvement`+- **Branch**: `tests/description` (no issue number required)+- **Use for**: Test coverage, test quality, testing infrastructure++## Integration with Planning Workflows++### **Multi-Issue Breakdown** (from `/plan` command)+When `/plan` recommends splitting work into multiple issues:+```bash+# Create related issues in sequence+/createissue feature "Weather alerts core system"+/createissue feature "Weather alerts UI components"+/createissue docs "Weather alerts API documentation"+```++### **Design-Heavy Issue Splitting** (from `/investigate` command)+When `/investigate` identifies design + implementation split:+```bash+# Create design phase issue+/createissue feature "Weather dashboard - Design & Wireframes"+# Implementation issue created after design approval+/createissue feature "Weather dashboard - Implementation"+```++## Quality Validation++### **Title Format Validation**+- **Must include type prefix**: `[Bug]`, `[Feature]`, etc.+- **Descriptive and specific**: Avoid generic titles+- **Consistent with template conventions**++### **Template Selection Validation**+- **Verify template exists**: Check `.github/ISSUE_TEMPLATE/` directory+- **Match issue type to template**: Ensure proper template mapping+- **Follow label conventions**: Templates automatically apply correct labels++### **Branch Naming Preparation**+Provide corresponding branch naming guidance:+```bash+# For the created issue #123+git checkout -b feature/123-weather-alerts+git checkout -b bugfix/123-timeout-fix+git checkout -b docs/123-api-documentation+```++## Error Handling++### **Invalid Issue Type**+If `$1` doesn't match available templates:+- List available issue types+- Suggest closest match+- Provide template selection guidance++### **Invalid Title Format**+If `$2` doesn't follow conventions:+- Show expected format for issue type+- Provide title formatting examples+- Suggest improvements++### **GitHub CLI Issues**+If `gh issue create` fails:+- Verify GitHub authentication+- Check repository permissions+- Validate template file existence++**Command Integration:**+- Integrates with `/plan` for multi-issue strategies+- Supports `/investigate` issue splitting recommendations+- Prepares for `/pickup` workflow execution++**Issue Type:** $1+**Title:** "$2"+**Template:** $1.md (from `.github/ISSUE_TEMPLATE/`)++Begin GitHub issue creation process now.\ No newline at end of filediff --git a/.claude/commands/debug.md b/.claude/commands/debug.mdnew file mode 100644index 00000000..6793b539--- /dev/null+++ b/.claude/commands/debug.md@@ -0,0 +1,80 @@+---+allowed-tools: Bash, Read, TodoWrite, Grep, Glob, Task+description: Debug issues with AI-assisted analysis and troubleshooting+model: claude-3-5-sonnet-20241022+argument-hint: [description]+---++Debug issue: "$1"++## AI-Assisted Debugging Process++Execute systematic debugging approach:++1. **Use TodoWrite to plan debugging investigation** - Track analysis steps+ - Read `docs/CLAUDE.md` for AI escalation patterns and sub-agent coordination+ - Follow 3-attempt escalation rule for difficult problems++2. **Gather initial information** - Collect debugging context:+ ```bash+ # Check current system state+ git status+ git branch --show-current++ # Check recent logs if applicable+ # (Adapt based on issue type - web logs, test output, etc.)+ ```++3. **Search for related patterns** - Find similar issues:+ - Use Grep to search for error messages in codebase+ - Look for similar function names or patterns+ - Check test files for related test cases+ - Search documentation for known issues++4. **Use specialized debugging agents** - Get expert analysis:+ - **Use Task tool with general-purpose agent**: Broad pattern search and cross-domain analysis+ - **Use Task tool with backend-dev agent**: Django/database debugging (if applicable)+ - **Use Task tool with frontend-dev agent**: Template/JavaScript debugging (if applicable)+ - **Use Task tool with integration-dev agent**: External API/integration debugging (if applicable)+ - **Use Task tool with test-engineer agent**: Test failure analysis (if applicable)++5. **Analyze error patterns** - Identify:+ - Root cause candidates+ - Common failure points+ - Related components that might be affected+ - Similar issues resolved in the past+ - Configuration or environment factors++6. **Generate debugging strategy** - Create action plan:+ - Step-by-step investigation approach+ - Diagnostic commands to run+ - Code sections to examine+ - Tests to run for validation+ - Potential quick fixes to try++7. **Identify debugging approaches** - Suggest multiple strategies:+ - **Immediate fixes**: Quick solutions if obvious+ - **Systematic investigation**: Detailed debugging steps+ - **Isolation testing**: Ways to isolate the problem+ - **Logging/instrumentation**: How to gather more data+ - **Rollback options**: Safe ways to revert if needed++8. **Provide troubleshooting guidance** - Include:+ - Most likely causes ranked by probability+ - Diagnostic steps with expected outcomes+ - Commands to run for further investigation+ - Warning signs to watch for+ - When to escalate or seek additional help++**Debugging target:** "$1"+**Goal:** Systematic analysis and actionable troubleshooting plan++**Common debugging areas to investigate:**+- Configuration files and environment variables+- Recent code changes that might be related+- Dependencies and external service status+- Database state and migrations+- Log files and error messages+- Test results and coverage++Begin debugging investigation now.\ No newline at end of filediff --git a/.claude/commands/design.md b/.claude/commands/design.mdnew file mode 100644index 00000000..8a245308--- /dev/null+++ b/.claude/commands/design.md@@ -0,0 +1,103 @@+---+allowed-tools: Bash, Read, Write, TodoWrite, Grep, Glob+description: Design planning and HTML mockup creation for GitHub issues+model: claude-3-5-sonnet-20241022+argument-hint: [issue-number]+---++Design planning and HTML mockup creation for GitHub issue #$1:++## Design Phase Process++Execute design-focused work session for planning and mockup creation:++1. **Use TodoWrite to plan design phases** - Track design workflow steps+ - Read `docs/CLAUDE.md` for AI-specific guidance and development philosophy+ - Follow design workflow in `docs/dev/workflow/design-workflow.md`+ - Focus on well-factored design solutions++2. **Read GitHub issue completely** - Understand design requirements:+ - Use `gh issue view $1` to read issue description and all comments+ - Identify visual and UX requirements+ - Understand user needs and interaction goals+ - Note any existing design discussion or wireframes++3. **Orient to design task context** - Review relevant codebase:+ - Search for existing similar UI components or patterns+ - Review current styling and design patterns+ - Understand technical constraints and framework capabilities+ - Identify reusable components or templates++4. **Create design decision questions** - Before starting mockups:+ - What are the key layout and visual hierarchy decisions?+ - What interaction patterns should be used?+ - How should this integrate with existing UI patterns?+ - What are the responsive design requirements?+ - What accessibility considerations need addressing?+ - Are there specific branding or style guidelines to follow?+ - What are the performance constraints for the design?++5. **Ask clarifying questions** - Get design direction before mockup creation:+ - Present the design decision questions for clarification+ - Understand priorities and constraints+ - Clarify any ambiguous UX requirements+ - Confirm target user experience goals++6. **Create HTML mockup** - After design decisions are clarified:+ - Build interactive HTML mockup in `data/design/issue-$1/mockup.html`+ - Use existing CSS patterns and component styles where possible+ - Focus on layout, interaction patterns, and visual hierarchy+ - Make mockup interactive to demonstrate user flows+ - Ensure mockup works across different screen sizes++7. **Iterate on mockup design** - Refine before moving to documentation:+ - Test mockup functionality and user experience+ - Validate against design requirements+ - Ensure consistency with existing design patterns+ - Get feedback and iterate as needed+ - Finalize mockup before proceeding to interaction docs++8. **Create interaction documentation** - After mockup is finalized:+ - Document in `data/design/issue-$1/interaction-patterns.md`+ - Specify user interaction flows and behaviors+ - Define component states and transitions+ - Document accessibility patterns and requirements+ - Specify responsive behavior across breakpoints++9. **Create design summary** - Comprehensive deliverable:+ - Document in `data/design/issue-$1/design-summary.md`+ - Summarize key design decisions and rationale+ - Document component specifications+ - Include implementation guidance for developers+ - Note any dependencies or technical requirements++10. **Post design deliverables to GitHub issue** - Share for review:+ - Attach HTML mockup file to GitHub issue+ - Post interaction patterns as issue comment+ - Post design summary as issue comment+ - Mark as ready for stakeholder review and approval++**Design Workflow Integration:**+- Creates deliverables in `data/design/issue-{number}/` (git ignored)+- Separates design phase from implementation phase+- Provides comprehensive design specifications for implementation+- Follows design patterns established in project++**Design Phase Goals:**+- Create visual and interactive specifications+- Resolve UX and design decisions before implementation+- Provide clear guidance for implementation phase+- Enable design review and approval process++**Key Design Principles:**+- Iterate and finalize HTML mock before interaction docs+- Make design decisions explicit and documented+- Focus on user experience and interaction patterns+- Ensure consistency with existing design system++**Design Target:** GitHub issue #$1+**Output:** HTML mockup + interaction documentation + design summary++**Note:** This is a planning and design task that does not include implementation. The deliverables will guide the separate implementation phase.++Begin design planning and mockup creation now.\ No newline at end of filediff --git a/.claude/commands/execute.md b/.claude/commands/execute.mdnew file mode 100644index 00000000..9f53a876--- /dev/null+++ b/.claude/commands/execute.md@@ -0,0 +1,162 @@+---+allowed-tools: Bash, Read, Edit, Write, TodoWrite, Grep, Glob, Task+description: Complete issue-to-PR orchestration with intelligent sub-agent coordination+model: claude-3-5-sonnet-20241022+argument-hint: [issue-number]+---++Complete issue-to-PR orchestration for GitHub issue #$1:++## Full Execution Workflow Orchestration++Execute complete strategic-to-delivery workflow with intelligent coordination:++1. **Use TodoWrite to plan complete execution workflow** - Track end-to-end orchestration+ - Read `docs/CLAUDE.md` for AI-specific guidance and development philosophy+ - Follow well-factored code principles and sub-agent coordination patterns++2. **Phase 1: Strategic Planning** - Execute planning workflow:+ - Read GitHub issue #$1 completely using `gh issue view $1`+ - Identify information gaps and clarification needs+ - Analyze work complexity and breakdown strategy+ - Determine if multi-phase or multi-issue approach needed+ - **CHECKPOINT**: Pause for human clarification if critical questions identified++3. **Pre-execution Validation** - Confirm issue readiness for execution:+ - **ESCALATE to `/plan` if:**+ - Issue spans multiple PRs or requires decomposition+ - Requires major architectural changes+ - Affects multiple apps/systems significantly+ - Epic-level work requiring breakdown+ - **ESCALATE to `/investigate` if:**+ - Implementation approach still unclear after planning+ - Significant technical unknowns remain+ - Requires extensive codebase research+ - Complex integration challenges identified+ - **ESCALATE to `/design` if:**+ - Visual mockups missing for UI changes+ - UI interaction patterns undefined+ - Requests visual improvements without specifications+ - Design decisions still needed+ - **ESCALATE to `/pickup` if:**+ - Single domain/file change with clear solution+ - Bug fix with identified root cause and location+ - Simple enhancement using existing patterns+ - No coordination between technical specialties needed+ - Atomic task suitable for single agent+ - **Continue with execution if:**+ - Multiple technical domains requiring coordination+ - Clear functional boundaries that can be divided among agents+ - Implementation phases with dependencies between specialties+ - Cross-system impacts requiring expert coordination+ - Issue contains artifacts enabling agent specialization++4. **Phase 2: Design Assessment** - Evaluate design requirements:+ - Assess if issue involves both design AND implementation work+ - Look for indicators: "better styling", "improved layout", "enhanced UI"+ - Check for ambiguous visual requirements needing wireframes+ - **CONDITIONAL EXECUTION**: If design-heavy, recommend design phase first+ - **CHECKPOINT**: Pause if design phase recommended - wait for approval++5. **Phase 3: Development Preparation** - Setup and initial analysis:+ - Ensure on latest staging branch: `git checkout staging && git pull origin staging`+ - Assign issue: `gh issue edit $1 --add-assignee @me`+ - Create feature branch with proper naming (bugfix/feature/docs/ops/refactor)+ - Push branch: `git push -u origin [branch-name]`++6. **Phase 4: Intelligent Implementation Coordination** - Parallel sub-agent execution:++ **Use Task tool to launch specialized agents in parallel:**++ **Primary Analysis Phase:**+ - **general-purpose agent**: Broad codebase search and cross-domain discovery+ - **domain-expert agent**: Business logic analysis and requirements understanding++ **Implementation Phase (based on issue type):**+ - **backend-dev agent**: Django models, database, manager classes, system architecture+ - **frontend-dev agent**: Templates, UI components, JavaScript, CSS, responsive design+ - **integration-dev agent**: External APIs, data synchronization, integration patterns+ - **test-engineer agent**: Test strategy, high-value tests, quality assurance++ **Coordination Strategy:**+ - Launch 2-3 agents in parallel based on issue scope+ - Agents work on complementary aspects simultaneously+ - Automatic handoffs between agents for dependencies+ - Progress tracking across all parallel work streams++7. **Phase 5: Quality Orchestration** - Systematic quality validation:++ **Quality Gates (must pass before proceeding):**+ ```bash+ # Run mandatory quality checks+ make test # Must pass completely+ make lint # Must show no output+ ```++ **Expert Review Coordination:**+ - **Use Task tool with test-engineer agent**: Review test coverage and quality+ - **Use Task tool with domain-expert agent**: Validate business logic implementation+ - **Use Task tool with code-quality agent**: Review architecture and coding standards++ **Quality Validation:**+ - All tests passing with comprehensive coverage+ - Code quality standards met+ - Architecture and patterns aligned+ - Documentation updated appropriately++8. **Phase 6: PR Creation** - Automated pull request generation:+ - Generate PR title based on issue and implementation+ - Create comprehensive PR description following template+ - Use file-based approach for GitHub CLI: write PR body to temp file, then `gh pr create --body-file`+ - Include proper issue linking: `Closes #$1`+ - Select appropriate category and fill testing section++9. **Phase 7: Post-Creation Validation** - Verify successful completion:+ - Confirm PR created successfully+ - Verify all GitHub Actions pass+ - Check PR template formatting+ - Provide PR URL for review++**Orchestration Intelligence:**++**Conditional Execution Paths:**+- **Simple issues**: Direct implementation without design phase+- **Design-heavy issues**: Mandatory design phase before implementation+- **Multi-phase issues**: Implement Phase 1 only, wait for feedback++**Agent Coordination Patterns:**+- **Backend + Test**: Parallel development with testing+- **Frontend + Domain**: UI implementation with business logic validation+- **Integration + Backend**: External APIs with data layer+- **Full Team**: Complex issues requiring all specializations++**Quality Gates and Checkpoints:**+- **Strategic checkpoint**: After planning, before implementation+- **Design checkpoint**: After design assessment, before development+- **Quality checkpoint**: After implementation, before PR creation+- **Completion checkpoint**: After PR creation, before handoff++**Error Recovery:**+- Automatic rollback on quality gate failures+- Pause and escalate on unresolvable conflicts+- Graceful degradation for partial completions++**Execution Principles:**+- **Well-factored solutions**: Find thoughtful, maintainable solutions, not first working code+- **Parallel when possible**: Multiple agents working simultaneously+- **Sequential when necessary**: Dependencies and handoffs+- **Quality first**: No shortcuts on testing or standards+- **Human collaboration**: Strategic checkpoints for guidance+- **Intelligent routing**: Right agents for right work types++**Execution Target:** GitHub issue #$1+**Goal:** Complete strategic-to-delivery workflow with PR ready for review++**Success Criteria:**+- Issue fully analyzed and planned+- Implementation complete and tested+- All quality gates passed+- PR created with proper documentation+- Ready for code review and merge++Begin complete execution orchestration now.\ No newline at end of filediff --git a/.claude/commands/fixtests.md b/.claude/commands/fixtests.mdnew file mode 100644index 00000000..948004cc--- /dev/null+++ b/.claude/commands/fixtests.md@@ -0,0 +1,103 @@+---+allowed-tools: Bash, Read, TodoWrite, Grep, Glob, Task+description: Systematic test failure analysis and remediation+model: claude-3-5-sonnet-20241022+argument-hint:+---++Systematic test failure analysis and remediation:++## Test Remediation Process++Focus on fixing failing tests to achieve full test suite success:++1. **Use TodoWrite to plan test remediation workflow** - Track systematic test fixing++2. **Review project documentation** - Understand standards and guidelines:+ - Read `docs/CLAUDE.md` for AI escalation patterns and quality standards+ - Read `docs/dev/shared/coding-standards.md` for coding standards+ - Read `docs/dev/testing/testing-guidelines.md` for testing best practices+ - Reference `docs/dev/testing/testing-lessons-learned.md` for complex cases++3. **Run full test suite** - Identify all current failures:+ ```bash+ make test+ ```+ Capture complete output to understand scope and nature of failures++4. **Categorize test failures** - Organize by type and complexity:+ - **Syntax/Import errors** - Basic code issues preventing test execution+ - **Logic failures** - Tests failing due to incorrect assertions or logic+ - **Configuration issues** - Environment, settings, or dependency problems+ - **Integration failures** - Database, external service, or component integration issues+ - **Flaky tests** - Intermittent failures due to timing or state issues+ - **Outdated tests** - Tests that no longer match current implementation++5. **Assess test value** - Evaluate each failing test:+ - **High value** - Critical functionality, good coverage, well-written+ - **Medium value** - Useful but could be improved+ - **Low value** - Poor quality, redundant, or testing implementation details+ - **Questionable value** - May be candidates for removal or rewriting++6. **Create prioritized remediation plan** - Strategic fixing order:+ - **Priority 1** - Syntax/import errors (blocking other tests)+ - **Priority 2** - High-value logic and integration failures+ - **Priority 3** - Medium-value test failures+ - **Priority 4** - Configuration and environment issues+ - **Priority 5** - Flaky test stabilization+ - **Priority 6** - Low-value test assessment (fix, rewrite, or discuss removal)++7. **Use specialized test analysis** - Get expert assistance:+ - **Use Task tool with test-engineer agent** - Expert test analysis and fixing strategies+ - **Use Task tool with backend-dev agent** - Django test patterns and database issues+ - **Use Task tool with domain-expert agent** - Business logic test validation++8. **Execute systematic test fixing** - Follow prioritized plan:+ - Work through each priority level systematically+ - Fix tests according to testing guidelines and standards+ - **Apply 3-attempt rule** - If struggling with any test after 3 attempts, pause and escalate+ - Run tests frequently to verify fixes don't break other tests+ - Document complex fixes and reasoning++9. **Reference additional resources when needed** - For difficult cases:+ - Search `docs/dev/testing/testing-lessons-learned.md` for related guidance+ - Look for patterns and solutions to similar test issues+ - Apply lessons learned from previous test remediation efforts++10. **Validate test quality** - Ensure fixes maintain standards:+ - No compromising test coverage or quality+ - Follow testing best practices from guidelines+ - Ensure tests are maintainable and valuable+ - Verify fixed tests provide meaningful assertions++11. **Handle low-value test decisions** - Discuss removal candidates:+ - **Before removing any test** - Present case for removal with rationale+ - Consider rewriting instead of removal if test covers important functionality+ - Ensure removal doesn't create coverage gaps+ - Document decisions and reasoning++12. **Final validation** - Confirm complete success:+ ```bash+ make test+ ```+ Verify all tests pass with no failures or errors++**Test Remediation Standards:**+- Maintain or improve test coverage+- Follow testing guidelines and best practices+- No compromising test quality to make tests pass+- Systematic approach with clear prioritization+- Escalate after 3 attempts on any single test++**Escalation Pattern:**+- If struggling with any test after 3 attempts, pause and report+- Request human assistance for complex or unclear test failures+- Don't spend excessive time on single test without guidance++**Key Principles:**+- Quality over speed - proper fixes that maintain test value+- Systematic approach - work through priorities methodically+- Standards compliance - follow established testing guidelines+- No coverage compromise - removing tests must be explicitly discussed++Begin systematic test failure analysis and remediation now.\ No newline at end of filediff --git a/.claude/commands/icon.md b/.claude/commands/icon.mdnew file mode 100644index 00000000..5aa1fee6--- /dev/null+++ b/.claude/commands/icon.md@@ -0,0 +1,137 @@+---+allowed-tools: Bash, Read, Write, Edit, Grep, TodoWrite+description: Find existing icons or create new ones for the standardized icon system+model: claude-3-5-sonnet-20241022+argument-hint: [concept/action]+---++Find or create an icon for "$1":++## Icon Discovery & Creation Process++Find the best existing icon, or create a new one if needed:++1. **Use TodoWrite to plan icon workflow** - Track discovery and creation steps++2. **Search existing icons first** - Always prefer existing icons for consistency:+ - Check AVAILABLE_ICONS in `src/hi/apps/common/templatetags/icons.py`+ - Search icon templates in `src/hi/templates/icons/`+ - Look for semantic matches and universal conventions++3. **Analyze search results** - Determine best match or need for new icon++4. **Recommend existing icon OR create new one** - Based on search results++## Step 1: Search Existing Icons++**Searching for concept**: "$1"++### Current Available Icons+```python+# From src/hi/apps/common/templatetags/icons.py+AVAILABLE_ICONS = {+ 'camera', 'cancel', 'check-circle', 'chevron-double-left',+ 'chevron-double-right', 'chevron-down', 'chevron-left',+ 'chevron-right', 'chevron-up', 'clock', 'close', 'cloud',+ 'collection', 'delete', 'edit', 'eye', 'eye-off', 'history',+ 'home', 'info-circle', 'layers', 'lightbulb', 'lock',+ 'map-pin', 'move', 'path', 'play', 'plug', 'plus',+ 'question-circle', 'rocket', 'rotate', 'save', 'settings',+ 'shield', 'sync', 'upload', 'video', 'view', 'warning', 'zoom'+}+```++### Semantic Matching Strategy+Look for matches based on:+- **Action synonyms**:+ - Add/Create/New → `plus`+ - Edit/Modify/Change → `edit`+ - Delete/Remove/Trash → `delete`+ - Save/Submit/Confirm → `save` or `check-circle`+ - Cancel/Close/Dismiss → `cancel` or `close`+- **Universal conventions**:+ - Settings/Config → `settings`+ - Help/Support → `question-circle`+ - Alert/Attention → `warning`+ - Success → `check-circle`+ - Error → `close` or `cancel`+- **Navigation patterns**:+ - Back/Previous → `chevron-left`+ - Forward/Next → `chevron-right`+ - Up/Down → `chevron-up`/`chevron-down`++## Step 2: Decision - Use Existing or Create New++### IF good match found:+**Recommendation**: Use existing icon `[icon-name]`++**Usage example**:+```django+{% load icons %}+{% icon "[icon-name]" size="sm" css_class="hi-icon-left" %}+```++**Rationale**: [Why this icon matches the concept]++### IF no good match:+**Recommendation**: Create new icon `[proposed-name]`++**Rationale**: No existing icon adequately represents "$1" because [specific gap]++## Step 3: Create New Icon (if needed)++### Icon Creation Process++**1. Create SVG template file**:+```django+<!-- src/hi/templates/icons/[new-icon-name].html -->+<svg class="{{ class_attr }}" viewBox="0 0 24 24" fill="currentColor" {{ accessibility_attrs }}>+ <path d="[SVG PATH DATA]"/>+</svg>+```++**Requirements**:+- Viewbox MUST be `0 0 24 24`+- Use `fill="currentColor"` for CSS color inheritance+- Simple, optimized paths (single color)+- No transforms, groups, or unnecessary attributes++**2. Register in icon system**:+```python+# src/hi/apps/common/templatetags/icons.py+AVAILABLE_ICONS = {+ # ... existing icons ...+ '[new-icon-name]', # Add alphabetically+}+```++**3. Test the new icon**:+```bash+# Verify icon renders at all sizes+# Test in template with different colors and sizes+```++## Icon Philosophy++**Key Principles**:+1. **Search first** - Use existing icons when possible for consistency+2. **Don't compromise** - Create new icons when existing ones don't fit+3. **Action-focused** - Icons represent actions/concepts, not specific objects+4. **Semantic naming** - Names should be intuitive and follow conventions++**Examples of when to create new icons**:+- Unique action with no close match (e.g., "calibrate", "sync-bidirectional")+- Domain-specific concept (e.g., "weather-alert", "zone-trigger")+- Better semantic clarity needed (e.g., "expand" vs generic "plus")++## Icon Naming Conventions++- **Actions**: verb or verb-noun (`edit`, `delete`, `save`)+- **Objects**: noun (`home`, `user`, `settings`)+- **Directional**: direction-shape (`chevron-up`, `arrow-left`)+- **Status**: state-shape (`check-circle`, `warning`)+- **Compound**: noun-modifier (`eye-off`, `cloud`)++**Concept to find/create**: "$1"++Begin icon discovery and recommendation now.\ No newline at end of filediff --git a/.claude/commands/investigate.md b/.claude/commands/investigate.mdnew file mode 100644index 00000000..abb90a13--- /dev/null+++ b/.claude/commands/investigate.md@@ -0,0 +1,90 @@+---+allowed-tools: Bash, Read, Edit, TodoWrite, Grep, Glob, Task+description: Deep investigation and analysis of GitHub issues for implementation planning+model: claude-3-5-sonnet-20241022+argument-hint: [issue-number]+---++Deep investigation and implementation planning for GitHub issue #$1:++## Investigation Process for #$1++Perform comprehensive codebase analysis and implementation planning:++1. **Use TodoWrite to plan investigation phases** - Track analytical work+ - Read `docs/CLAUDE.md` for AI-specific guidance and sub-agent coordination patterns+ - Follow development philosophy of well-factored solutions++2. **Read GitHub issue completely** - Use `gh issue view $1` to understand:+ - Full issue description and requirements+ - All comments and discussion history+ - Labels, assignees, and project context+ - Related issues or dependencies++3. **Codebase research using specialized agents** - Use Task tool with appropriate agents:+ - **general-purpose agent**: For broad code searches and cross-domain discovery+ - **domain-expert agent**: For business logic analysis+ - **backend-dev agent**: For Django model/database analysis+ - **frontend-dev agent**: For template/UI analysis+ - **integration-dev agent**: For external API analysis++4. **Comprehensive code analysis** - Identify:+ - Relevant files, classes, and functions+ - Current implementation patterns+ - Dependencies and integration points+ - Existing test coverage+ - Similar functionality elsewhere in codebase++5. **Design-heavy issue detection** - Check if issue involves both design AND implementation:+ - Look for requests for "better styling", "improved layout", "enhanced UI"+ - Identify ambiguous visual requirements+ - Assess if wireframes/mockups needed+ - Recommend issue splitting if applicable (per `docs/dev/workflow/workflow-guidelines.md`)++6. **Implementation strategy planning** - Following `docs/dev/workflow/workflow-guidelines.md`:+ - Plan multi-phase approach if complex+ - Phase 1: Simple, reliable solution addressing core issue+ - Phase 2+: Advanced optimizations, UX improvements+ - Identify natural stopping points for review++7. **Impact assessment** - Analyze:+ - Breaking changes potential+ - Performance implications+ - Security considerations+ - Testing requirements++8. **Post comprehensive findings to GitHub issue** - Include:+ - Summary of investigation findings+ - Detailed implementation approach+ - Key files/components to be modified+ - Multi-phase breakdown if applicable+ - Design/implementation splitting recommendation if needed+ - If issue splitting recommended, provide specific `/createissue` commands+ - Questions or concerns requiring clarification+ - Estimated complexity and timeline++9. **Investigation Outcome Recommendations** - Guide next steps based on findings:+ - **Recommend `/plan` if analysis reveals:**+ - Multi-phase implementation needed across multiple PRs+ - Epic-level work requiring issue decomposition+ - Cross-cutting changes affecting multiple systems+ - Work breakdown structure needed for complex features+ - **Recommend `/design` if analysis reveals:**+ - UI/UX decisions requiring mockups or wireframes+ - Visual design specifications missing+ - Interaction patterns need clarification+ - Ambiguous styling or layout requirements+ - **Recommend `/execute` if analysis reveals:**+ - Clear implementation path identified+ - All technical questions resolved+ - Requirements well-defined and single-PR scope+ - Ready for immediate development+ - **Recommend continued `/investigate` if analysis reveals:**+ - Additional research domains identified+ - More technical unknowns discovered+ - Need for deeper integration analysis++**Investigation target:** GitHub issue #$1+**Goal:** Complete technical analysis and implementation roadmap++Begin deep investigation now.\ No newline at end of filediff --git a/.claude/commands/pickup.md b/.claude/commands/pickup.mdnew file mode 100644index 00000000..a6961b90--- /dev/null+++ b/.claude/commands/pickup.md@@ -0,0 +1,84 @@+---+allowed-tools: Bash, Read, TodoWrite, Grep+description: Pick up a GitHub issue following our development workflow+model: claude-3-5-sonnet-20241022+argument-hint: [issue-number]+---++Pick up GitHub issue #$1 following our development workflow from docs/dev/workflow/workflow-guidelines.md:++## Issue Pickup Process for #$1++Execute the complete issue pickup workflow:++1. **Use TodoWrite to plan the pickup process** - Track all workflow steps+ - Read `docs/CLAUDE.md` for development philosophy and workflow integration+ - Focus on well-factored solutions and quality over speed++2. **Read the GitHub issue and all comments** - Understand requirements, context, and discussion using `gh issue view $1`++3. **Complexity Assessment** - Evaluate if pickup is appropriate:+ - **STOP and use `/plan` if:**+ - Issue affects multiple apps/systems+ - Requires breaking changes or major refactoring+ - Scope unclear or too large for single PR+ - Epic-level work requiring decomposition+ - **STOP and use `/investigate` if:**+ - Implementation approach unclear+ - Requires significant codebase research+ - Complex technical challenges or unknowns+ - Integration between multiple systems+ - **STOP and use `/design` if:**+ - Requests "better styling" or "improved layout"+ - Mentions UI/UX improvements+ - Needs mockups or wireframes+ - Visual design decisions required+ - **ESCALATE to `/execute` if:**+ - Multiple technical domains require coordination+ - Issue has functional boundaries divisible among agents+ - Cross-system impacts need expert specialization+ - Implementation phases with dependencies between specialties+ - Work requires backend + frontend + integration coordination+ - **Continue with pickup if:**+ - Single domain/file change with clear solution+ - Bug fix with identified root cause and location+ - Simple enhancement using existing patterns+ - Atomic task suitable for single agent+ - No coordination between technical specialties needed++4. **Ensure on latest staging branch** - MANDATORY safety step:+ - Verify current branch and working directory status+ - Switch to staging: `git checkout staging`+ - Pull latest: `git pull origin staging`+ - Verify clean state: `git status`++5. **Assign issue to yourself** - Use: `gh issue edit $1 --add-assignee @me`++6. **Create feature branch immediately** - Use proper naming from `docs/dev/workflow/workflow-guidelines.md`:+ - Determine branch type from issue labels/content (feature/bugfix/docs/ops/refactor)+ - Create branch: `git checkout -b [type]/$1-[mnemonic]`+ - Push branch: `git push -u origin [branch-name]`++7. **Investigation and planning** - Research the codebase:+ - Search for relevant code, components, and files+ - Identify affected areas and dependencies+ - Understand current implementation+ - Plan implementation approach++8. **Post investigation comment to GitHub issue** - Document:+ - Summary of investigation findings+ - Proposed implementation approach+ - Key files/components to be modified+ - Any questions or concerns identified+ - Multi-phase strategy if applicable (following workflow-guidelines.md)++**Critical requirements:**+- Follow exact workflow from `docs/dev/workflow/workflow-guidelines.md`+- Follow branch naming conventions from `docs/dev/workflow/workflow-guidelines.md`+- Create feature branch BEFORE any investigation work+- Always verify clean working directory before branch operations+- Post comprehensive investigation findings to GitHub issue++**Issue to pick up:** #$1++Begin the pickup process now.\ No newline at end of filediff --git a/.claude/commands/plan.md b/.claude/commands/plan.mdnew file mode 100644index 00000000..801553dc--- /dev/null+++ b/.claude/commands/plan.md@@ -0,0 +1,113 @@+---+allowed-tools: Bash, Read, TodoWrite, Grep, Glob+description: Strategic planning and work breakdown for GitHub issues+model: claude-3-5-sonnet-20241022+argument-hint: [issue-number]+---++Strategic planning and work breakdown for GitHub issue #$1:++## Strategic Planning Process++Help plan the work described in GitHub issue #$1 to determine optimal breakdown strategy:++1. **Use TodoWrite to plan strategic analysis** - Track planning phases+ - Read `docs/CLAUDE.md` for AI-specific guidance and project context+ - Follow development philosophy of well-factored solutions++2. **Read GitHub issue completely** - Understand full scope and context:+ - Use `gh issue view $1` to read issue description and all comments+ - Understand business requirements and user needs+ - Identify stated goals and success criteria+ - Note any existing discussion or proposed approaches++3. **Identify information gaps first** - Look for clarification needs:+ - Ambiguous requirements or unclear specifications+ - Missing technical details or constraints+ - Undefined success criteria or acceptance criteria+ - Unclear dependencies on other systems or features+ - Questions about user experience or design intent++4. **Ask clarifying questions** - Before proposing breakdown strategy:+ - What information is missing or unclear?+ - Are there unstated assumptions that need confirmation?+ - What are the priorities if scope needs to be reduced?+ - Are there specific technical constraints to consider?+ - What is the relationship to existing features or planned work?++5. **Analyze work complexity and scope** - After clarification:+ - Assess overall complexity and effort required+ - Identify distinct functional areas or components+ - Understand dependencies between different parts+ - Evaluate technical risk and uncertainty levels++6. **Evaluate isolation potential** - Key strategic question:+ - Can parts of this work deliver independent value?+ - Would partial implementation be useful even if later phases never happen?+ - Are there natural boundaries that could become separate issues?+ - What are the coupling points between different aspects?++7. **Determine breakdown strategy** - Choose optimal approach:++ **Multi-phase within single issue** (when work is tightly coupled):+ - All phases contribute to same core feature+ - Later phases build directly on earlier ones+ - No independent value from partial completion+ - Example: Phase 1 (core functionality), Phase 2 (optimizations), Phase 3 (advanced features)++ **Multi-issue breakdown** (when work can stand independently):+ - Each issue delivers standalone value+ - Issues can be implemented in any order+ - Each issue useful even if others never completed+ - Example: Separate issues for different features that happen to be related++ **Hybrid approach** (when some parts independent, others coupled):+ - Combination of separate issues and multi-phase within issues+ - Independent features as separate issues+ - Related optimizations as phases within issues++8. **Generate strategic plan** - Provide detailed breakdown:+ - Recommended approach with clear rationale+ - Specific phase or issue breakdown with descriptions+ - Dependencies and ordering recommendations+ - Effort estimates and risk assessment+ - Value delivery timeline and milestones+ - If multi-issue approach recommended, provide `/createissue` commands for each issue++9. **Plan Outcome Execution Guidance** - Direct next steps for implementation:+ - **Use `/design` for issues requiring:**+ - Visual mockups or wireframes for UI changes+ - UI interaction specifications and patterns+ - Design decision clarification before implementation+ - User experience flow definition+ - **Use `/execute` for issues with:**+ - Clear technical requirements and approach+ - Defined implementation path+ - No design ambiguity or visual decisions needed+ - Ready for immediate development+ - **Use `/investigate` for issues needing:**+ - Technical research or feasibility analysis+ - Codebase exploration and pattern discovery+ - Integration complexity assessment+ - Architecture decision investigation+ - **Continue planning if:**+ - Additional issue decomposition needed+ - Cross-issue dependencies require coordination+ - Strategic decisions still unclear++**Strategic Planning Goals:**+- Optimize for independent value delivery+- Minimize dependencies and coupling+- Enable flexible prioritization and scheduling+- Reduce risk through incremental approach+- Ensure clear success criteria for each phase/issue++**Planning Target:** GitHub issue #$1+**Output:** Strategic work breakdown with implementation roadmap++**Key Decision Criteria:**+- Can work stand in isolation regardless if following phases ever get done?+- Is there natural separation between functional areas?+- What delivers maximum value with minimum dependencies?++Begin strategic planning analysis now.\ No newline at end of filediff --git a/.claude/commands/pr.md b/.claude/commands/pr.mdnew file mode 100644index 00000000..7e51948f--- /dev/null+++ b/.claude/commands/pr.md@@ -0,0 +1,125 @@+---+allowed-tools: Bash, Read, Write, TodoWrite+description: Create pull request following our workflow and template requirements+model: claude-3-5-sonnet-20241022+argument-hint: [title]+---++Create pull request with title "$1" following our workflow from `docs/dev/workflow/workflow-guidelines.md`:++## Pull Request Creation Process++Execute the complete PR creation workflow:++1. **Use TodoWrite to plan PR creation steps** - Track all required checks++2. **MANDATORY pre-PR requirements** - Both must pass before PR creation:+ ```bash+ # Run full test suite (must pass)+ make test++ # Run code quality check (must pass with no output)+ make lint+ ```+ **CRITICAL**: Do not create PR if either check fails. Fix all issues first.++3. **Gather PR information** - Collect required details:+ - Current branch name and recent commits+ - Related GitHub issue number(s)+ - Summary of changes made+ - Testing performed+ - Documentation updates needed++4. **Create PR using GitHub CLI** - Follow exact template from `.github/PULL_REQUEST_TEMPLATE.md`:++ **CRITICAL**: Use file-based approach to prevent escaping failures:+ ```bash+ # Write PR body to temporary file first+ cat > /tmp/pr_body.md <<'EOF'+ ## Pull Request: [TITLE]++ ### Issue Link+ Closes #[ISSUE_NUMBER]++ ---++ ## Category+ - [ ] **Feature** (New functionality)+ - [ ] **Bugfix** (Fixes an issue)+ - [ ] **Docs** (Documentation updates)+ - [ ] **Ops** (Infrastructure, CI/CD, build tools)+ - [ ] **Tests** (Adding/improving tests)+ - [ ] **Refactor** (Code improvements without changing functionality)+ - [ ] **Tweak** (Minor UI or code improvements)++ ---++ ## Changes Summary+ - [Describe changes made]++ ---++ ## How to Test+ 1. [Testing steps]++ ---++ ## Checklist+ - [x] Code follows the project's style guidelines.+ - [x] Unit tests added or updated if necessary.+ - [x] All tests pass (`./manage.py test`).+ - [ ] Docs updated if applicable.+ - [x] No breaking changes introduced.++ ---++ ## Related PRs++ ---++ ## Screenshots (if applicable)++ ---++ ## Additional Notes++ ---++ ### **Ready for Review?**+ - [x] This PR is ready for review and merge.+ - [ ] This PR requires more work before approval.++ ---++ ### **Reviewer(s)**+ @cassandra+ EOF++ # Update placeholders in the file+ sed -i '' "s/\[TITLE\]/$1/g" /tmp/pr_body.md+ sed -i '' "s/\[ISSUE_NUMBER\]/ISSUE_NUMBER/g" /tmp/pr_body.md++ # Create PR using file reference+ gh pr create --title "$1" --body-file /tmp/pr_body.md++ # Clean up temporary file+ rm -f /tmp/pr_body.md+ ```++5. **Verify PR creation** - Check that:+ - PR was created successfully+ - Template formatting is correct+ - All required sections are filled+ - Proper category is selected+ - Issue is properly linked++**Requirements:**+- Follow exact workflow from `docs/dev/workflow/workflow-guidelines.md`+- Use exact template from `.github/PULL_REQUEST_TEMPLATE.md`+- Must pass all pre-PR checks before creation+- Use HEREDOC syntax to prevent formatting issues+- No Claude attribution in PR description++**PR Title:** "$1"++Begin PR creation process now.\ No newline at end of filediff --git a/.claude/commands/refactor.md b/.claude/commands/refactor.mdnew file mode 100644index 00000000..f137a2c2--- /dev/null+++ b/.claude/commands/refactor.md@@ -0,0 +1,85 @@+---+allowed-tools: Bash, Read, TodoWrite, Grep, Glob, Task+description: Plan and execute refactoring with expert analysis+model: claude-3-5-sonnet-20241022+argument-hint: [target] (e.g., ClassName, module_name, or file_path)+---++Plan refactoring for: "$1"++## Expert Refactoring Planning Process++Execute comprehensive refactoring analysis and planning:++1. **Use TodoWrite to plan refactoring phases** - Track analysis and implementation+ - Read `docs/CLAUDE.md` for development philosophy and well-factored code principles+ - Use specialized agents for expert refactoring analysis++2. **Analyze current implementation** - Understand existing code:+ - Search for target: "$1" across codebase+ - Identify all usages and dependencies+ - Understand current patterns and structure+ - Document existing behavior and interfaces++3. **Use specialized refactoring agents** - Get expert analysis:+ - **Use Task tool with domain-expert agent**: Analyze business logic and responsibilities+ - **Use Task tool with backend-dev agent**: Django patterns, database design, architecture+ - **Use Task tool with test-engineer agent**: Test impact assessment and strategy+ - **Use Task tool with general-purpose agent**: Broad dependency and cross-domain analysis+ - **Use Task tool with code-quality agent**: Architecture compliance and quality assessment++4. **Identify refactoring opportunities** - Find improvement areas:+ - Code duplication and consolidation opportunities+ - Single Responsibility Principle violations+ - Coupling and cohesion issues+ - Performance bottlenecks+ - Maintainability concerns+ - Testing gaps++5. **Assess refactoring impact** - Evaluate scope and risk:+ - Files and components affected+ - Breaking change potential+ - Test coverage requirements+ - Performance implications+ - Migration complexity+ - Rollback considerations++6. **Plan refactoring phases** - Following workflow-guidelines.md multi-phase strategy:+ - **Phase 1**: Core structural improvements (no behavior changes)+ - **Phase 2**: Interface improvements and optimizations+ - **Phase 3**: Advanced features and enhancements+ - Each phase should be independently valuable++7. **Create implementation strategy** - Detailed execution plan:+ - Step-by-step refactoring sequence+ - Safe transformation techniques+ - Test-driven refactoring approach+ - Validation checkpoints+ - Rollback strategies++8. **Generate refactoring deliverables** - Provide comprehensive plan:+ - Current state analysis and pain points+ - Target architecture and improvements+ - Phase-by-phase implementation plan+ - Risk assessment and mitigation strategies+ - Testing strategy for each phase+ - Success metrics and validation criteria++**Refactoring guidelines:**+- Maintain existing behavior (no functional changes in Phase 1)+- Ensure comprehensive test coverage+- Use incremental, safe transformations+- Plan for rollback at each phase+- Document architectural decisions++**Refactoring target:** "$1"+**Goal:** Well-factored code following our architecture principles++**Key considerations from `docs/CLAUDE.md`:**+- Extremely well factored code+- Thoughtful responsibility boundaries+- Proper encapsulation+- Readability and maintainability+- Find well factored solutions, not just first working solutions++Begin refactoring analysis now.\ No newline at end of filediff --git a/.claude/commands/release.md b/.claude/commands/release.mdnew file mode 100644index 00000000..e9a6cbd9--- /dev/null+++ b/.claude/commands/release.md@@ -0,0 +1,34 @@+---+allowed-tools: Bash, Read, Edit, TodoWrite, Grep, Glob+description: Execute the complete release process from staging to master+model: claude-3-5-sonnet-20241022+argument-hint: [version] (e.g., 1.2.3)+---++Execute our complete release process following `docs/dev/workflow/release-process.md`:++## Release for version $1++I need to execute our standardized release process with the following requirements:++1. **Use TodoWrite to plan all release steps** - Break down the entire process into trackable tasks+2. **Pre-release verification** - Verify CI status, run `make check`, review recent changes+3. **Version management** - Update HI_VERSION file to `$1` and update CHANGELOG.md+4. **Git workflow** - Merge staging to master following our branch strategy+5. **GitHub release** - Create release using `gh` CLI with auto-generated notes+6. **Validation** - Check build artifacts, ZIP file size, and download URLs+7. **Cleanup** - Version bump to next dev version and return to staging+8. **Post-release guidance** - Provide monitoring checklist and next steps++**Critical requirements:**+- Follow exact process in `docs/dev/workflow/release-process.md`+- Handle errors gracefully with rollback guidance+- Verify all prerequisites before starting+- Validate each step before proceeding+- Use TodoWrite tool throughout for progress tracking++**Version to release:** $1+**Target branch:** master+**Source branch:** staging++Begin the release process now.\ No newline at end of filediff --git a/.claude/commands/respond.md b/.claude/commands/respond.mdnew file mode 100644index 00000000..733317a5--- /dev/null+++ b/.claude/commands/respond.md@@ -0,0 +1,140 @@+---+allowed-tools: Bash, Read, TodoWrite, Grep, Glob, Task+description: Systematic response to GitHub pull request feedback+model: claude-3-5-sonnet-20241022+argument-hint: [pr-number]+---++Systematic response to GitHub pull request #$1 feedback:++## PR Feedback Response Process++Focus on responding to feedback on GitHub pull request #$1:++1. **Use TodoWrite to plan feedback response workflow** - Track systematic review response++2. **Review project documentation** - Understand standards and guidelines:+ - Read `docs/CLAUDE.md` for AI behavior patterns and development philosophy+ - Read `docs/dev/workflow/workflow-guidelines.md` for development workflows+ - Read `docs/dev/shared/coding-standards.md` for coding standards+ - Read `docs/dev/testing/testing-guidelines.md` for testing practices+ - Read `docs/dev/shared/architecture-overview.md` for architectural principles++3. **Ensure correct branch state** - Verify working on PR branch:+ ```bash+ # Check current branch and status+ git status+ git branch --show-current++ # Pull latest changes from GitHub if needed+ git pull origin [current-branch]+ ```++4. **Read all PR feedback** - Collect and understand review comments:+ ```bash+ # View PR details and all comments+ gh pr view $1++ # Get detailed review comments+ gh pr view $1 --comments+ ```++5. **Categorize feedback types** - Organize by domain and nature:+ - **Code quality** - Style, patterns, architecture concerns+ - **Logic/functionality** - Business logic, implementation correctness+ - **Testing** - Test coverage, quality, patterns+ - **Documentation** - Comments, docs, README updates+ - **Security** - Security concerns or vulnerabilities+ - **Performance** - Efficiency, optimization suggestions+ - **UI/UX** - Frontend, template, user experience feedback+ - **Questions/clarifications** - Requests for explanation or context++6. **Assess feedback validity** - Evaluate each comment:+ - **Valid and actionable** - Clear improvement that should be implemented+ - **Valid but debatable** - Good point but may have alternative approaches+ - **Needs clarification** - Unclear feedback requiring discussion+ - **Invalid or unnecessary** - Feedback that doesn't align with project standards+ - **Out of scope** - Valid but belongs in separate issue/PR++7. **Create prioritized response plan** - Address most important feedback first:+ - **Priority 1** - Critical issues (security, functionality, breaking changes)+ - **Priority 2** - Important code quality and architecture concerns+ - **Priority 3** - Testing improvements and coverage gaps+ - **Priority 4** - Documentation and clarity improvements+ - **Priority 5** - Style and minor optimization suggestions+ - **Priority 6** - Questions and clarifications++8. **Use specialized analysis for complex feedback** - Get expert assistance:+ - **Use Task tool with domain-expert agent** - Business logic and architecture feedback+ - **Use Task tool with test-engineer agent** - Testing-related feedback+ - **Use Task tool with backend-dev agent** - Django patterns and database feedback+ - **Use Task tool with frontend-dev agent** - UI/template feedback+ - **Use Task tool with code-quality agent** - Code quality and standards feedback++9. **Execute systematic feedback response** - Work through prioritized plan:++ **For each feedback item, choose appropriate response:**++ **Option A: Implement requested change**+ - Make the code/test/documentation change+ - Commit with clear message referencing feedback+ - Verify change addresses the concern completely++ **Option B: Implement alternative solution**+ - Propose and implement better approach+ - Explain reasoning in PR comment reply+ - Ensure solution addresses underlying concern++ **Option C: Provide explanatory reply**+ - Explain why no change is needed+ - Reference project standards or architectural decisions+ - Provide context or rationale for current approach+ - Ask for clarification if feedback is unclear++10. **Validate all responses** - Ensure comprehensive coverage:+ - Every feedback comment has been addressed+ - All code changes maintain quality standards+ - Tests still pass after changes+ - Documentation is updated if needed+ - No regressions introduced++11. **Commit and push updates** - Document feedback responses:+ ```bash+ # Stage and commit changes+ git add .+ git commit -m "Address PR feedback: [summary of changes]"++ # Push updates to PR+ git push+ ```++12. **Follow up on PR** - Ensure review completion:+ - Reply to individual comments as needed+ - Add general PR comment summarizing changes made+ - Request re-review if significant changes made+ - Mark conversations as resolved when appropriate++**Response Strategy Guidelines:**+- Assess validity before responding - don't blindly implement all feedback+- Provide clear rationale when declining to make changes+- Prioritize critical and high-impact feedback first+- Maintain project standards and architectural consistency+- Be collaborative and professional in all responses++**Quality Standards:**+- All changes must follow project coding standards+- Maintain or improve test coverage+- Ensure documentation stays current+- No regressions or breaking changes+- Follow established architectural patterns++**Communication Principles:**+- Be respectful and professional in all responses+- Provide context and reasoning for decisions+- Ask for clarification when feedback is unclear+- Acknowledge good suggestions even if not implementing++**PR Target:** #$1+**Goal:** Systematic and complete response to all review feedback++Begin systematic PR feedback response now.\ No newline at end of filediff --git a/.claude/commands/review.md b/.claude/commands/review.mdnew file mode 100644index 00000000..bdd9e6ca--- /dev/null+++ b/.claude/commands/review.md@@ -0,0 +1,79 @@+---+allowed-tools: Bash, Read, TodoWrite, Task+description: Prepare code for review with quality checks and analysis+model: claude-3-5-sonnet-20241022+argument-hint:+---++Prepare current code for review following our quality standards:++## Code Review Preparation Process++Execute comprehensive review preparation:++1. **Use TodoWrite to plan review preparation** - Track all quality checks+ - Read `docs/CLAUDE.md` for AI behavior patterns and quality standards+ - Use sub-agent coordination for expert analysis++2. **Run mandatory quality checks** - Both must pass:+ ```bash+ # Run full test suite (must pass)+ make test+ ```+ ```bash+ # Run code quality check (must pass with no output)+ make lint+ ```+ **CRITICAL**: Address any failures before proceeding++3. **Generate change summary** - Document what was modified:+ ```bash+ # Show recent commits on current branch+ git log --oneline --graph -10++ # Show diff against staging branch+ git diff staging...HEAD++ # Show changed files+ git diff --name-only staging...HEAD+ ```++4. **Use specialized review agents** - Get expert analysis:+ - **Use Task tool with test-engineer agent**: Review test coverage and quality+ - **Use Task tool with domain-expert agent**: Analyze business logic changes+ - **Use Task tool with backend-dev agent**: Review Django patterns (if applicable)+ - **Use Task tool with frontend-dev agent**: Review template/UI changes (if applicable)++5. **Identify potential issues** - Look for:+ - Code quality concerns+ - Security vulnerabilities+ - Performance implications+ - Breaking changes+ - Missing tests+ - Documentation gaps++6. **Create review checklist** - Generate actionable items:+ - Code quality improvements needed+ - Test coverage gaps to address+ - Documentation updates required+ - Security considerations+ - Performance optimizations+ - Breaking change documentation++7. **Generate review summary** - Provide comprehensive overview:+ - Summary of changes made+ - Key components modified+ - Business impact assessment+ - Quality metrics (tests passing, lint clean)+ - Potential risks or concerns+ - Reviewer guidance and focus areas++**Review preparation goals:**+- Ensure code meets our quality standards+- Identify potential issues before PR creation+- Provide comprehensive change documentation+- Generate reviewer guidance++**Current branch:** [Will be determined from git status]++Begin review preparation now.\ No newline at end of filediff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 53094ea7..acc053d3 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -1,463 +1,93 @@# CLAUDE.md-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.+This file provides AI-specific guidance for Claude Code when working with this repository.-## Development Context - Our Prime Directive+## Development Philosophy - Our Prime Directive-In all the code we write, we strive for extremely well factored code. We are thoughtful about responsibility boundaries, encapsulation, readability and maintainability. We do not write the first code we can think of to solve the problem or meet the requirements: we find a well factored version that does the job.+In all code we write, we strive for extremely well factored code. We are thoughtful about responsibility boundaries, encapsulation, readability and maintainability. We do not write the first code we can think of to solve the problem - we find a well factored version that does the job.-## Quick Reference - Common Process Checkpoints+## Custom Command Ecosystem-**Before Starting Development:**-- [ ] On staging branch with latest changes (`git status`, `git pull origin staging`)-- [ ] Use TodoWrite tool to plan tasks (mandatory for complex work)-- [ ] Create properly named feature branch+This project has extensive custom commands for workflow automation. Use them proactively:-**During All Code Changes:**-- [ ] **All new files MUST end with newline** (prevents W391 linting failures)-- [ ] **All imports MUST be at file top** (never inside functions/methods)-- [ ] **Use `/bin/rm` instead of `rm`** (avoid interactive prompts)+### Strategic & Planning Commands+- **`/plan 123`** - Strategic work breakdown and issue planning+- **`/design 123`** - Design phase with HTML mockups and interaction docs+- **`/createissue type "title"`** - Create GitHub issues with proper templates-**Before Any Commit or Pull Request:**-- [ ] Use concise, factual messages WITHOUT Claude attribution-- [ ] Avoid overly verbose or marketing-like language-- [ ] **DO NOT** add attributions such as: "🤖 Generated with Claude Code" ❌+### Development Execution Commands+- **`/execute 123`** - Complete issue-to-PR orchestration with sub-agent coordination+- **`/pickup 123`** - Issue assignment and branch setup+- **`/investigate 123`** - Deep codebase analysis and implementation planning-**Before Creating Pull Request:**-- [ ] `cd $PROJ_DIR ; make lint` (must show no output)-- [ ] `cd $PROJ_DIR ; make test` (must show "OK")-- [ ] Both MUST pass before PR creation-- [ ] **Use a /tmp file for PR body** (prevents quoting failures)-- [ ] **MUST** use template and follow `.github/PULL_REQUEST_TEMPLATE.md` structure+### Quality & Maintenance Commands+- **`/commit "message"`** - Smart commits following project standards+- **`/review`** - Pre-PR quality preparation with expert analysis+- **`/pr "title"`** - Pull request creation with proper template+- **`/respond 112`** - Systematic PR feedback response+- **`/fixtests`** - Test failure analysis and remediation+- **`/cleanup branch`** - Post-merge branch cleanup-**Before Creating Tests:**-- [ ] Consult Testing guidelines and `docs/dev/testing/testing-guidelines.md`+### Specialized Commands+- **`/debug "issue"`** - AI-assisted debugging and troubleshooting+- **`/refactor Class`** - Expert refactoring planning+- **`/release 1.2.3`** - Complete release process automation+- **`/icon "concept"`** - Find existing icon or create new one-**Process Verification Pattern:**-Before major actions, ask yourself:-1. "Did I use TodoWrite to plan this work?"-2. "Have I run all required tests?"-3. "Is my commit message following guidelines?"-4. "Am I on the correct branch with latest staging changes?"+**Command files:** `.claude/commands/*.md` contain detailed specifications.-## Task Management (TodoWrite Tool)+## AI-Specific Guidelines-**MANDATORY for complex tasks**: Use TodoWrite tool extensively for:-- Planning multi-step implementations-- Breaking down complex issues into phases-- Tracking progress during development-- Including testing and validation steps in todos-- Ensuring no steps are forgotten+### TodoWrite Tool Usage (Mandatory)+- **ALWAYS use TodoWrite** for complex tasks and multi-step work+- Plan before executing, track progress throughout+- Mark tasks completed immediately when finished+- Break down complex issues into trackable phases-**Use immediately when starting work on:**-- GitHub issues with multiple requirements-- Refactoring tasks-- Any work involving multiple files or components+### Sub-Agent Coordination+- **Use specialized agents proactively** - they provide expert-level analysis+- **Launch agents in parallel** when possible for efficiency+- **Be specific about scope** - detailed context yields better results+- **Chain agents** - use output from one as input to another-IMPORTANT: Always use the TodoWrite tool to plan and track tasks throughout the conversation.+**Available agents:** `general-purpose`, `backend-dev`, `frontend-dev`, `domain-expert`, `test-engineer`, `integration-dev`, `code-quality`-## Sub-Agent Usage Patterns+### Project Documentation Structure+- **Authoritative docs:** `docs/dev/` contains official workflow, testing, and coding standards+- **Commands reference these docs** - don't duplicate content+- **When in doubt:** Check `docs/dev/workflow/workflow-guidelines.md` for process questions-Claude Code has access to specialized sub-agents with specific expertise areas defined in their YAML configurations. Use them proactively rather than as a fallback - they often provide more thorough, expert-level analysis than attempting work directly. They should also be useed to do code reviews.+### AI Behavior Patterns+- **Quality over speed** - use well-factored solutions, not first working code+- **Reference documentation** - commands point to authoritative sources+- **Escalate when stuck** - pause after 3 attempts on difficult problems+- **No Claude attribution** - keep commit messages and PR descriptions project-focused-### Best Practices for Sub-Agent Usage+## Core Development Standards-**Be Specific About Scope**: Instead of "help debug tests", use "debug why EntityForm validation is failing when entity_type_str='sensor' but passing for 'wall_switch'"+### Essential Technical Requirements+- **All files must end with newline** (prevents W391 linting failures)+- **All imports at file top** (never inside functions/methods)+- **Use `/bin/rm` not `rm`** (avoid interactive prompts)-**Provide Context**: Give sub-agents the specific issue, relevant code snippets, and what you've already tried+### Quality Gates (Enforced by Commands)+- **`make lint`** must show no output before any PR+- **`make test`** must pass before any PR+- **Use project templates** for PRs and follow `.github/PULL_REQUEST_TEMPLATE.md`+- **Use project templates** for Issues and follow those in `.github/ISSUE_TEMPLATE/*`-**Request Actionable Output**: Ask for specific deliverables like "return the exact test code to add" or "provide the minimal fix for the payload detection logic"+### Workflow Integration+- **Start with commands** - use `/execute 123` for standard workflows+- **Use individual commands** for precise control or unusual cases+- **Follow command guidance** - they reference authoritative documentation+- **Trust the process** - commands implement project best practices-**Chain Sub-Agents**: Use results from one sub-agent as input to another (e.g., investigation findings from general-purpose → specific implementation from domain expert)+## Key Project References-**Key Insight**: Sub-agents often provide more thorough, expert-level analysis than attempting the work directly. Use them proactively rather than as a fallback.+- **Project Structure** `docs/dev/shared/project-structure.md`+- **Workflows:** `docs/dev/workflow/workflow-guidelines.md`+- **Testing:** `docs/dev/testing/testing-guidelines.md`+- **Coding Standards:** `docs/dev/shared/coding-standards.md`+- **Architecture:** `docs/dev/shared/architecture-overview.md`-## Development Workflow for GitHub Issues--When working on GitHub issues, follow this development workflow:--1. **Read the GitHub issue and all its comments** - Understand the requirements, context, and any discussion--2. **Ensure you're on the latest staging branch** - MANDATORY step before any work:- - If coming from a merged PR, run Post-PR Cleanup first (see step 11)- - Switch to staging branch: `git checkout staging`- - Pull latest changes: `git pull origin staging`- - Verify you're on the correct branch: `git status`--3. **Create a feature branch immediately** - MANDATORY before any investigation or changes:- - Use proper naming convention based on issue type:- - **Bug fixes**: `bugfix/##-description` (e.g., `bugfix/31-controller-modal-fix`)- - **New features**: `feature/##-description` (e.g., `feature/45-weather-alerts`)- - **Documentation**: `docs/##-description` (e.g., `docs/22-api-documentation`)- - **Operations**: `ops/##-description` (e.g., `ops/18-docker-improvements`)- - **Refactoring**: `refactor/##-description` (e.g., `refactor/33-cleanup-views`)- - **Why create immediately**: Investigation may involve temporary file changes, and it's safer to work on a branch- - **If no changes needed**: Simply delete the unused branch with `git branch -d branch-name`- - See `docs/dev/workflow/workflow-guidelines.md` for complete conventions including test-only and tweak branches--4. **Use TodoWrite tool to plan the work** - MANDATORY for complex tasks:- - Break down the issue into specific, actionable tasks- - Include investigation, implementation, testing, and validation steps- - Mark tasks as in_progress/completed as you work--5. **Investigate and plan the implementation** - MANDATORY step for all issues:- - Assign the issue to yourself: `gh issue edit <issue-number> --add-assignee @me`- - Research the codebase to understand current implementation- - Identify files, functions, and components that need changes- - Consider edge cases, dependencies, and potential impacts- - **Check for design-heavy issues** - If issue involves both design/UX work AND implementation, consider splitting (see Design-Heavy Issue Detection below)- - Plan the implementation approach and sequence of changes- - **Post a comment on the GitHub issue** documenting:- - Summary of investigation findings- - Proposed implementation approach- - Key files/components that will be modified- - Any questions or concerns identified- - Issue splitting recommendation if applicable- - **Wait for confirmation only if**:- - You have critical questions that could affect the implementation- - Important information is missing or unclear from the issue- - Multiple solution approaches exist with no clear best choice- - The proposed changes have significant architectural implications- - **You recommend splitting a design-heavy issue**- - Otherwise, proceed directly to implementation--#### Design-Heavy Issue Detection and Splitting--During investigation, if an issue involves **both** design/UX work **and** implementation:--**Indicators of design-heavy issues:**-- Requests for "better styling", "improved layout", "enhanced UI"-- Mentions of wireframes, mockups, or visual design-- Ambiguous visual requirements needing clarification-- Multiple UI components or significant template changes-- User experience improvements without specific implementation details--**Recommended approach:**-1. **Suggest issue splitting** in your GitHub comment:- ```- Based on investigation, this issue involves both design and implementation work.- I recommend splitting this into:-- - Issue A: "[Original Title] - Design & Wireframes"- - Create wireframes/mockups- - Define visual approach and information architecture- - Get stakeholder approval on design direction-- - Issue B: "[Original Title] - Implementation"- - Implement approved design- - Code templates and styling- - Add tests and validation-- This approach allows design iteration without blocking implementation and- enables focused review of each phase.- ```--2. **Wait for confirmation** before proceeding (this falls under the "significant architectural implications" case)--3. **If splitting approved**: Complete design work in current issue, create implementation issue upon design approval--4. **If splitting declined**: Proceed but use multi-phase strategy with design as Phase 1--**Design Phase Deliverables:**-- Always include wireframes/mockups as GitHub issue comments with images-- Get explicit "approved for implementation" comment before coding begins-- Use GitHub issue linking (`Closes #123`) to maintain traceability between design and implementation issues--#### Design Work Documentation Workflow--When working on design-focused issues (UX improvements, UI redesigns, mockups, wireframes):--**Local Work Directory Structure:**-```bash-# All design work goes in data/design (git ignored)-data/design/issue-{number}/-├── mockup.html # Interactive HTML mockups-├── architecture.md # Technical architecture docs-├── interaction-patterns.md # UX interaction specifications-├── design-summary.md # Executive summary-└── other-design-artifacts.* # Additional files as needed-```--**Design Workflow Process:**-1. **Create issue subdirectory**: `mkdir -p data/design/issue-{number}`-2. **Iterate locally**: Create, refine, and iterate on design documents locally-3. **No repository commits**: Design work products stay local only (`data/` is in .gitignore)-4. **Post to GitHub issue**: Share stable versions via GitHub issue comments/attachments--**GitHub Issue Documentation Pattern:**-```markdown-## Phase X Design Complete - Ready for Review--Brief summary of key decisions and deliverables:--1. **Interactive Mockup** (attached) - HTML file for browser viewing-2. **Architecture Document** (comment below) - Technical specifications-3. **Interaction Patterns** (comment below) - UX behavior definitions--[Key decisions summary...]--Ready for stakeholder review and implementation planning.-```--**Content Organization:**-- **Visual deliverables** (HTML mockups, images): Attach as GitHub issue attachments-- **Textual content** (markdown docs): Post as regular GitHub issue comments-- **Benefits**: Attachments can be downloaded/viewed directly, comments are searchable and linkable--**Design Iteration Process:**-1. Create design documents in `data/design/issue-{number}/`-2. Iterate and refine locally based on feedback-3. Post important checkpoints or final versions to GitHub issue-4. Never commit design work products to repository-5. Maintain audit trail in GitHub issue comments--This workflow keeps the repository clean while providing comprehensive design documentation and stakeholder review capabilities.--5.5. **For Complex Issues - Apply Multi-Phase Strategy** (when applicable):- - If issue involves multiple aspects, significant trade-offs, or substantial complexity, apply the multi-phase methodology from [Domain Guidelines](dev/domain/domain-guidelines.md#complex-issue-implementation-strategy)- - Post phase breakdown to GitHub issue before starting implementation- - Complete Phase 1 fully, commit and push (but don't create PR yet)- - Update TodoWrite tool with phase completion status- - Stop and report Phase 1 completion with summary- - Wait for human feedback before proceeding to subsequent phases- - Only create PR when all phases complete or explicitly requested--6. **Development environment check** - The virtual environment and necessary environment variables should be set before starting claude. If there is no virtual environment, this is an indication that the environment has not been properly set up. That means the test cannot run and code changes cannot be validated. We shoudl stop the process and fix it. There is no need to check ever time since this shoudl be rare, but if running tests is failing, that is a good thing to look for.--7. **Do development changes** - Commit to git at logical checkpoints during development--8. **After first commit, push the branch to GitHub** - Use the same branch name as the local one--9. **Run Testing Workflow** - MANDATORY before creating PR (see below)--10. **Create a pull request** - Using the template, only after all tests pass--11. **After pull request is merged** - Clean up and prepare for next work (see Post-PR Cleanup below)--### Testing Workflow (Required Before Pull Requests)--**MANDATORY**: Before creating any pull request, you must run and pass all of these checks:--**NOTE**: All commands run from PROJECT ROOT directory for consistency.--```bash-# 1. Run code quality check (only if source code was modified)-make lint-# Must show: no output (clean)--# 2. Run full test suite-make test-# Must show: "OK" with all tests passing-```--**Important**: Do not create pull requests if any of these checks fail. Fix all issues first.--### Pull Request Requirements--Before any pull request can be merged, the following requirements must be met:--1. **Tests**: All tests must pass (`make test`)-2. **Code Quality**: flake8 linting with `.flake8-ci` configuration must pass with no violations (if source code modified) (`make lint`)-3. **GitHub CI**: GitHub Actions will automatically verify these requirements and will block PR merging if they fail-4. **MUST** use pull request template `.github/PULL_REQUEST_TEMPLATE.md`-5. No Claude attributions in message.--These requirements are enforced by GitHub branch protection rules and cannot be bypassed.--For detailed branching conventions and additional workflow information, see `docs/dev/workflow/workflow-guidelines.md`.--## Commit Message Guidelines (Claude-Specific)--- Use concise, descriptive commit messages without attribution text-- Focus on **what** was changed and **why**, not implementation details-- Keep messages professional and project-focused-- **Do NOT include** Claude Code attribution, co-author tags, or generated-by comments--**Good examples:**-```-Fix weather module test failures and improve WMO units handling-Add support for temperature offset unit arithmetic in Pint-Remove invalid AlertUrgency.PAST enum value for weather alerts-```--**Bad Examples:**-```-🤖 Generated with Claude Code-Co-Authored-By: Claude <[email protected]>-```--### Post-PR Cleanup (After Pull Request Merged)--**HUMAN INITIATED**: This workflow must be triggered manually when you confirm a PR has been merged. Never run without explicit confirmation that the PR is merged.--**MANDATORY Safety Checks** - Execute these verification steps before any cleanup actions:--```bash-# 1. Verify current branch is a feature branch (not staging/master)-git branch --show-current-# Must show a feature branch pattern like: bugfix/##-description, feature/##-description, etc.-# STOP if output shows: staging, master, main--# 2. Verify working directory is clean (no uncommitted changes)-git status-# Must show: "nothing to commit, working tree clean"-# STOP if there are uncommitted changes - commit or stash them first--# 3. Verify the PR is actually merged-gh pr view --json state,mergedAt-# Must show: "state": "MERGED" and "mergedAt": with a timestamp-# STOP if state is not "MERGED"-```--**Cleanup Actions** - Only proceed if all safety checks pass:--```bash-# 4. Switch to staging branch-git checkout staging--# 5. Sync with latest remote changes-git pull origin staging--# 6. Delete the merged feature branch (use branch name from step 1)-git branch -d <feature-branch-name>-# Example: git branch -d bugfix/31-controller-modal-fix--# 7. Verify clean final state-git status-# Should show: "On branch staging" and "nothing to commit, working tree clean"-```--**If any safety check fails:**-- **DO NOT proceed** with cleanup actions-- **Address the issue** (commit changes, wait for PR merge, etc.)-- **Re-run verification** before attempting cleanup--This process ensures you're ready for the next issue while preventing accidental data loss.--## Creating GitHub Issues--When creating new GitHub issues, use the appropriate issue template:--### Available Issue Templates-- **Bug Report** (`[Bug]`): For reporting bugs or unexpected behavior-- **Feature Request** (`[Feature]`): For proposing new features or enhancements-- **Refactor Request** (`[Refactor]`): For improving code quality without changing behavior-- **Ops/Deployment Issue** (`[Ops]`): For infrastructure, CI/CD, or deployment issues-- **Documentation** (`[Docs]`): For documentation improvements-- **Tests** (`[Tests]`): For test-related improvements--### Creating Issues via GitHub CLI-When using `gh issue create`, specify the template with the `--template` flag:-```bash-# Examples:-gh issue create --template bug_report.md --title "[Bug] Description"-gh issue create --template refactor.md --title "[Refactor] Description"-gh issue create --template operations.md --title "[Ops] Description"-```--**Note**: The repository has `blank_issues_enabled: false`, so you must use a template.--## Project Documentation References--For comprehensive project information, see:--- **Architecture**: [dev/shared/architecture-overview.md](dev/shared/architecture-overview.md) - System design, patterns, and component overview-- **Development Guidelines**: [dev/shared/coding-standards.md](dev/shared/coding-standards.md) - Coding standards, style guide, and conventions-- **Testing**: [dev/testing/testing-guidelines.md](dev/testing/testing-guidelines.md) - Testing patterns, best practices, and anti-patterns-- **Setup**: [dev/Setup.md](dev/Setup.md) - Environment setup and daily development commands-- **Workflow**: [dev/workflow/workflow-guidelines.md](dev/workflow/workflow-guidelines.md) - Branching, commits, and pull request process--## Release Process (Claude-Specific)--When executing the release process documented in `docs/dev/workflow/release-process.md`, use these AI-specific commands and considerations:--### Release Execution Commands-```bash-# Pre-release verification (combine all checks)-git status && make check--# Version bump and commit-git add HI_VERSION && git commit -m "Bump version number to vX.X.X"-git push origin staging--# Merge to master-git checkout master && git pull origin master-git merge staging && git push origin master--# Create release (CLI method - preferred for automation)-gh release create vX.X.X --title "vX.X.X" --generate-notes --latest-```--### Release Process Considerations-- **Working Directory**: Always verify clean working directory before starting-- **Dependency Vulnerabilities**: GitHub may warn about dependencies during push - note but don't block release-- **Documentation Changes**: Commit any documentation updates to staging before switching branches-- **GitHub CLI**: Prefer `gh` command for release creation over manual UI steps--See `docs/dev/workflow/release-process.md` for the complete process documentation.--## Generated Code Standards (Claude-Specific)--All generated code must comply with the `.flake8-ci` configuration rules. Common issues to avoid:--1. **Final Newlines**: All files must end with a single newline character-2. **Unused Imports**: Remove all unused import statements-3. **Unused Variables**: Remove or prefix unused variables with underscore (`_variable`)-4. **Line Continuation**: Proper indentation for multi-line statements following PEP 8-5. **Line Length**: Respect maximum line length limits defined in `.flake8-ci`--Before submitting code, always run: `make lint` to verify compliance.--## GitHub PR Creation (Claude-Specific)--**CRITICAL**: Use HEREDOC syntax to prevent quoting failures:--```bash-gh pr create --title "Brief Title" --body "$(cat <<'EOF'-[Follow the structure from .github/PULL_REQUEST_TEMPLATE.md]-## Pull Request: [Short Title]--### Issue Link-Closes #123--[Rest of template content]-EOF-)"-```--**Key points:**-- Always use `cat <<'EOF'` with single quotes around EOF-- This prevents variable expansion and special character issues-- Follow the exact structure from `.github/PULL_REQUEST_TEMPLATE.md`--## Django Template Guidelines (Claude-Specific)--Follow Django best practices for template design:--1. **Minimal Business Logic**: Keep business logic out of templates. Complex loops, conditionals, and data processing belong in views or custom template tags/filters.-2. **View Preparation**: Views should prepare all data that templates need. Templates should primarily display pre-processed data.-3. **Simple Conditionals**: Use only simple `{% if %}` statements for display logic. Avoid complex nested loops or data manipulation.-4. **Custom Template Tags**: Create custom template tags or filters for reusable template logic instead of embedding it directly.-5. **Data Structure**: Structure context data in views to match template needs rather than making templates adapt to raw data.--**Good examples:**-```python-# In view-context = {- 'alert': alert,- 'alert_has_visual_content': bool(alert.get_first_image_url()),- 'alert_first_image': alert.get_first_image_url(),-}-```--**Avoid:**-```django-<!-- Complex business logic in template -->-{% for alarm in alert.alarm_list %}- {% for source_details in alarm.source_details_list %}- {% if source_details.image_url %}- <!-- Complex nested logic -->- {% endif %}- {% endfor %}-{% endfor %}-```+Commands automatically reference these documents - no need to read them manually unless working outside command workflows.diff --git a/docs/dev/COMMENTING_GUIDELINES.md b/docs/dev/COMMENTING_GUIDELINES.mddeleted file mode 100644index f1eece87..00000000--- a/docs/dev/COMMENTING_GUIDELINES.md+++ /dev/null@@ -1,166 +0,0 @@-# Code Commenting Guidelines--## Core Philosophy--We generally want to avoid over-commenting and let the code variable/method naming be clear on the intent. We believe in the philosophy: **"Before adding a comment, ask yourself how the code can be changed to make the comment unnecessary."**--## Guidelines--### ✅ GOOD Comments - What TO Include--1. **Design rationale that is non-obvious**- - Example: `# Single source of truth for position vs path classification`- - Explains architectural decisions--2. **Complex domain logic explanations**- - Example: Multi-line explanation of entity delegation concept- - Business rules that aren't obvious from code structure--3. **Summarize complex or non-standard coding approaches**- - When using unusual patterns or workarounds- - Algorithm explanations that aren't obvious--4. **Design decision rationale**- - Example: "The general types could be used for these, since all are just name-value pairs. However, by being more specific, we can provide more specific visual and processing"- - Explains why one approach was chosen over alternatives--5. **Mathematical/geometric calculations**- - Example: `'80.0,40.0', # top-left (100-20, 50-10)`- - Coordinate calculations that are difficult to verify mentally- - Especially valuable in test cases for validation--6. **Cross-file coordination notes**- - Example: `# Match SvgItemFactory.NEW_PATH_RADIUS_PERCENT`- - Important synchronization between related constants/values in different files--7. **Complex domain abstractions**- - Example: Multi-line explanation of LocationItem interface concept- - Abstract concepts that need implementation guidance--8. **Multi-step process/algorithm documentation**- - Example: `alert_manager.py:40-56` - Breaks down the three distinct checks and explains why HTML is always returned- - Complex workflows that need step-by-step explanation of the "why"--9. **External API/library limitations and workarounds**- - Example: `wmo_units.py:838-841` - Documents Pint library limitations requiring unit mappings- - Example: `zoneminder/monitors.py:81-87` - pyzm timezone parsing quirks- - Critical for understanding why non-obvious code patterns exist- - Brief expressions of frustration (e.g., "ugh") acceptable when documenting known pain points--10. **External service configuration rationale**- - Example: `usno.py:59-62` - Documents API priority, rate limits, polling intervals- - Explains constraints and decisions for external integrations--11. **Future extension points**- - Example: `daily_weather_tracker.py:96-100` - "Future: Add other weather field tracking here"- - Marks logical insertion points for anticipated features- - Should be brief hints, not commented-out code blocks--12. **Temporal/timing complexity in APIs**- - Example: `zoneminder/monitors.py:99-110` - Events as intervals vs points, open/closed handling- - Example: `zoneminder/monitors.py:166-171` - Why polling time cannot advance- - Critical for understanding time-based edge cases in external systems--13. **Bug fix documentation**- - Example: `zoneminder/monitors.py:132-133` - "This fixes the core bug where..."- - Documents what was broken and why the current approach fixes it- - Helps prevent regression--### ❌ BAD Comments - What NOT To Include--1. **Avoid commenting obvious variable purposes**- - Bad: `# Store original entity_type_str to detect changes`- - The variable name should make this clear--2. **Remove work-stream artifacts**- - Bad: Comments explaining why tests were removed or referencing specific issues- - Comments should be timeless, not tied to particular development contexts--3. **Redundant descriptions of clear code**- - Bad: `# Track EntityType change and response needed after transaction`- - When variable names already convey this information--4. **Cryptic references**- - Bad: `# Recreate to preserve "max" to show new form`- - If unclear, either explain properly or remove--5. **Development phase/work-stream artifacts**- - Bad: Comments explaining "Phase 3/Phase 4" development contexts- - Bad: Explanations of why code was removed or changed- - These belong in commit messages or PR descriptions, not in main branch code--6. **TODO comments (high bar to justify)**- - Generally avoid TODOs in main branch- - If important enough for TODO, create an issue and prioritize it- - Only acceptable when there's a compelling reason not to address immediately- - Must be specific and actionable, not vague intentions--7. **Commented-out code**- - Bad: Dead code that's been disabled or replaced- - Bad: Example implementations as large code blocks- - Bad: Logic that looks like it might need uncommenting (e.g., `zoneminder/integration.py:65-66`)- - If needed for future reference, create an issue instead- - Exception: Very brief one-line hints at extension points (see "Future extension points" in good comments)- - Commented code creates confusion about whether it should be active--### 🤔 Consider Alternatives--1. **Method names over behavioral comments**- - Instead of commenting behavior, consider renaming methods to be self-documenting- - Example: Comment about "always attempt regardless of mode/view" might be better as a more descriptive method name--## Examples from Entity Module Review--### Keep These Comments:-- `entity/enums.py:104` - "Single source of truth for position vs path classification"-- `entity/entity_pairing_manager.py:20-23` - Multi-line explanation of delegation concept-- `entity/enums.py:160-163` - Explains why specific types exist vs general types-- `location/models.py:224-226` - LocationItem interface concept-- `alert/alert_manager.py:40-56` - Multi-step process breakdown-- `alert/alarm.py:25-27` - Data structure behavior explanation-- `weather/monitors.py:47-50` - Rate-limiting protection rationale-- `weather/wmo_units.py:838-841` - Pint library limitation workarounds-- `weather/aggregated_weather_data.py:26-32` - Comprehensive class documentation-- `zoneminder/monitors.py:99-110` - Complex temporal logic explanation-- `zoneminder/monitors.py:166-171` - Critical edge case reasoning-- `zm_manager.py:22` - External library frustration ("ugh") with context--### Remove/Improve These:-- `entity/views.py:37` - "Store original entity_type_str to detect changes"-- `entity/views.py:48` - "Track EntityType change and response needed after transaction"-- `entity/tests/test_views.py:66-72` - Long explanations of why tests were removed-- `location/edit/views.py:171` - "Recreate to preserve 'max' to show new form" - Cryptic reference-- `location/location_manager.py:169` - "Only collect position OR path based on EntityType, not both" - States obvious-- `alert/alert_queue.py:62` - "Use queue_insertion_datetime instead of start_datetime" - States what code does-- Test files with "Phase 3/Phase 4" development context comments-- `weather/daily_weather_tracker.py:39,42,45` - Simple labels that state the obvious-- `zoneminder/integration.py:65-66` - Commented-out logic that creates confusion--### Borderline (Keep for now):-- `entity/views.py:87` - "Always attempt advanced transition handling regardless of mode/view" - Conveys important business rule despite unclear phrasing-- Enum inline comments - Generally add semantic value about domain purpose--## Special Cases--### TRACE Pattern (Accepted)-- `TRACE = False # for debugging` is an accepted pattern-- Addresses Python logging limitation (lacks TRACE level below DEBUG)-- Used for very frequent or large-volume debug output-- Keep the comment to explain purpose for those unfamiliar with the pattern--## Summary--Comments should explain the **why** not the **what**. Good comments document:-- Non-obvious design decisions-- Complex business logic-- External API/library quirks and workarounds-- Time-based complexities-- Bug fixes that prevent regression--Avoid comments that:-- State what the code obviously does-- Contain development artifacts or work-stream context-- Leave commented-out code (creates confusion)-- Explain what better naming could clarify--When in doubt, ask: "Can I change the code to make this comment unnecessary?"\ No newline at end of filediff --git a/docs/dev/backend/backend-guidelines.md b/docs/dev/backend/backend-guidelines.mdindex 95747979..0f79f8dc 100644--- a/docs/dev/backend/backend-guidelines.md+++ b/docs/dev/backend/backend-guidelines.md@@ -1,382 +1,86 @@# Backend Guidelines-## App Module Structure+## Core Concepts & Modules-Each Django app follows this standard structure:+### App Module Structure+See [Project Structure](../shared/project-structure.md)-```-hi/apps/${APPNAME}/-├── enums.py # Enums related to the module-├── models.py # Django ORM models-├── transient_models.py # Non-ORM models (not persisted)-├── urls.py # URL patterns when module provides views-├── views.py # Main views for module-├── views_mixin.py # Common view functionality-├── forms.py # Django forms for views-├── ${NAME}_manager.py # Singleton manager classes-├── settings.py # User-controllable settings-├── monitors.py # Periodic background processes-├── templates/${APPNAME}/ # App templates-├── apps.py # Django-required module definition-├── tests/ # Tests-└── admin.py # Django admin console integration+### Key Base Classes+- `hi.utils.singleton.Singleton` - All manager classes+- `hi.apps.common.enums.LabeledEnum` - All enums+- `hi.apps.common.model_fields.LabeledEnumField` - Enum storage in models-# Edit mode structure (when applicable)-edit/-├── urls.py # Edit-only URLs-├── views.py # Edit-only views-└── ... # Same structure for edit functionality-```--## Django Model Patterns--### Integration Key Pattern--All external systems use integration keys for entity mapping:--```python-class IntegrationKeyMixin(models.Model):- integration_id = models.CharField(max_length=255, null=True, blank=True)- integration_name = models.CharField(max_length=50, null=True, blank=True)-- class Meta:- abstract = True-- @property- def integration_key(self):- return f"{self.integration_name}:{self.integration_id}"-```--### Entity-Centric Design+## Design Patterns+### Entity-Centric ArchitectureAll controllable/observable items modeled as entities with states:--```python-class Entity(IntegrationKeyMixin):- name = models.CharField(max_length=100)- location = models.ForeignKey('location.Location', on_delete=models.CASCADE)- entity_type = models.ForeignKey('EntityType', on_delete=models.CASCADE)-- class Meta:- indexes = [- models.Index(fields=['integration_name', 'integration_id']),- ]--class EntityState(models.Model):- entity = models.ForeignKey(Entity, on_delete=models.CASCADE, related_name='states')- entity_state_type = models.ForeignKey('EntityStateType', on_delete=models.CASCADE)-- class Meta:- unique_together = ['entity', 'entity_state_type']-```---### Database Indexing Strategy--Strategic use of `db_index=True` for query performance:--```python-class SensorResponse(models.Model):- sensor = models.ForeignKey(Sensor, on_delete=models.CASCADE, db_index=True)- timestamp = models.DateTimeField(auto_now_add=True, db_index=True)- value = models.TextField()-- class Meta:- indexes = [- models.Index(fields=['sensor', '-timestamp']), # Composite index for queries- models.Index(fields=['timestamp']), # For time-range queries- ]-```--## Singleton Manager Pattern--Core functionality uses singleton pattern for system-wide coordination:--```python-from hi.utils.singleton import Singleton--class AlertManager(Singleton):- def __init_singleton__(self):- self._alert_queue = AlertQueue()- self._lock = threading.Lock()-- def add_alert(self, alert_data):- with self._lock:- # Thread-safe alert processing- self._alert_queue.add(alert_data)-- @classmethod- def instance(cls):- """Get singleton instance"""- return cls()-```--### Manager Initialization Patterns--```python-def ensure_initialized(self):- """Ensure manager is properly initialized (sync version)"""- if not hasattr(self, '_initialized'):- self._initialize_data_structures()- self._initialized = True--async def ensure_initialized_async(self):- """Ensure manager is properly initialized (async version)"""- if not hasattr(self, '_initialized'):- await self._initialize_data_structures_async()- self._initialized = True-```--## Dual Sync/Async Patterns--Many manager classes support both Django views and async integration services:--```python-class WeatherManager(Singleton):- def get_current_conditions(self):- """Synchronous version for Django views"""- return self._fetch_conditions_sync()-- async def get_current_conditions_async(self):- """Asynchronous version for integrations"""- return await self._fetch_conditions_async()-- def do_control(self, device_id, action):- """Sync control for web requests"""- return self._execute_control(device_id, action)-- async def do_control_async(self, device_id, action):- """Async control for background processes"""- return await self._execute_control_async(device_id, action)-```--## Background Process Integration--### Thread Management--```python-class AppMonitorManager(Singleton):- def __init_singleton__(self):- self._event_loop = None- self._background_threads = []- self._shutdown_event = threading.Event()-- def start_background_monitoring(self):- """Start background monitoring threads"""- thread = threading.Thread(target=self._monitor_loop, daemon=True)- thread.start()- self._background_threads.append(thread)-- def shutdown(self):- """Graceful shutdown of background processes"""- self._shutdown_event.set()- for thread in self._background_threads:- thread.join(timeout=5.0)-```--### Django + AsyncIO Integration--```python-import asyncio-from asgiref.sync import sync_to_async--class IntegrationManager(Singleton):- def __init_singleton__(self):- self._event_loop = asyncio.new_event_loop()-- async def process_entities_async(self):- """Process entities with proper ORM access"""- # Use select_related to prevent lazy loading issues- entities = await sync_to_async(list)(- Entity.objects.select_related('location', 'entity_type').all()- )-- for entity in entities:- await self._process_entity_async(entity)-```--## Django Views--**Simple Views**: Our design philophy is to keep the Django view classes in views.py somewhat simple. When where the views need non-trivial computations, database queries or construction of intricate data structure, we use some helper class to encapsulate the business logic. For example, the method _group_history_by_time() should be moved to a helper class. In this case, given the scope of video browsing, it makes sense for there to be a dedicated class for all the various helpers needed related to this feature.--**URL Names**: Always leverage Django url names and never depend on details and strings of user-facing urls.--## Performance Optimization Patterns--### TTL Caching--```python-from cachetools import TTLCache-import threading--class StatusDisplayManager(Singleton):- def __init_singleton__(self):- self._cache = TTLCache(maxsize=1000, ttl=60) # 1 minute TTL- self._cache_lock = threading.Lock()-- def get_status_display(self, entity_id):- with self._cache_lock:- if entity_id in self._cache:- return self._cache[entity_id]-- status = self._compute_status_display(entity_id)- self._cache[entity_id] = status- return status-```--### Deque-based Aggregation--```python-from collections import deque--class AlertManager(Singleton):- def __init_singleton__(self):- # Memory-efficient circular buffer- self._recent_alerts = deque(maxlen=100)-- def add_alert(self, alert):- self._recent_alerts.append(alert)- # Automatically removes oldest when maxlen exceeded-```--## Django View Patterns--### View Mixins for Common Functionality--```python-class EntityMixin:- def get_entity(self):- """Get entity from URL parameters"""- entity_id = self.kwargs.get('entity_id')- return get_object_or_404(Entity, id=entity_id)--class LocationViewMixin:- def get_location_view(self):- """Get current location view from session"""- location_view_id = self.request.session.get('location_view_id')- if location_view_id:- return LocationView.objects.get(id=location_view_id)- return None-```--### Custom View Base Classes--```python-class HiModalView(View):- """Base for views that handle both sync and async requests"""-- def dispatch(self, request, *args, **kwargs):- if request.headers.get('X-Requested-With') == 'XMLHttpRequest':- return self.async_dispatch(request, *args, **kwargs)- return self.sync_dispatch(request, *args, **kwargs)-- def sync_dispatch(self, request, *args, **kwargs):- """Handle synchronous requests - render full page"""- response = super().dispatch(request, *args, **kwargs)- return response-- def async_dispatch(self, request, *args, **kwargs):- """Handle AJAX requests - return JSON with HTML fragments"""- response = super().dispatch(request, *args, **kwargs)- if hasattr(response, 'content'):- return JsonResponse({- 'modal': response.content.decode('utf-8'),- 'status': 'success'- })- return response-```--## Enums--We leverage enums extensively and do not allow "magic" strings to represent core concepts that the application Logic depends on. We have defined a base class `hi.apps.common.enums.LabeledEnums` for al enums used in the application that slightly extends their capabilities and provides some convenience methods.--A key convenience method is the `from_name` and `from_name_safe` methods. These provide more robust case-insensitve and whitespace-insensitive matching. The latter does not raise an exception for bad values, but returns the default value for uses where the default bhavior is better than interrupting the flow.--### Enums in Django Models--We have a pattern for storing enums in the database that is used throughout the code. It is described like this:--The design pattern for storing enumerated values in the Database is *NOT* to use the Django/databases enumeration/choices type, but use a string via Django CharField (VARCHAR) instead. The rationale is that we prefer the flexibility to add new enums without requiring a database migration for such a trivial change.--We use a special base level enum hi.apps.common.LabeledEnum for most enums, but especially those stored in the database. The key features of this class is to ensure consistency as we put values into and out of the database, and to gracefully handle the case of improper values. Specifically, the `__str__` method returns the enum name in *LOWER* case, though the Django name field matches the casing of the defined enum.--Further, we adopt a naming convention to make the difference between the enum class and the Django model field distinct by having the Django field always have `str` as the fielkd name suffix. For example, if the enum class is named `EntityType`, the Django field name would be `entity_type_str`. Further, we also add a setter/getter pair on the model that matches the enum name and that accepts/returns an enum instance. e.g.,-```- @property- def entity_type(self) -> EntityType:- return EntityType.from_name_safe( self.entity_type_str )-- @entity_type.setter- def entity_type( self, entity_type : EntityType ):- self.entity_type_str = str(entity_type)- return-```--We are aware that there is a risk in this pattern, and we have done work to correct it by creating the custom Django model field `hi.apps.common.model_fields.LabeledEnumField`. All going forward new enums must use this new custom field when storing in a model. Retrofitting existing models is on a best effort, time availability basis.--## Settings and Configuration--### App Settings Pattern--Each internal Django app module can provide user-controllable settings that appear on the main config page. These settings are auto-discovered by the `config` app module. The presence of a file named `settings.py` in an app module will automatically get picked up and create a new config area on the user-facing config page.--In the `settings.py` file, define a subclass of the enum `SettingEnum` to define the label and data types:--```python-# In app/settings.py-from hi.config.enums import SettingEnum--class WeatherSettings(SettingEnum):- REFRESH_INTERVAL = ("refresh_interval", int, 300, "Weather refresh interval (seconds)")- DEFAULT_LOCATION = ("default_location", str, "", "Default weather location")- ENABLE_ALERTS = ("enable_alerts", bool, True, "Enable weather alerts")-- def __init__(self, key, data_type, default_value, description):- self.key = key- self.data_type = data_type- self.default_value = default_value- self.description = description-```--### Adding to Existing Settings--After adding a new value to an app's `SettingEnum`, you will need to run `./manage.py migrate` to populate the database with the new setting and its default value. New settings are written to the DB using a post-migrate signal.--### Internal Settings Debugging--For debugging help, there is a URL to inspect the Django internal `settings.py` content:-```-http://localhost:8411/config/internal-```--### Adding New Config UI Tab Section--To add a new tab section to the Configuration UI:--1. **Add entry to `ConfigPageType`**-2. **Add a View** - view class should extend `ConfigPageView`-3. **Override methods**:- - `config_page_type()`- - `get_main_template_name()`- - `get_template_context()`-4. **Create template** (matching name)-5. **Template should extend** `config/pages/config_base.html`-6. **Add to `urls.py`** (ensure this is included in top-level `urls.py`)+- `Entity` model with `IntegrationKeyMixin` for external system mapping+- `EntityState` for current state tracking+- Integration key format: `"integration_name:integration_id"`++### Singleton Manager Pattern+Core functionality uses singleton pattern with thread-safe initialization:+- Implement `__init_singleton__()` not `__init__()`+- Use `cls.instance()` for access+- Include `ensure_initialized()` and `ensure_initialized_async()` methods++### Dual Sync/Async Support+Manager classes provide both sync (Django views) and async (integrations) methods:+- Sync: `get_data()`, `do_control()`+- Async: `get_data_async()`, `do_control_async()`++### Database Patterns+- Strategic indexing: Use `db_index=True` and composite indexes+- Entity queries: Always use `select_related()` for foreign keys+- Enum storage: CharField with `LabeledEnumField`, not Django choices++## Django View Philosophy++### Simple Views+Keep view classes lightweight - delegate complex logic to helper classes:+- Business logic → Helper classes+- Database queries → Manager classes+- Data structure construction → Dedicated builder classes++### View Patterns+- Use mixins for common functionality (`EntityMixin`, `LocationViewMixin`)+- Custom base classes for specialized behaviors (`HiModalView`)+- Always use Django URL names, never hardcoded URLs++## Settings & Configuration++### App Settings Auto-Discovery+Create `settings.py` in any app with `SettingEnum` subclass:+- Automatically appears on config page+- Requires `./manage.py migrate` after adding new settings+- Debug internal settings at `/config/internal`++### Adding Config UI Sections+1. Add entry to `ConfigPageType` enum+2. Create view extending `ConfigPageView`+3. Override required methods+4. Create template extending `config/pages/config_base.html`++## Performance Patterns++### Caching+- TTL caching: `cachetools.TTLCache` with thread locks+- Memory efficiency: `collections.deque` for circular buffers++### Threading & AsyncIO+- Background threads: Daemon threads with graceful shutdown+- Django+AsyncIO: Use `asgiref.sync.sync_to_async` for ORM access++## Development Tools++### Debug Settings+Modify `src/hi/settings/development.py`:+- `SUPPRESS_SELECT_REQUEST_ENPOINTS_LOGGING` - Hide polling requests+- `SUPPRESS_MONITORS` - Disable background tasks+- `BASE_URL_FOR_EMAIL_LINKS` - Email link testing## Related Documentation-- Django patterns: [Django Patterns](django-patterns.md)-- Database conventions: [Database Conventions](database-conventions.md)-- Async/sync patterns: [Async Sync Patterns](async-sync-patterns.md)-- Integration patterns: [Integration Guidelines](../integrations/integration-guidelines.md)-- Testing: [Testing Guidelines](../testing/testing-guidelines.md)-- Generic Attributes [Attribute Editing Integration Guide](./attribute-editing-integration-guide.md)--## Debugging--## Custom Debug Settings--You can modify these variables in `src/hi/settings/development.py` to enable/disable some custom development features:--- `SUPPRESS_SELECT_REQUEST_ENPOINTS_LOGGING` - Suppress showing the request line log message. The polling front-end will generate a long stream of these and it make it hard to see other requests.-- `SUPPRESS_MONITORS` - Turns off running any of the background monitor tasks. Useful when working on something not related ot them to prevent unnecessary logging and resource usage.-- `BASE_URL_FOR_EMAIL_LINKS` - If needing to test the links in delivered emails. We usually need this to point back to the local development server that send the email.+- [Coding Patterns](../shared/coding-patterns.md)+- [Database Conventions](database-conventions.md)+- [Integration Guidelines](../integrations/integration-guidelines.md)+- [Testing Guidelines](../testing/testing-guidelines.md)diff --git a/docs/dev/backend/database-conventions.md b/docs/dev/backend/database-conventions.mdindex e6a43d50..d3a43060 100644--- a/docs/dev/backend/database-conventions.md+++ b/docs/dev/backend/database-conventions.md@@ -14,4 +14,4 @@ class Meta:## Related Documentation- Backend guidelines: [Backend Guidelines](backend-guidelines.md)-- Django patterns: [Django Patterns](django-patterns.md)\ No newline at end of file+- Coding patterns: [Django Patterns](../shared/coding-patterns.md)diff --git a/docs/dev/domain/domain-guidelines.md b/docs/dev/domain/domain-guidelines.mdindex 98eed944..7f04704e 100644--- a/docs/dev/domain/domain-guidelines.md+++ b/docs/dev/domain/domain-guidelines.md@@ -1,309 +1,85 @@# Domain Guidelines-## Entity-Centric Design Philosophy+## Entity-Centric Architecture-The system models all controllable/observable items as entities with states. This provides a unified approach to managing diverse physical and logical objects.+All controllable/observable items modeled as entities with states for unified management.-## Core Domain Models--### Entity Hierarchy+### Core Models- **Entity**: Central model for all objects (devices, features, software)-- **EntityState**: Hidden state variables that are sensed/controlled+- **EntityState**: State variables that are sensed/controlled- **EntityType**: Categorization and behavior definition-- **EntityPosition/EntityPath**: Spatial representation in locations--### Location Modeling- **Location**: Physical spaces with SVG-based floor plans-- **LocationView**: Configurable views of locations with bounds and rotation-- **LocationItem**: Abstract interface for positionable items+- **Sensor/Controller**: Observation and control of entity states-### Sensor/Controller Pattern-- **Sensor**: Observation of entity state variables-- **Controller**: Actions to affect entity state variables-- **SensorResponse**: Historical sensor readings+Also see [Data Model](../shared/data-model.md)## Business Logic Patterns### Status Display System+Entity status driven by `StatusDisplayManager` which:+- Calculates display states from sensor data+- Implements time-based value decay (Active → Recent → Past → Idle)+- Resolves priority when entities have multiple sensors+- Coordinates with frontend for visual representation-All entity state variables are indirectly observed through sensors, and all sensor values come from integrations. Integrations normalize sensor values and encapsulate them in SensorResponse instances. The SensorResponseManager receives these responses and provides latest status values and histories to views, also detecting changes and feeding them into the alerting subsystem.--### Status Display Logic--Entity status display is driven by business logic that determines how sensor readings translate into visual states. The `StatusDisplayManager` coordinates this process by calculating appropriate display states based on current and historical sensor data.--```python-class StatusDisplayManager(Singleton):- def get_status_display_data(self, entity):- """Compute display state data for entity"""- current_state = entity.get_current_state()- return StatusDisplayData(- status_level=self.calculate_status_level(current_state),- priority_state=self.resolve_priority_state(entity),- decaying_status=self.calculate_decaying_status(entity, timezone.now())- )-```--The visual implementation of this status data (CSS classes, colors, SVG styling) is handled by the frontend system. See [Entity Status Display](../frontend/entity-status-display.md) for visual implementation details.--### Value Decaying Logic--For some entity state types and sensors, we display not only current sensor values but also visually represent recent past values. For example, when motion is detected in an area, we highlight that, but after motion ends, we visually show it was "active" in the recent past (Active red → Recent orange → Past yellow → Idle green).--#### Implementation Approach--The decaying logic creates synthetic visual states ("recent" and "past") that are not actual EntityState values, but are derived from history and timing of sensor readings. The system examines both current and previous sensor values with timestamps to determine appropriate visual representation.+**Key Classes**: `StatusDisplayManager`, `StatusDisplayData`, `SensorResponseManager`-**Key Concept**: The system uses configurable time thresholds to transition between visual states. An entity that was recently active but is now idle will show as "recent" (orange) for a period, then transition to "past" (yellow), and finally to "idle" (green).+### Multi-Sensor Priority Resolution+Each `LocationView` can set `location_view_type` to determine which `EntityStateType` takes precedence for visual display. See `hi.apps.location.enums.LocationViewType`.-**Supported State Types**: Currently implemented for movement sensors, presence sensors, and open/close sensors - entity types where showing recent activity history provides valuable context.--**Color Progression**: Typical color flow is: Active (red) → Recent (orange) → Past (yellow) → Idle (green/gray). This creates an intuitive visual "cooling off" effect.--**Architecture**: The logic is centralized in the status display system (`StatusDisplayData` and `StatusDisplayManager` classes) and integrates with the existing client-server polling mechanism for real-time updates.--```python-class EntityStatusCalculator:- def calculate_decaying_status(self, entity, current_time):- """Calculate status with time-based decay"""- latest_activity = entity.get_latest_activity()- if not latest_activity:- return EntityStatus.IDLE-- time_since = current_time - latest_activity.timestamp-- if time_since < timedelta(minutes=5):- return EntityStatus.ACTIVE- elif time_since < timedelta(minutes=30):- return EntityStatus.RECENT- elif time_since < timedelta(hours=2):- return EntityStatus.PAST- else:- return EntityStatus.IDLE-```--### Multiple Sensors Priority--The visual representation is always for an Entity, but an entity can have multiple states and multiple sensors. Trying to support visual distinctions across the cross-product of values for multiple sensors would be too complicated. Thus, the design decision is that at most one entity state will determine the visual view of the SVG.--We define a default priority of entity states and use the highest priority state. However, a single static priority order is too limiting for many use cases. We need to support different priorities for different purposes. For example, we may want a climate control view and a security view of a defined area. In the former, we want the temperature sensor value to dictate visual display, while in the latter, the motion sensor should impact the area's visual display.--To allow user control over visuals from sensor values, each LocationView instance can have its `location_view_type` set to one of the enum values which determines which EntityStateType value takes precedence for status displays. See `hi.apps.location.enums.LocationViewType`.--```python-class EntityStatePriorityResolver:- def resolve_display_state(self, entity, location_view_type):- """Resolve which state takes precedence for display"""- state_priorities = self.get_priorities_for_view_type(location_view_type)-- active_states = entity.get_active_states()- highest_priority_state = max(- active_states,- key=lambda state: state_priorities.get(state.entity_state_type, 0)- )-- return highest_priority_state-```+### Weather Integration+Multi-source weather system with:+- **WeatherManager**: Singleton coordinating multiple data sources+- **Priority-based data merging**: Higher priority sources provide primary data+- **Alert integration**: External weather alerts converted to system alarms+- **Source attribution**: Every data point tracked with source and timestamp+See [Weather Integration](../integrations/weather-integration.md) for technical details.-## Event-Driven Architecture+## Event & Alert Architecture### Event System- **EventDefinition**: Multi-clause triggers with time windows-- **EventClause**: Individual conditions for triggering-- **EventAction**: Automated responses to events+- **EventClause**: Individual trigger conditions+- **EventAction**: Automated responses### Alert System-- **Alert**: System-wide notifications and alarms+- **Alert**: System-wide notifications- **AlertManager**: Singleton queue-based processing-- **AlarmLevel**: Priority classification for alerts+- **AlarmLevel**: Priority classification-### Weather Integration--The weather system follows a pluggable business design to support multiple data sources and provide unified weather information throughout the system.--#### Business Logic Principles--- **Multi-Source Strategy**: System does not depend on any single weather data source-- **Data Merging**: Combines data from multiple sources using priority-based resolution-- **Source Attribution**: Every data point is associated with its source and fetch time-- **Priority Resolution**: Higher priority sources provide primary data; lower priority sources fill gaps or replace stale data--#### Core Components--- **WeatherManager**: Singleton manager coordinating weather data from multiple sources-- **WeatherData**: Unified weather information model used throughout the system-- **WeatherAlert**: Integration with the alert system for weather-based notifications--#### Weather Alert Integration--Weather alerts from external sources integrate with the system alert architecture by converting external weather alerts to system Alarms based on:--- **Alert Type Filtering**: Determines which external weather alerts should create system alarms-- **Severity Mapping**: Maps external weather alert severity levels to system `AlarmLevel` values-- **Lifetime Management**: Weather alerts have different duration characteristics than sensor-based events-- **Security Level Application**: Weather alarms typically apply to all security levels (unlike sensor-based alarms)--For technical implementation details of weather data sources and API integration, see [Weather Integration](../integrations/weather-integration.md).+## Advanced Patterns-## Complex Calculations--### Geometric Calculations--Location-based geometric operations for spatial relationships and positioning:--```python-class LocationGeometry:- def calculate_bounds_with_rotation(self, bounds, rotation_degrees):- """Calculate bounding box accounting for rotation"""- rotation_radians = math.radians(rotation_degrees)- cos_r, sin_r = math.cos(rotation_radians), math.sin(rotation_radians)-- # Transform all corners and find bounding box- corners = self.get_bounds_corners(bounds)- transformed_corners = [- self.rotate_point(corner, cos_r, sin_r)- for corner in corners- ]-- return self.calculate_bounding_box(transformed_corners)-- def calculate_spatial_relationships(self, entity_positions):- """Determine spatial relationships between entities"""- relationships = []- for i, pos1 in enumerate(entity_positions):- for j, pos2 in enumerate(entity_positions[i+1:], i+1):- distance = self.calculate_distance(pos1, pos2)- if distance < self.proximity_threshold:- relationships.append(SpatialRelationship(- entities=(pos1.entity, pos2.entity),- relationship_type=RelationshipType.ADJACENT,- distance=distance- ))- return relationships-```--For frontend-specific coordinate transformations, SVG viewbox operations, and screen positioning, see [SVG Coordinate Operations](../frontend/svg-coordinate-operations.md).+### Entity Delegation+Delegate entities reflect principal entity states using `EntityStateDelegation` model with automatic state synchronization.### Collection Management+Logical entity groupings with aggregate status calculation from member entities.-```python-class Collection(models.Model):- """Logical grouping of entities"""- name = models.CharField(max_length=100)- entities = models.ManyToManyField(Entity, related_name='collections')-- def get_aggregate_status(self):- """Calculate collection status from member entities"""- entity_statuses = [- entity.get_current_status()- for entity in self.entities.all()- ]-- if any(status.is_critical() for status in entity_statuses):- return CollectionStatus.CRITICAL- elif any(status.is_active() for status in entity_statuses):- return CollectionStatus.ACTIVE- else:- return CollectionStatus.IDLE-```--## File and Resource Management--### Entity Images and Assets--```python-class EntityAsset(models.Model):- entity = models.ForeignKey(Entity, on_delete=models.CASCADE)- asset_type = models.CharField(max_length=50)- file_path = models.FileField(upload_to='entity_assets/')-- def delete(self, *args, **kwargs):- """Clean up files on deletion"""- if self.file_path and os.path.isfile(self.file_path.path):- os.remove(self.file_path.path)- super().delete(*args, **kwargs)-- def generate_unique_filename(self):- """Generate collision-resistant filenames"""- ext = self.file_path.name.split('.')[-1]- return f"{uuid.uuid4()}.{ext}"-```--## Enum Business Rules+### Spatial Calculations+Location-based geometric operations for entity positioning and spatial relationships.### Security State Logic+Enums with embedded business rules for state transitions and behavior validation.++## Key Modules & Classes-```python-class SecurityState(Enum):- ARMED = ("armed", True, True, "#dc3545")- DISARMED = ("disarmed", True, False, "#28a745")- TRIGGERED = ("triggered", False, True, "#dc3545")- MAINTENANCE = ("maintenance", False, False, "#ffc107")-- def __init__(self, name, auto_change_allowed, sends_notification, color):- self.value = name- self.auto_change_allowed = auto_change_allowed- self.sends_notification = sends_notification- self.color = color-- @classmethod- def from_name_safe(cls, name, default=None):- """Safe enum lookup with business logic"""- for state in cls:- if state.value == name:- return state-- # Business rule: invalid states default to maintenance- return default or cls.MAINTENANCE-- def can_transition_to(self, target_state):- """Business rules for state transitions"""- if self == self.TRIGGERED and target_state != self.DISARMED:- return False # Must disarm from triggered state-- if self == self.MAINTENANCE and not target_state.auto_change_allowed:- return False # Can't auto-change from maintenance-- return True-```+### Managers+- `hi.apps.sensor.sensor_response_manager.SensorResponseManager`+- `hi.apps.alert.alert_manager.AlertManager`+- `hi.apps.weather.weather_manager.WeatherManager`-## Entity Delegation Pattern+### Enums+- `hi.apps.location.enums.LocationViewType`+- `hi.apps.common.enums.LabeledEnum` (base class)-```python-class EntityStateDelegation(models.Model):- """Delegate entity state reflects principal entity state"""- delegate_entity = models.ForeignKey(- Entity,- on_delete=models.CASCADE,- related_name='delegated_from'- )- principal_entity = models.ForeignKey(- Entity,- on_delete=models.CASCADE,- related_name='delegated_to'- )- entity_state_type = models.ForeignKey(EntityStateType, on_delete=models.CASCADE)-- class Meta:- unique_together = ['delegate_entity', 'entity_state_type']-- def sync_state(self):- """Synchronize delegate state with principal"""- principal_state = self.principal_entity.get_state(self.entity_state_type)- delegate_state, created = EntityState.objects.get_or_create(- entity=self.delegate_entity,- entity_state_type=self.entity_state_type,- defaults={'current_value': principal_state.current_value}- )-- if not created and delegate_state.current_value != principal_state.current_value:- delegate_state.current_value = principal_state.current_value- delegate_state.save()-```+### Models+- `hi.apps.entity.models.Entity`+- `hi.apps.entity.models.EntityState`+- `hi.apps.location.models.Location`## Related Documentation-- Entity patterns: [Entity Patterns](entity-patterns.md)-- Event and alert systems: [Event Alert Systems](event-alert-systems.md)-- Business logic: [Business Logic](business-logic.md)-- Data model concepts: [Data Model](../shared/data-model.md)\ No newline at end of file+- [Entity Patterns](entity-patterns.md)+- [Event Alert Systems](event-alert-systems.md)+- [Business Logic](business-logic.md)+- [Data Model](../shared/data-model.md)diff --git a/docs/dev/frontend/entity-status-display.md b/docs/dev/frontend/entity-status-display.mdindex 80b56dec..448d57a1 100644--- a/docs/dev/frontend/entity-status-display.md+++ b/docs/dev/frontend/entity-status-display.md@@ -2,1454 +2,12 @@## Quick Reference-### Common Tasks-- **Add new status color** → [Update CSS variables](#status-color-system) → Modify `:root` color definitions-- **Change status progression** → [Update color classes](#visual-state-progression) → Modify state-specific CSS-- **Fix polling issues** → [Check polling system](#polling-system-implementation) → Verify `/api/status` endpoint-- **Update entity styling** → [Modify CSS classes](#css-class-mapping) → Edit `.entity-svg` rules-- **Test status changes** → [Use synthetic data](#server-response-format) → Create test entities with different states-### Key Files- **CSS**: Status colors defined in CSS custom properties (`:root` section)- **JavaScript**: `polling.js` handles real-time updates via `/api/status`- **Templates**: Entity elements need `data-entity-id` attributes for updates- **Backend**: `StatusDisplayManager` calculates display states from sensor data-### Quick Fixes-| Problem | Solution | Location |-|---------|----------|----------|-| Colors not updating | Check CSS class application | [CSS Class Mapping](#css-class-mapping) |-| Polling not working | Verify StatusPoller initialization | [Polling System](#polling-system-implementation) |-| SVG elements not styling | Add proper CSS selectors | [SVG Element Handling](#svg-element-handling) |-| Status stuck on old value | Check server response format | [Server Response Format](#server-response-format) |---## Real-World Workflow Examples--### Workflow 1: Adding Status Display to New Entity Template--**Scenario**: You have a new entity type (smart thermostat) that needs status display functionality in location views.--**Step-by-Step Implementation:**--1. **Plan the Visual States** (Domain consideration)- ```python- # Thermostat states we want to display:- # - heating (red) - actively heating- # - cooling (blue) - actively cooling- # - idle (green) - maintaining temperature- # - offline (gray) - no communication- ```--2. **Define Status CSS Classes** ([CSS Class Mapping](#css-class-mapping))- ```css- /* Add to your CSS file */- .entity-svg.thermostat-heating {- fill: var(--status-active);- stroke: #cc0000;- }-- .entity-svg.thermostat-cooling {- fill: #0066cc;- stroke: #004499;- }-- .entity-svg.thermostat-idle {- fill: var(--status-idle);- stroke: #006600;- }-- .entity-svg.thermostat-offline {- fill: var(--status-unknown);- stroke: #666666;- }- ```--3. **Update Backend Status Logic** ([Server Response Format](#server-response-format))- ```python- # In your entity model or status manager- class ThermostatStatusCalculator:- def get_status_css_classes(self, thermostat_entity):- current_state = thermostat_entity.get_current_state('hvac_mode')-- if not current_state or current_state.is_stale():- return ['thermostat-offline']-- mode = current_state.value- if mode == 'heating':- return ['thermostat-heating']- elif mode == 'cooling':- return ['thermostat-cooling']- elif mode == 'idle':- return ['thermostat-idle']- else:- return ['thermostat-offline']- ```--4. **Update Template Integration** ([Template Integration](#template-integration))- ```django- <!-- In your location view template -->- <g class="entity-group" data-entity-id="{{ thermostat.id }}">- <use href="#icon-thermostat"- class="entity-svg {{ thermostat.get_status_css_classes|join:' ' }}"- transform="translate({{ thermostat.position.x }}, {{ thermostat.position.y }})"/>- </g>- ```--5. **Test Status Updates** ([Polling System Implementation](#polling-system-implementation))- ```javascript- // Verify polling picks up thermostat status changes- // Check browser Network tab for /api/status requests- // Manually trigger state change and observe visual update- ```--**Expected Result**: Thermostat icons change color in real-time based on heating/cooling state.-------### Workflow 2: Debugging Status Colors Not Updating--**Scenario**: Entity status colors were working, but stopped updating after a recent template change.--**Systematic Debugging Process:**--1. **Quick Diagnostic** ([Quick Reference](#quick-reference))- ```bash- # Check browser dev tools - Elements tab- # Look for data-entity-id attribute and CSS classes on entity elements- ```--2. **Verify CSS Class Application** ([Troubleshooting - CSS Classes Not Applied](#status-colors-not-updating))- ```javascript- // In browser console:- const element = document.querySelector('[data-entity-id="123"]');- console.log('Element found:', element);- console.log('Current classes:', element.classList);- console.log('Data attribute:', element.getAttribute('data-entity-id'));- ```--3. **Check Polling System** ([Troubleshooting - Polling System](#polling-system-not-working))- ```javascript- // Verify StatusPoller is running- console.log('StatusPoller:', window.statusPoller);-- // Check network requests- // Browser Dev Tools → Network → Filter by '/api/status'- // Should see requests every 5 seconds- ```--4. **Test Server Response** ([Server Response Format](#server-response-format))- ```bash- # Test API endpoint directly- curl http://localhost:8411/api/status- # Should return JSON with entities object containing your entity ID- ```--5. **Verify CSS Variables** ([Status Color System](#status-color-system))- ```css- /* Check these are defined in your CSS */- :root {- --status-active: #dc3545;- --status-idle: #28a745;- /* ... other status colors */- }- ```--6. **Fix Template Structure** ([Template Integration](#template-integration))- ```django- <!-- Ensure proper structure -->- <g data-entity-id="{{ entity.id }}"> <!-- Must have data-entity-id -->- <path class="entity-svg {{ entity.get_status_css_classes }}"> <!-- Must have CSS classes -->- </g>- ```--**Common Resolution**: Missing `data-entity-id` attribute or incorrect CSS class application.-------### Workflow 3: Implementing Custom Status Progression--**Scenario**: Create a custom "warming up" status for heating systems that shows a gradual color transition.--**Implementation Steps:**--1. **Design Color Progression** ([Visual State Progression](#visual-state-progression))- ```css- /* Define custom progression: cold → warming → warm → hot */- .heating-system.state-cold {- fill: #4a90e2;- opacity: 0.6;- }- .heating-system.state-warming {- fill: #f5a623;- opacity: 0.7;- }- .heating-system.state-warm {- fill: #e94b3c;- opacity: 0.8;- }- .heating-system.state-hot {- fill: #d0021b;- opacity: 1.0;- }- ```--2. **Implement Transition Logic** ([Client-Server Status Updates](#client-server-status-updates))- ```javascript- class HeatingStatusManager {- updateHeatingDisplay(entityId, temperature, targetTemp) {- const element = document.querySelector(`[data-entity-id="${entityId}"]`);-- // Calculate heating state based on temperature difference- const tempDiff = targetTemp - temperature;- let statusClass;-- if (tempDiff > 5) statusClass = 'state-cold';- else if (tempDiff > 2) statusClass = 'state-warming';- else if (tempDiff > 0.5) statusClass = 'state-warm';- else statusClass = 'state-hot';-- // Apply with smooth transition- element.classList.remove('state-cold', 'state-warming', 'state-warm', 'state-hot');- element.classList.add(statusClass);- }- }- ```--3. **Add Smooth Transitions** ([Performance Considerations](#performance-considerations))- ```css- .heating-system {- transition: fill 2s ease-in-out, opacity 1s ease-in-out;- }- ```--4. **Test Progression** ([Testing](#testing))- ```javascript- // Test all state transitions- const heatingManager = new HeatingStatusManager();- const testCases = [- { temp: 65, target: 72 }, // Should be cold- { temp: 69, target: 72 }, // Should be warming- { temp: 71, target: 72 }, // Should be warm- { temp: 72, target: 72 } // Should be hot- ];-- testCases.forEach(test => {- heatingManager.updateHeatingDisplay('test-heater', test.temp, test.target);- });- ```--**Expected Result**: Heating system icons smoothly transition through color progression as they approach target temperature.-------### Workflow 4: Performance Optimization for Many Entities--**Scenario**: Location view with 100+ entities is experiencing slow status updates and browser lag.--**Optimization Process:**--1. **Identify Performance Bottlenecks** ([Performance Considerations](#performance-considerations))- ```javascript- // Measure update performance- console.time('status-update');- statusPoller.updateEntityStates(largeStatusData);- console.timeEnd('status-update');- ```--2. **Implement Batched Updates** ([Performance - Batch Updates](#performance-issues))- ```javascript- class OptimizedStatusPoller extends StatusPoller {- updateEntityStates(statusData) {- const updates = Object.entries(statusData.entities);-- // Process in batches to avoid blocking UI- const batchSize = 20;- let currentBatch = 0;-- const processBatch = () => {- const start = currentBatch * batchSize;- const end = Math.min(start + batchSize, updates.length);-- for (let i = start; i < end; i++) {- const [entityId, stateData] = updates[i];- this.updateEntityDisplay(entityId, stateData);- }-- currentBatch++;-- if (end < updates.length) {- requestAnimationFrame(processBatch);- }- };-- processBatch();- }- }- ```--3. **Reduce Polling Frequency** ([Performance - Reduce Polling](#performance-issues))- ```javascript- // Adaptive polling based on entity count- const entityCount = Object.keys(statusData.entities).length;- const pollInterval = entityCount > 50 ? 10000 : 5000; // 10s vs 5s-- const statusPoller = new OptimizedStatusPoller(pollInterval);- ```--4. **Optimize CSS Transitions** ([CSS Animation Optimization](#css-animation-optimization))- ```css- /* Use transform and opacity instead of color changes where possible */- .entity-svg {- transition: opacity 0.3s ease, transform 0.3s ease;- /* Avoid: transition: fill 0.3s ease; // Expensive! */- }-- .entity-svg.performance-optimized {- transform: translateZ(0); /* Force hardware acceleration */- will-change: transform, opacity;- }- ```--**Expected Result**: Smooth status updates even with 100+ entities, no UI blocking.--## Common Patterns Library--### Standard Entity Status Templates--#### Basic SVG Entity with Status Classes-```django-<!-- Standard pattern for positioned entity icons -->-<g class="entity-group" data-entity-id="{{ entity.id }}">- <use href="#icon-{{ entity.entity_type.name.lower }}"- class="entity-svg {{ entity.get_status_css_classes|join:' ' }}"- transform="translate({{ entity.position.x }}, {{ entity.position.y }})- scale({{ entity.position.scale|default:1.0 }})- rotate({{ entity.position.rotation|default:0 }})"/>-</g>-```--#### Path Entity with Dynamic Styling-```django-<!-- Standard pattern for area/path-based entities -->-<g class="entity-group" data-entity-id="{{ entity.id }}">- <path class="entity-path {{ entity.get_status_css_classes|join:' ' }}"- d="{{ entity.path.svg_path }}"- style="fill: {{ entity.get_status_fill }};- stroke: {{ entity.get_status_stroke }};- opacity: {{ entity.get_status_opacity }}"/>-</g>-```--#### Entity Status Card (Non-SVG)-```django-<!-- Standard pattern for entity cards in lists/grids -->-<div class="entity-card" data-entity-id="{{ entity.id }}">- <div class="status-indicator {{ entity.get_status_css_classes|join:' ' }}"- style="background-color: {{ entity.get_status_color }}"></div>- <span class="entity-name">{{ entity.name }}</span>- <span class="entity-state">{{ entity.get_current_display_state }}</span>-</div>-```--### Standard CSS Status Classes--#### Basic Status Color Scheme-```css-/* Standard status color variables */-:root {- --status-active: #dc3545; /* Red - Active/Alert */- --status-recent: #fd7e14; /* Orange - Recently active */- --status-past: #ffc107; /* Yellow - Past activity */- --status-idle: #28a745; /* Green - Idle/Safe */- --status-unknown: #6c757d; /* Gray - Unknown/Offline */-}--/* Basic entity status classes */-.entity-svg.state-active {- fill: var(--status-active);- stroke: #b02a37;- opacity: 1.0;-}--.entity-svg.state-recent {- fill: var(--status-recent);- stroke: #cc6200;- opacity: 0.8;-}--.entity-svg.state-past {- fill: var(--status-past);- stroke: #cc9a00;- opacity: 0.6;-}--.entity-svg.state-idle {- fill: var(--status-idle);- stroke: #1e7e34;- opacity: 0.4;-}--.entity-svg.state-unknown {- fill: var(--status-unknown);- stroke: #545b62;- opacity: 0.3;-}-```--#### Smooth Status Transitions-```css-/* Standard transition pattern for status changes */-.entity-svg, .entity-path {- transition: fill 0.3s ease-in-out,- stroke 0.3s ease-in-out,- opacity 0.3s ease-in-out;-}--/* Pulse animation for active states */-@keyframes status-pulse {- 0% { opacity: 0.8; }- 50% { opacity: 1.0; }- 100% { opacity: 0.8; }-}--.entity-svg.state-active.pulse-enabled {- animation: status-pulse 2s ease-in-out infinite;-}-```--#### Device-Type Specific Patterns-```css-/* Motion sensor specific styling */-.entity-svg.motion-sensor.state-active {- fill: #dc3545;- filter: drop-shadow(0 0 4px rgba(220, 53, 69, 0.6));-}--/* Door sensor specific styling */-.entity-svg.door-sensor.state-active {- fill: #dc3545;- stroke-width: 3;-}--/* Temperature sensor color gradient */-.entity-svg.temperature-sensor.temp-hot {- fill: #dc3545; /* Hot - red */-}-.entity-svg.temperature-sensor.temp-warm {- fill: #fd7e14; /* Warm - orange */-}-.entity-svg.temperature-sensor.temp-cool {- fill: #17a2b8; /* Cool - blue */-}-.entity-svg.temperature-sensor.temp-cold {- fill: #007bff; /* Cold - dark blue */-}-```--### Standard JavaScript Polling Implementation--#### Basic StatusPoller Class-```javascript-// Standard polling implementation pattern-class StatusPoller {- constructor(options = {}) {- this.pollInterval = options.pollInterval || 5000;- this.endpoint = options.endpoint || '/api/status';- this.isPolling = false;- this.errorCount = 0;- this.maxErrors = 3;- }-- start() {- if (this.isPolling) return;- this.isPolling = true;- this.errorCount = 0;- this.poll();- }-- stop() {- this.isPolling = false;- }-- async poll() {- if (!this.isPolling) return;-- try {- const response = await fetch(this.endpoint);- if (!response.ok) throw new Error(`HTTP ${response.status}`);-- const statusData = await response.json();- this.updateEntityStates(statusData);- this.errorCount = 0; // Reset error count on success- } catch (error) {- console.error('Status polling failed:', error);- this.errorCount++;-- if (this.errorCount >= this.maxErrors) {- console.error('Too many polling errors, stopping poller');- this.stop();- return;- }- }-- if (this.isPolling) {- setTimeout(() => this.poll(), this.pollInterval);- }- }-- updateEntityStates(statusData) {- if (!statusData.entities) return;-- Object.entries(statusData.entities).forEach(([entityId, stateData]) => {- this.updateEntityDisplay(entityId, stateData);- });- }-- updateEntityDisplay(entityId, stateData) {- const elements = document.querySelectorAll(`[data-entity-id="${entityId}"]`);- elements.forEach(element => {- this.applyStatusClasses(element, stateData.cssClasses);- this.applyColorScheme(element, stateData.colorScheme);- });- }-- applyStatusClasses(element, cssClasses) {- // Remove existing status classes- const existingClasses = Array.from(element.classList).filter(c =>- c.startsWith('state-') || c.startsWith('temp-') || c.startsWith('priority-')- );- element.classList.remove(...existingClasses);-- // Apply new status classes- if (cssClasses && cssClasses.length) {- element.classList.add(...cssClasses);- }- }-- applyColorScheme(element, colorScheme) {- if (!colorScheme) return;-- if (element.tagName.toLowerCase() === 'path' || element.tagName.toLowerCase() === 'use') {- element.style.fill = colorScheme.fill || '';- element.style.stroke = colorScheme.stroke || '';- element.style.opacity = colorScheme.opacity || '';- } else if (element.classList.contains('status-indicator')) {- element.style.backgroundColor = colorScheme.fill || '';- element.style.borderColor = colorScheme.stroke || '';- element.style.opacity = colorScheme.opacity || '';- }- }-}-```--#### Standard Initialization Pattern-```javascript-// Standard way to initialize status polling-document.addEventListener('DOMContentLoaded', function() {- // Initialize status poller if entity elements exist- if (document.querySelectorAll('[data-entity-id]').length > 0) {- window.statusPoller = new StatusPoller({- pollInterval: 5000,- endpoint: '/api/status'- });- window.statusPoller.start();- }-- // Cleanup on page unload- window.addEventListener('beforeunload', function() {- if (window.statusPoller) {- window.statusPoller.stop();- }- });-});-```--### Standard Backend Response Patterns--#### Standard Server Response Format-```python-# Standard format for /api/status endpoint responses-{- "timestamp": "2025-01-15T10:30:00Z",- "entities": {- "entity_123": {- "cssClasses": ["state-active", "priority-high"],- "colorScheme": {- "fill": "#dc3545",- "stroke": "#b02a37",- "opacity": "0.8"- },- "displayState": "Motion Detected",- "lastUpdated": "2025-01-15T10:29:45Z"- },- "entity_456": {- "cssClasses": ["state-idle"],- "colorScheme": {- "fill": "#28a745",- "stroke": "#1e7e34",- "opacity": "0.4"- },- "displayState": "No Motion",- "lastUpdated": "2025-01-15T10:25:12Z"- }- }-}-```--#### Standard Django Model Methods-```python-# Standard methods for Entity models to support status display-class Entity(models.Model):- def get_status_css_classes(self):- """Return CSS classes for current status"""- status_manager = StatusDisplayManager(self)- return status_manager.get_css_classes()-- def get_status_color(self):- """Return fill color for current status"""- status_manager = StatusDisplayManager(self)- return status_manager.get_fill_color()-- def get_status_display_data(self):- """Return complete status data for API responses"""- status_manager = StatusDisplayManager(self)- return {- 'cssClasses': status_manager.get_css_classes(),- 'colorScheme': {- 'fill': status_manager.get_fill_color(),- 'stroke': status_manager.get_stroke_color(),- 'opacity': status_manager.get_opacity()- },- 'displayState': status_manager.get_display_state(),- 'lastUpdated': self.get_last_updated_timestamp()- }-```--### Common Entity Status Testing Patterns--#### Standard Test Fixtures-```python-# Standard test setup for entity status testing-class EntityStatusTestCase(TestCase):- def setUp(self):- self.location = Location.objects.create(name='Test Location')-- # Create test entities with different types- self.motion_sensor = Entity.objects.create(- name='Test Motion Sensor',- entity_type=EntityType.MOTION_SENSOR,- location=self.location- )-- self.door_sensor = Entity.objects.create(- name='Test Door Sensor',- entity_type=EntityType.DOOR_SENSOR,- location=self.location- )-- # Create EntityPosition for icon entities- EntityPosition.objects.create(- entity=self.motion_sensor,- x=100, y=150, scale=1.0, rotation=0- )-- def create_test_state(self, entity, state_type, value, timestamp=None):- """Helper to create test entity states"""- timestamp = timestamp or timezone.now()- return EntityState.objects.create(- entity=entity,- state_type=state_type,- value=value,- timestamp=timestamp- )-- def assert_status_response(self, response, entity_id, expected_classes):- """Helper to assert status API response format"""- self.assertSuccessResponse(response)- self.assertJsonResponse(response)-- data = response.json()- self.assertIn('entities', data)- self.assertIn(entity_id, data['entities'])-- entity_data = data['entities'][entity_id]- self.assertIn('cssClasses', entity_data)- self.assertIn('colorScheme', entity_data)-- for css_class in expected_classes:- self.assertIn(css_class, entity_data['cssClasses'])-```--#### Standard JavaScript Testing Pattern-```javascript-// Standard pattern for testing status updates in browser-function testEntityStatusUpdates() {- // Mock status data- const mockStatusData = {- timestamp: new Date().toISOString(),- entities: {- 'entity_123': {- cssClasses: ['state-active', 'priority-high'],- colorScheme: {- fill: '#dc3545',- stroke: '#b02a37',- opacity: '0.8'- }- }- }- };-- // Test status application- const statusPoller = new StatusPoller();- statusPoller.updateEntityStates(mockStatusData);-- // Verify DOM updates- const element = document.querySelector('[data-entity-id="entity_123"]');- console.assert(element.classList.contains('state-active'), 'Active class not applied');- console.assert(element.style.fill === 'rgb(220, 53, 69)', 'Fill color not applied');-- console.log('Entity status update test passed');-}-```--## Performance Optimization Guide--### Overview--Entity status display can become a performance bottleneck when dealing with many entities, frequent updates, or complex visual effects. This guide provides strategies to maintain smooth, responsive status displays even under heavy load.--### Performance Monitoring and Profiling--#### Measuring Status Update Performance-```javascript-// Monitor status update timing-class StatusPerformanceMonitor {- constructor() {- this.updateTimes = [];- this.maxSamples = 100;- }-- measureUpdate(updateFunction) {- const start = performance.now();- updateFunction();- const end = performance.now();-- this.updateTimes.push(end - start);- if (this.updateTimes.length > this.maxSamples) {- this.updateTimes.shift();- }-- // Log warnings for slow updates- const updateTime = end - start;- if (updateTime > 16) { // More than one frame at 60fps- console.warn(`Slow status update: ${updateTime.toFixed(2)}ms`);- }- }-- getAverageUpdateTime() {- if (this.updateTimes.length === 0) return 0;- return this.updateTimes.reduce((a, b) => a + b, 0) / this.updateTimes.length;- }-- reportPerformance() {- console.log(`Status Update Performance:- Average: ${this.getAverageUpdateTime().toFixed(2)}ms- Max: ${Math.max(...this.updateTimes).toFixed(2)}ms- Min: ${Math.min(...this.updateTimes).toFixed(2)}ms- Samples: ${this.updateTimes.length}`);- }-}-```--#### Browser DevTools Profiling-```javascript-// Enable performance tracking in development-if (process.env.NODE_ENV === 'development') {- // Mark status update cycles for performance timeline- function markStatusUpdate() {- performance.mark('status-update-start');- }-- function measureStatusUpdate() {- performance.mark('status-update-end');- performance.measure('status-update', 'status-update-start', 'status-update-end');- }-- // Use in StatusPoller- markStatusUpdate();- this.updateEntityStates(statusData);- measureStatusUpdate();-}-```--### DOM Update Optimization--#### Batched DOM Modifications-```javascript-// Optimized StatusPoller with batched DOM updates-class OptimizedStatusPoller extends StatusPoller {- updateEntityStates(statusData) {- const updates = Object.entries(statusData.entities);- const batchSize = 20; // Process 20 entities at a time-- // Use requestAnimationFrame to avoid blocking UI- this.processBatch(updates, 0, batchSize);- }-- processBatch(updates, startIndex, batchSize) {- const endIndex = Math.min(startIndex + batchSize, updates.length);-- // Process current batch- for (let i = startIndex; i < endIndex; i++) {- const [entityId, stateData] = updates[i];- this.updateEntityDisplay(entityId, stateData);- }-- // Schedule next batch if more entities remain- if (endIndex < updates.length) {- requestAnimationFrame(() => {- this.processBatch(updates, endIndex, batchSize);- });- }- }-- // Minimize DOM reads and writes- updateEntityDisplay(entityId, stateData) {- const elements = this.cachedElements[entityId] ||- this.cacheEntityElements(entityId);-- elements.forEach(element => {- // Batch style updates- this.batchStyleUpdate(element, stateData);- });- }-- cacheEntityElements(entityId) {- const elements = document.querySelectorAll(`[data-entity-id="${entityId}"]`);- this.cachedElements = this.cachedElements || {};- this.cachedElements[entityId] = Array.from(elements);- return this.cachedElements[entityId];- }-- batchStyleUpdate(element, stateData) {- // Collect all style changes before applying- const styleUpdates = {};-- if (stateData.colorScheme) {- styleUpdates.fill = stateData.colorScheme.fill;- styleUpdates.stroke = stateData.colorScheme.stroke;- styleUpdates.opacity = stateData.colorScheme.opacity;- }-- // Apply all changes at once- Object.assign(element.style, styleUpdates);-- // Update classes in single operation- if (stateData.cssClasses) {- this.applyStatusClasses(element, stateData.cssClasses);- }- }-}-```--#### Virtual Entity Rendering-```javascript-// Only render entities in visible viewport-class VirtualizedStatusDisplay {- constructor(svgElement, options = {}) {- this.svgElement = svgElement;- this.visibleEntities = new Set();- this.hiddenEntities = new Set();- this.viewBox = this.parseViewBox(svgElement.getAttribute('viewBox'));- this.options = {- cullingMargin: options.cullingMargin || 50, // Render margin outside viewport- ...options- };-- // Monitor viewport changes- this.svgElement.addEventListener('viewportChanged', (e) => {- this.updateViewBox(e.detail.viewBox);- });- }-- updateViewBox(newViewBox) {- this.viewBox = newViewBox;- this.updateEntityVisibility();- }-- updateEntityVisibility() {- const entities = this.svgElement.querySelectorAll('[data-entity-id]');-- entities.forEach(entity => {- const isVisible = this.isEntityVisible(entity);- const entityId = entity.getAttribute('data-entity-id');-- if (isVisible && this.hiddenEntities.has(entityId)) {- // Entity became visible- this.showEntity(entity, entityId);- } else if (!isVisible && this.visibleEntities.has(entityId)) {- // Entity became hidden- this.hideEntity(entity, entityId);- }- });- }-- isEntityVisible(entity) {- const bbox = entity.getBBox();- const margin = this.options.cullingMargin;-- return !(- bbox.x + bbox.width < this.viewBox.x - margin ||- bbox.x > this.viewBox.x + this.viewBox.width + margin ||- bbox.y + bbox.height < this.viewBox.y - margin ||- bbox.y > this.viewBox.y + this.viewBox.height + margin- );- }-- showEntity(entity, entityId) {- entity.style.display = 'block';- this.visibleEntities.add(entityId);- this.hiddenEntities.delete(entityId);- }-- hideEntity(entity, entityId) {- entity.style.display = 'none';- this.hiddenEntities.add(entityId);- this.visibleEntities.delete(entityId);- }-}-```--### Memory Management--#### Element Reference Caching-```javascript-// Efficient element caching with memory management-class EntityElementCache {- constructor(maxCacheSize = 1000) {- this.cache = new Map();- this.accessOrder = [];- this.maxCacheSize = maxCacheSize;- }-- get(entityId) {- if (this.cache.has(entityId)) {- // Move to end of access order (LRU)- this.accessOrder = this.accessOrder.filter(id => id !== entityId);- this.accessOrder.push(entityId);- return this.cache.get(entityId);- }- return null;- }-- set(entityId, elements) {- // Evict oldest entries if cache is full- if (this.cache.size >= this.maxCacheSize) {- const oldest = this.accessOrder.shift();- this.cache.delete(oldest);- }-- this.cache.set(entityId, elements);- this.accessOrder.push(entityId);- }-- clear() {- this.cache.clear();- this.accessOrder = [];- }-- // Clean up references to removed entities- cleanup() {- const validEntityIds = new Set();- document.querySelectorAll('[data-entity-id]').forEach(el => {- validEntityIds.add(el.getAttribute('data-entity-id'));- });-- // Remove cached elements for entities that no longer exist- for (const [entityId] of this.cache) {- if (!validEntityIds.has(entityId)) {- this.cache.delete(entityId);- this.accessOrder = this.accessOrder.filter(id => id !== entityId);- }- }- }-}-```--#### Memory Leak Prevention-```javascript-// Prevent memory leaks in long-running applications-class LeakPreventionStatusPoller extends StatusPoller {- constructor(options = {}) {- super(options);- this.cleanupInterval = options.cleanupInterval || 60000; // 1 minute- this.startCleanupTimer();- }-- startCleanupTimer() {- setInterval(() => {- this.performCleanup();- }, this.cleanupInterval);- }-- performCleanup() {- // Clean up element cache- if (this.elementCache) {- this.elementCache.cleanup();- }-- // Remove orphaned event listeners- this.removeOrphanedListeners();-- // Force garbage collection in development- if (typeof gc !== 'undefined') {- gc();- }- }-- removeOrphanedListeners() {- // Track and remove event listeners for removed entities- const currentEntityIds = new Set();- document.querySelectorAll('[data-entity-id]').forEach(el => {- currentEntityIds.add(el.getAttribute('data-entity-id'));- });-- // Clean up listeners for removed entities- if (this.entityListeners) {- Object.keys(this.entityListeners).forEach(entityId => {- if (!currentEntityIds.has(entityId)) {- delete this.entityListeners[entityId];- }- });- }- }-- stop() {- super.stop();-- // Clean up all references- if (this.elementCache) {- this.elementCache.clear();- }-- this.entityListeners = {};- }-}-```--### CSS Performance Optimization--#### Hardware Acceleration-```css-/* Force GPU acceleration for status animations */-.entity-svg, .entity-path {- transform: translateZ(0); /* Force hardware acceleration */- will-change: fill, stroke, opacity; /* Hint browser about changing properties */-}--/* Use transform and opacity for animations (GPU-friendly) */-.entity-svg.status-transition {- transition: transform 0.3s ease, opacity 0.3s ease;-}--/* Avoid expensive properties in animations */-.entity-svg.avoid-expensive {- /* AVOID: animating these properties */- /* transition: width 0.3s ease, height 0.3s ease, background-size 0.3s ease; */-- /* PREFER: animating these properties */- transition: transform 0.3s ease, opacity 0.3s ease;-}-```--#### CSS Containment-```css-/* Use CSS containment to limit reflow/repaint scope */-.entity-group {- contain: layout style paint;-}--.location-view-container {- contain: layout;-}--/* Optimize for large entity lists */-.entity-collection {- contain: layout style paint;- will-change: transform;-}-```--#### Efficient CSS Selectors-```css-/* FAST: Use class selectors */-.entity-svg.state-active { fill: #dc3545; }--/* SLOWER: Avoid complex descendant selectors */-.location-view .entity-group .entity-svg.state-active { fill: #dc3545; }--/* FAST: Specific attribute selectors */-[data-entity-type="motion_sensor"].state-active { fill: #dc3545; }--/* SLOWER: Universal selectors */-* .state-active { fill: #dc3545; }-```--### Network Optimization--#### Intelligent Polling Strategies-```javascript-// Adaptive polling based on system load and entity count-class AdaptiveStatusPoller extends StatusPoller {- constructor(options = {}) {- super(options);- this.baseInterval = options.pollInterval || 5000;- this.minInterval = options.minInterval || 1000;- this.maxInterval = options.maxInterval || 30000;- this.entityCount = 0;- this.systemLoad = 0;- }-- calculateOptimalInterval() {- // Adjust based on entity count- let interval = this.baseInterval;-- if (this.entityCount > 100) {- interval *= 1.5; // Slower polling for many entities- } else if (this.entityCount > 50) {- interval *= 1.2;- }-- // Adjust based on system performance- if (this.systemLoad > 0.8) {- interval *= 2; // Much slower when system is loaded- } else if (this.systemLoad > 0.6) {- interval *= 1.5;- }-- return Math.max(this.minInterval, Math.min(this.maxInterval, interval));- }-- measureSystemLoad() {- // Simple performance measurement- const start = performance.now();-- // Simulate work- for (let i = 0; i < 1000; i++) {- Math.random();- }-- const end = performance.now();- const expected = 1; // Expected time for the work in ms- this.systemLoad = Math.min(1, (end - start) / expected);- }-- async poll() {- this.measureSystemLoad();-- try {- const response = await fetch('/api/status');- const statusData = await response.json();-- this.entityCount = Object.keys(statusData.entities || {}).length;- this.updateEntityStates(statusData);-- this.errorCount = 0;- } catch (error) {- console.error('Status polling failed:', error);- this.errorCount++;- }-- // Use adaptive interval- const interval = this.calculateOptimalInterval();-- if (this.isPolling) {- setTimeout(() => this.poll(), interval);- }- }-}-```--#### Delta Updates-```javascript-// Only send changes since last update-class DeltaStatusPoller extends StatusPoller {- constructor(options = {}) {- super(options);- this.lastUpdateTimestamp = null;- this.entityStates = new Map();- }-- async poll() {- try {- const url = this.lastUpdateTimestamp- ? `/api/status?since=${this.lastUpdateTimestamp}`- : '/api/status';-- const response = await fetch(url);- const statusData = await response.json();-- if (statusData.entities) {- this.processDeltas(statusData);- this.lastUpdateTimestamp = statusData.timestamp;- }- } catch (error) {- console.error('Delta polling failed:', error);- }- }-- processDeltas(statusData) {- Object.entries(statusData.entities).forEach(([entityId, newState]) => {- const currentState = this.entityStates.get(entityId);-- // Only update if state actually changed- if (!currentState || this.hasStateChanged(currentState, newState)) {- this.updateEntityDisplay(entityId, newState);- this.entityStates.set(entityId, newState);- }- });- }-- hasStateChanged(oldState, newState) {- return JSON.stringify(oldState.cssClasses) !== JSON.stringify(newState.cssClasses) ||- JSON.stringify(oldState.colorScheme) !== JSON.stringify(newState.colorScheme);- }-}-```--### Large Dataset Handling--#### Pagination and Lazy Loading-```javascript-// Handle thousands of entities with pagination-class PaginatedStatusDisplay {- constructor(svgElement, options = {}) {- this.svgElement = svgElement;- this.pageSize = options.pageSize || 50;- this.visiblePages = new Set();- this.entityPages = new Map();- this.currentViewport = null;- }-- paginateEntities() {- const entities = this.svgElement.querySelectorAll('[data-entity-id]');- const pages = [];-- // Group entities by spatial locality- const spatialGroups = this.groupEntitiesSpatially(entities);-- spatialGroups.forEach((group, index) => {- const pageId = `page-${index}`;- pages.push({- id: pageId,- entities: group,- bounds: this.calculateGroupBounds(group)- });- });-- return pages;- }-- groupEntitiesSpatially(entities) {- // Use spatial hashing to group nearby entities- const spatialHash = new Map();- const cellSize = 100; // SVG units-- Array.from(entities).forEach(entity => {- const bbox = entity.getBBox();- const cellX = Math.floor(bbox.x / cellSize);- const cellY = Math.floor(bbox.y / cellSize);- const cellKey = `${cellX},${cellY}`;-- if (!spatialHash.has(cellKey)) {- spatialHash.set(cellKey, []);- }- spatialHash.get(cellKey).push(entity);- });-- return Array.from(spatialHash.values());- }-- updateVisiblePages(viewBox) {- this.currentViewport = viewBox;- const pages = this.paginateEntities();-- pages.forEach(page => {- const isVisible = this.isPageVisible(page.bounds, viewBox);-- if (isVisible && !this.visiblePages.has(page.id)) {- this.loadPage(page);- } else if (!isVisible && this.visiblePages.has(page.id)) {- this.unloadPage(page);- }- });- }-- isPageVisible(bounds, viewBox) {- return !(- bounds.right < viewBox.x ||- bounds.left > viewBox.x + viewBox.width ||- bounds.bottom < viewBox.y ||- bounds.top > viewBox.y + viewBox.height- );- }-- loadPage(page) {- // Enable status updates for entities in this page- page.entities.forEach(entity => {- entity.style.display = 'block';- this.enableStatusUpdates(entity);- });-- this.visiblePages.add(page.id);- }-- unloadPage(page) {- // Disable status updates for entities in this page- page.entities.forEach(entity => {- entity.style.display = 'none';- this.disableStatusUpdates(entity);- });-- this.visiblePages.delete(page.id);- }-}-```--### Browser Compatibility Optimization--#### Performance Feature Detection-```javascript-// Adapt performance strategies based on browser capabilities-class BrowserOptimizedStatusPoller extends StatusPoller {- constructor(options = {}) {- super(options);- this.browserCapabilities = this.detectCapabilities();- this.adaptToBrowser();- }-- detectCapabilities() {- return {- hasRequestAnimationFrame: typeof requestAnimationFrame !== 'undefined',- hasIntersectionObserver: typeof IntersectionObserver !== 'undefined',- hasWebGL: this.hasWebGLSupport(),- supportsCSSSContainment: CSS.supports('contain', 'layout'),- supportsWillChange: CSS.supports('will-change', 'transform'),- isLowEndDevice: this.detectLowEndDevice()- };- }-- hasWebGLSupport() {- try {- const canvas = document.createElement('canvas');- return !!(canvas.getContext('webgl') || canvas.getContext('experimental-webgl'));- } catch (e) {- return false;- }- }-- detectLowEndDevice() {- // Heuristics for low-end device detection- const memoryGB = navigator.deviceMemory || 4;- const cores = navigator.hardwareConcurrency || 4;- return memoryGB < 2 || cores < 4;- }-- adaptToBrowser() {- if (this.browserCapabilities.isLowEndDevice) {- // Reduce update frequency and batch size- this.pollInterval *= 2;- this.batchSize = 10;- }-- if (!this.browserCapabilities.hasRequestAnimationFrame) {- // Fallback to setTimeout for older browsers- this.useSetTimeoutForUpdates = true;- }-- if (!this.browserCapabilities.supportsCSSSContainment) {- // Disable some optimizations that require CSS containment- this.disableContainmentOptimizations = true;- }- }-}-```--### Performance Monitoring Integration--#### Real-User Monitoring (RUM)-```javascript-// Integration with performance monitoring services-class MonitoredStatusPoller extends StatusPoller {- constructor(options = {}) {- super(options);- this.performanceMetrics = {- updateTimes: [],- errorCounts: {},- memoryUsage: []- };- }-- updateEntityDisplay(entityId, stateData) {- const start = performance.now();-- try {- super.updateEntityDisplay(entityId, stateData);-- const duration = performance.now() - start;- this.recordMetric('updateTime', duration);-- } catch (error) {- this.recordError('updateDisplay', error);- throw error;- }- }-- recordMetric(type, value) {- if (!this.performanceMetrics[type]) {- this.performanceMetrics[type] = [];- }-- this.performanceMetrics[type].push({- value,- timestamp: Date.now()- });-- // Keep only recent metrics (last 5 minutes)- const cutoff = Date.now() - 5 * 60 * 1000;- this.performanceMetrics[type] = this.performanceMetrics[type]- .filter(metric => metric.timestamp > cutoff);- }-- recordError(operation, error) {- if (!this.performanceMetrics.errorCounts[operation]) {- this.performanceMetrics.errorCounts[operation] = 0;- }- this.performanceMetrics.errorCounts[operation]++;-- // Send to monitoring service- if (typeof gtag !== 'undefined') {- gtag('event', 'status_display_error', {- operation,- error_message: error.message- });- }- }-- getPerformanceReport() {- const report = {- averageUpdateTime: this.calculateAverage('updateTime'),- maxUpdateTime: this.calculateMax('updateTime'),- errorRate: this.calculateErrorRate(),- memoryTrend: this.calculateMemoryTrend()- };-- return report;- }-}-```-## OverviewThe entity status display system provides visual feedback for entity states through dynamic CSS classes, SVG styling, and real-time updates. This document covers the frontend implementation details for displaying entity status visually.@@ -1570,429 +128,95 @@ The value decaying system creates a visual "cooling off" effect through color trThe JavaScript `polling.js` module handles real-time status updates through server polling:-```javascript-// Status polling implementation-class StatusPoller {- constructor(pollInterval = 5000) {- this.pollInterval = pollInterval;- this.isPolling = false;- }-- start() {- if (this.isPolling) return;- this.isPolling = true;- this.poll();- }-- async poll() {- try {- const response = await fetch('/api/status');- const statusData = await response.json();- this.updateEntityStates(statusData);- } catch (error) {- console.error('Status polling failed:', error);- }-- if (this.isPolling) {- setTimeout(() => this.poll(), this.pollInterval);- }- }-- updateEntityStates(statusData) {- // Update entity visual states based on server response- Object.entries(statusData.entities).forEach(([entityId, stateData]) => {- this.updateEntityDisplay(entityId, stateData);- });- }-- updateEntityDisplay(entityId, stateData) {- const elements = document.querySelectorAll(`[data-entity-id="${entityId}"]`);- elements.forEach(element => {- this.applyStatusClasses(element, stateData.cssClasses);- this.applyColorScheme(element, stateData.colorScheme);- });- }-}-```-### Server Response FormatThe server returns status updates in a standardized JSON format:-```javascript-{- "timestamp": "2025-01-15T10:30:00Z",- "entities": {- "entity_123": {- "cssClasses": ["state-active", "priority-high"],- "colorScheme": {- "fill": "#dc3545",- "stroke": "#b02a37",- "opacity": 0.8- },- "iconVariant": "motion-active"- }- }-}-```-### Element Targeting and UpdatesThe polling system uses CSS class names and data attributes to target elements:-```javascript-function applyStatusClasses(element, cssClasses) {- // Remove existing state classes- element.classList.remove(...element.classList);-- // Apply new state classes- element.classList.add(...cssClasses);-}--function applyColorScheme(element, colorScheme) {- if (element.tagName === 'path' || element.tagName === 'g') {- // SVG element styling- element.style.fill = colorScheme.fill;- element.style.stroke = colorScheme.stroke;- element.style.opacity = colorScheme.opacity;- } else if (element.tagName === 'div') {- // HTML element styling for non-SVG displays- element.style.backgroundColor = colorScheme.fill;- element.style.borderColor = colorScheme.stroke;- element.style.opacity = colorScheme.opacity;- }-}-```--## SVG Element Handling--### SVG Path and Group Elements--Standard handling for SVG `g` and `path` tags:--```html-<g class="entity-group" data-entity-id="123">- <path class="entity-svg state-idle" d="M10,10 L50,10 L50,50 L10,50 Z"/>-</g>-```--```javascript-// SVG-specific styling-function styleSvgElement(element, stateData) {- element.setAttribute('class', `entity-svg ${stateData.cssClasses.join(' ')}`);- element.style.fill = stateData.colorScheme.fill;- element.style.stroke = stateData.colorScheme.stroke;-}-```--### Special Case Handling--#### Select Tags (Controllers)--Special handling for controller select elements:+## Workflow 1: Adding Status Display to New Entity Template-```javascript-function updateControllerSelect(selectElement, stateData) {- // Update select styling to reflect entity state- selectElement.className = `form-control ${stateData.cssClasses.join(' ')}`;-- // Update associated label or indicator- const indicator = selectElement.nextElementSibling;- if (indicator && indicator.classList.contains('status-indicator')) {- indicator.style.backgroundColor = stateData.colorScheme.fill;- }-}-```--#### DIV Elements (Non-SVG Display)--For entity status in Collection Views or status modals:--```html-<div class="entity-status-card" data-entity-id="123">- <div class="status-indicator"></div>- <span class="entity-name">Motion Sensor</span>-</div>-```--```javascript-function updateStatusCard(cardElement, stateData) {- const indicator = cardElement.querySelector('.status-indicator');- indicator.className = `status-indicator ${stateData.cssClasses.join(' ')}`;- indicator.style.backgroundColor = stateData.colorScheme.fill;-}-```--## Template Integration--### Django Template Setup--Templates must include proper class names and data attributes:--```django-<!-- SVG entity representation -->-<g class="entity-group" data-entity-id="{{ entity.id }}">- <path class="entity-svg {{ entity.get_status_css_classes }}"- d="{{ entity.get_svg_path }}"- style="fill: {{ entity.get_status_color }}"/>-</g>--<!-- Non-SVG entity representation -->-<div class="entity-card" data-entity-id="{{ entity.id }}">- <div class="status-indicator {{ entity.get_status_css_classes }}"- style="background-color: {{ entity.get_status_color }}"></div>- <span class="entity-name">{{ entity.name }}</span>-</div>-```--### Template Context Requirements--Views must provide status data in the context:--```python-# In Django view-context = {- 'entity': entity,- 'status_classes': entity.get_status_css_classes(),- 'status_color': entity.get_status_color(),- 'status_data': entity.get_status_display_data(),-}-```--## Performance Considerations--### Efficient DOM Updates--Minimize DOM manipulation for better performance:--```javascript-// Batch DOM updates-function batchUpdateEntities(statusUpdates) {- // Use DocumentFragment for batch updates- const fragment = document.createDocumentFragment();-- statusUpdates.forEach(update => {- const element = document.querySelector(`[data-entity-id="${update.entityId}"]`);- if (element) {- // Apply updates without triggering reflow- requestAnimationFrame(() => {- this.applyStatusUpdate(element, update.stateData);- });- }- });-}-```--### CSS Animation Optimization--Use transform and opacity for smooth animations:--```css-.entity-svg {- transition: opacity 0.3s ease, transform 0.3s ease;- /* Avoid animating expensive properties like width, height, color */-}--.entity-svg.state-transition {- transform: scale(1.1);- opacity: 0.9;-}-```--## Troubleshooting--### Status Colors Not Updating+**Scenario**: You have a new entity type (smart thermostat) that needs status display functionality in location views.-**Symptoms**: Entity colors remain static, don't reflect current state-**Root Causes & Solutions**:+**Step-by-Step Implementation:**-1. **CSS Classes Not Applied**- ```bash- # Check browser dev tools - Elements tab- # Look for data-entity-id attribute and CSS classes+1. **Plan the Visual States** (Domain consideration)+ ```python+ # Thermostat states we want to display:+ # - heating (red) - actively heating+ # - cooling (blue) - actively cooling+ # - idle (green) - maintaining temperature+ # - offline (gray) - no communication```- - **Fix**: Ensure `StatusPoller.applyStatusClasses()` is called- - **Verify**: Check `element.classList` contains expected state classes-2. **CSS Variables Not Defined**+2. **Define Status CSS Classes** ([CSS Class Mapping](#css-class-mapping))```css- /* Verify these exist in your CSS */- :root {- --status-active: #dc3545;- --status-recent: #fd7e14;- /* ... other status colors */+ /* Add to your CSS file */+ .entity-svg.thermostat-heating {+ fill: var(--status-active);+ stroke: #cc0000;}- ```- - **Fix**: Add missing CSS custom properties- - **Test**: Use browser dev tools to verify computed styles--3. **CSS Selectors Too Specific**- ```css- /* BAD - too specific, won't be overridden */- .location-view .entity-svg.state-active { fill: red !important; }- /* GOOD - proper specificity */- .entity-svg.state-active { fill: var(--status-active); }- ```--### Polling System Not Working--**Symptoms**: Status never updates, even when backend state changes-**Diagnostic Steps**:--1. **Check Network Tab**- ```bash- # Browser Dev Tools → Network Tab- # Look for periodic /api/status requests- # Should see requests every 5 seconds (default)- ```--2. **Verify StatusPoller Initialization**- ```javascript- // Check browser console for errors- console.log('StatusPoller initialized:', window.statusPoller);+ .entity-svg.thermostat-cooling {+ fill: #0066cc;+ stroke: #004499;+ }- // Manually test polling- if (window.statusPoller) {- window.statusPoller.poll();+ .entity-svg.thermostat-idle {+ fill: var(--status-idle);+ stroke: #006600;}- ```--3. **Check Server Response**- ```bash- # Manually test the endpoint- curl http://localhost:8411/api/status- # Should return JSON with entities object- ```--**Common Fixes**:-- **StatusPoller not started**: Call `statusPoller.start()` in DOMContentLoaded-- **URL incorrect**: Verify `/api/status` endpoint exists and returns valid JSON-- **JavaScript errors**: Check browser console for exceptions stopping polling--### SVG Elements Not Styling--**Symptoms**: SVG paths/groups don't change appearance with status updates-**Diagnostic Approach**:--1. **Verify Element Selection**- ```javascript- // Test in browser console- const elements = document.querySelectorAll('[data-entity-id="123"]');- console.log('Found elements:', elements.length);- ```--2. **Check SVG Structure**- ```html- <!-- Required structure -->- <g class="entity-group" data-entity-id="123">- <path class="entity-svg state-idle" d="..."/>- </g>- ```--3. **Test CSS Application**- ```javascript- // Manually apply CSS class- element.classList.add('state-active');- // Should see visual change immediately- ```--**Solutions**:-- **Missing data-entity-id**: Add to parent group or path element-- **Wrong element type**: Use proper selectors for `g` vs `path` elements-- **CSS inheritance issues**: Check if parent elements are blocking style inheritance--### Template Integration Issues--**Symptoms**: New entity templates don't show status updates-**Checklist**:--1. **Required Attributes**- ```django- <!-- MUST have data-entity-id -->- <g data-entity-id="{{ entity.id }}">- <!-- MUST have status CSS classes -->- <path class="entity-svg {{ entity.get_status_css_classes }}">- </g>+ .entity-svg.thermostat-offline {+ fill: var(--status-unknown);+ stroke: #666666;+ }```-2. **Context Data**+3. **Update Backend Status Logic** ([Server Response Format](#server-response-format))```python- # View must provide status data- context = {- 'entity': entity,- 'status_classes': entity.get_status_css_classes(),- 'status_color': entity.get_status_color(),- }+ # In your entity model or status manager+ class ThermostatStatusCalculator:+ def get_status_css_classes(self, thermostat_entity):+ current_state = thermostat_entity.get_current_state('hvac_mode')++ if not current_state or current_state.is_stale():+ return ['thermostat-offline']++ mode = current_state.value+ if mode == 'heating':+ return ['thermostat-heating']+ elif mode == 'cooling':+ return ['thermostat-cooling']+ elif mode == 'idle':+ return ['thermostat-idle']+ else:+ return ['thermostat-offline']```-3. **Template Includes**+4. **Update Template Integration** ([Template Integration](#template-integration))```django- <!-- Ensure polling.js is loaded -->- {% load static %}- <script src="{% static 'js/polling.js' %}"></script>- ```--### Performance Issues--**Symptoms**: Slow status updates, browser lag with many entities-**Solutions**:--1. **Throttle DOM Updates**- ```javascript- // Use requestAnimationFrame for smooth updates- requestAnimationFrame(() => {- this.applyStatusUpdate(element, statusData);- });- ```--2. **Batch Updates**- ```javascript- // Process all status updates in single pass- Object.entries(statusData.entities).forEach(([entityId, data]) => {- this.scheduleUpdate(entityId, data);- });+ <!-- In your location view template -->+ <g class="entity-group" data-entity-id="{{ thermostat.id }}">+ <use href="#icon-thermostat"+ class="entity-svg {{ thermostat.get_status_css_classes|join:' ' }}"+ transform="translate({{ thermostat.position.x }}, {{ thermostat.position.y }})"/>+ </g>```-3. **Reduce Polling Frequency**+5. **Test Status Updates** ([Polling System Implementation](#polling-system-implementation))```javascript- // Increase interval for non-critical entities- const statusPoller = new StatusPoller(10000); // 10 seconds- ```--### Browser Compatibility Issues--**Symptoms**: Status display works in some browsers but not others-**Common Issues**:--1. **CSS Custom Properties (IE/Edge)**- ```css- /* Fallback for older browsers */- .entity-svg.state-active {- fill: #dc3545; /* fallback */- fill: var(--status-active, #dc3545);- }- ```--2. **SVG Styling (Safari)**- ```css- /* Safari sometimes needs explicit SVG styling */- .entity-svg {- -webkit-transform: translateZ(0); /* Force hardware acceleration */- }+ // Verify polling picks up thermostat status changes+ // Check browser Network tab for /api/status requests+ // Manually trigger state change and observe visual update```-3. **Fetch API (IE)**- ```javascript- // Use polyfill or XMLHttpRequest for IE support- if (!window.fetch) {- // Load fetch polyfill or use XMLHttpRequest- }- ```+**Expected Result**: Thermostat icons change color in real-time based on heating/cooling state.## Related Documentation- Status calculation logic: [Domain Guidelines](../domain/domain-guidelines.md#status-display-system)- Style guidelines: [Style Guidelines](style-guidelines.md)- Template conventions: [Template Conventions](template-conventions.md)-- Frontend patterns: [Frontend Guidelines](frontend-guidelines.md)\ No newline at end of file+- Frontend patterns: [Frontend Guidelines](frontend-guidelines.md)diff --git a/docs/dev/frontend/entity-visual-configuration.md b/docs/dev/frontend/entity-visual-configuration.mdindex 6fe6f88c..c26e8091 100644--- a/docs/dev/frontend/entity-visual-configuration.md+++ b/docs/dev/frontend/entity-visual-configuration.md@@ -1,1640 +1,15 @@# Entity Visual Configuration-## Quick Reference--### Common Tasks-- **Add new entity icon** → [Create SVG asset](#create-svg-icon-asset) → Register in `EntityTypesWithIcons`-- **Add new entity path** → [Configure path type](#choose-path-type) → Add to `EntityTypeClosedPaths` or `EntityTypeOpenPaths`-- **Fix icon not showing** → [Check registration](#register-icon-configuration) → Verify enum and icon file match-- **Change entity colors** → [Update style classes](#define-visual-style) → Modify `SvgStatusStyle` properties-- **Test new entity type** → [Visual testing](#testing-visual-configuration) → Create test entity and verify display--### Key Configuration Files-- **Icons**: `hi/apps/entity/templates/entity/svg/type.{TYPE}.svg`-- **Registration**: `hi.hi_styles.EntityStyle.EntityTypesWithIcons`-- **Path Types**: `hi.hi_styles.EntityStyle.EntityTypeClosedPaths/EntityTypeOpenPaths`-- **Styling**: `hi.hi_styles.EntityStyle.PathEntityTypeToSvgStatusStyle`--### Quick Fixes-| Problem | Solution | Location |-|---------|----------|----------|-| Icon not displaying | Check file name matches enum | [Create SVG Asset](#create-svg-icon-asset) |-| Wrong icon size | Verify viewbox registration | [Custom Viewbox](#register-icon-configuration) |-| Path not styling | Check style class assignment | [Define Visual Style](#define-visual-style) |-| Entity not clickable | Add `hi-entity-bg` rectangle | [SVG Icon Requirements](#create-svg-icon-asset) |--### Entity Type Decision Tree-```-New Entity Type-├── Point-like (sensor, device) → Use Icon-│ ├── Create SVG file: type.{enum_name}.svg-│ └── Register in EntityTypesWithIcons-└── Area-like (room, zone) → Use Path- ├── Closed shape → Add to EntityTypeClosedPaths- └── Open line → Add to EntityTypeOpenPaths-```---## Real-World Workflow Examples--### Workflow 1: Adding a New Entity Type with Custom Icon--**Scenario**: Add support for a "Smart Door Lock" entity type with a custom icon and status colors.--**Complete Implementation Process:**--1. **Domain Setup** (Cross-reference: [Entity Patterns](../domain/entity-patterns.md))- ```python- # Add to hi.apps.entity.enums.EntityType- class EntityType(Enum):- # ... existing types- SMART_DOOR_LOCK = ("smart_door_lock", "Smart Door Lock")-- # Add to appropriate group- class EntityGroupType(Enum):- SECURITY_DEVICES = "security_devices"- # Add SMART_DOOR_LOCK to this group- ```--2. **Create Custom SVG Icon** ([Create SVG Icon Asset](#create-svg-icon-asset))--Note: Do **not** use the `<g>` tag inside these SVGs!-- ```xml- <!-- File: hi/apps/entity/templates/entity/svg/type.smart_door_lock.svg -->- <rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>- <!-- Door outline -->- <rect x="20" y="10" width="24" height="44" fill="none" stroke="currentColor" stroke-width="2"/>- <!-- Lock mechanism -->- <circle cx="32" cy="32" r="6" fill="currentColor"/>- <!-- Key hole -->- <circle cx="32" cy="32" r="2" fill="white"/>- <!-- Status indicator (will change color based on state) -->- <circle cx="45" cy="15" r="4" fill="currentColor" opacity="0.8"/>- ```--3. **Register Icon Type** ([Register Icon Configuration](#register-icon-configuration))- ```python- # In hi.hi_styles.EntityStyle.EntityTypesWithIcons- EntityTypesWithIcons = {- EntityType.MOTION_SENSOR,- EntityType.DOOR_SENSOR,- EntityType.SMART_DOOR_LOCK, # Add this line- # ... existing types- }- ```--4. **Define Status-Specific Styling** ([Status Colors](../entity-status-display.md#status-color-system))- ```css- /* Add to your CSS file */- .entity-svg.door-lock-locked {- fill: var(--status-idle); /* Green - secure */- stroke: #006600;- }-- .entity-svg.door-lock-unlocked {- fill: var(--status-recent); /* Orange - caution */- stroke: #cc6600;- }-- .entity-svg.door-lock-jammed {- fill: var(--status-active); /* Red - problem */- stroke: #cc0000;- }-- .entity-svg.door-lock-offline {- fill: var(--status-unknown); /* Gray - unknown */- stroke: #666666;- }- ```--5. **Test Visual Configuration** ([Testing Visual Configuration](#testing-visual-configuration))- ```python- # Create test entity- test_door_lock = Entity.objects.create(- name="Front Door Lock",- entity_type=EntityType.SMART_DOOR_LOCK,- location=test_location- )-- # Create EntityPosition for icon display- EntityPosition.objects.create(- entity=test_door_lock,- x=100, y=150,- scale=1.0, rotation=0- )- ```--6. **Verify in Location View**- - Navigate to location view containing the door lock- - Verify icon displays correctly- - Test status changes trigger color updates- - Check click interactions work (clickable background)--**Expected Result**: Smart door lock appears as custom icon with status-based color changes.-------### Workflow 2: Converting Icon Entity to Path Entity--**Scenario**: Motion sensor needs to represent a coverage area rather than just a point location.--**Migration Process:**--1. **Plan Path Representation** ([Entity Display Methods](#entity-display-methods))- ```python- # Motion sensor coverage area as circular path- # Center: sensor position- # Radius: detection range- coverage_radius = 50 # units in SVG coordinates- center_x, center_y = 200, 300- ```--2. **Remove from Icon Registry** ([Icon Configuration](#register-icon-configuration))- ```python- # Remove from hi.hi_styles.EntityStyle.EntityTypesWithIcons- EntityTypesWithIcons = {- # EntityType.MOTION_SENSOR, # Comment out or remove- EntityType.DOOR_SENSOR,- # ... other types- }- ```--3. **Add to Path Registry** ([Path-Based Configuration](#path-based-entity-configuration))- ```python- # Add to hi.hi_styles.EntityStyle.EntityTypeClosedPaths- EntityTypeClosedPaths = {- EntityType.ROOM,- EntityType.MOTION_SENSOR, # Add this line- # ... existing types- }- ```--4. **Create SVG Path Data** ([SVG Path Requirements](#path-based-entity-configuration))- ```python- import math-- def create_circular_path(center_x, center_y, radius):- """Create SVG path for circular coverage area"""- # Create circle using path commands (more flexible than <circle>)- path_data = (- f"M {center_x - radius} {center_y} "- f"A {radius} {radius} 0 0 1 {center_x + radius} {center_y} "- f"A {radius} {radius} 0 0 1 {center_x - radius} {center_y} "- f"Z"- )- return path_data-- # Update existing motion sensor entities- for motion_sensor in Entity.objects.filter(entity_type=EntityType.MOTION_SENSOR):- # Get current position- position = motion_sensor.entityposition_set.first()- if position:- # Create EntityPath with coverage area- EntityPath.objects.create(- entity=motion_sensor,- svg_path=create_circular_path(position.x, position.y, 50)- )- # Remove EntityPosition- position.delete()- ```--5. **Define Path Styling** ([Define Visual Style](#define-visual-style))- ```python- # Create new style class in hi.hi_styles.EntityStyle- class MotionSensorPathStyle:- default_fill = "#E0E0E0"- default_stroke = "#808080"- default_opacity = 0.3-- active_fill = "#FF4444"- active_stroke = "#CC0000"- active_opacity = 0.6-- recent_fill = "#FF8844"- recent_stroke = "#CC4400"- recent_opacity = 0.5-- idle_fill = "#44FF44"- idle_stroke = "#00CC00"- idle_opacity = 0.3-- # Register the style- PathEntityTypeToSvgStatusStyle = {- EntityType.MOTION_SENSOR: MotionSensorPathStyle,- # ... existing mappings- }- ```--6. **Update Templates** (Cross-reference: [Template Integration](#template-integration))- ```django- <!-- Motion sensors now render as paths instead of icons -->- {% for entity in entities %}- {% if entity.entity_type.name == 'MOTION_SENSOR' %}- <path class="entity-path {{ entity.get_status_css_classes }}"- data-entity-id="{{ entity.id }}"- d="{{ entity.path.svg_path }}"- style="{{ entity.get_path_styling }}"/>- {% elif entity.has_position %}- <!-- Other icon entities -->- <use href="#icon-{{ entity.entity_type.name.lower }}"/>- {% endif %}- {% endfor %}- ```--**Expected Result**: Motion sensors display as coverage areas that show detection zones rather than point icons.-------### Workflow 3: Troubleshooting Icon Registration Issues--**Scenario**: New entity type icon was created and registered, but still shows as placeholder or missing.--**Systematic Debugging:**--1. **Verify File Path and Naming** ([Troubleshooting - Icon Not Displaying](#entity-icon-not-displaying))- ```bash- # Check exact file path and naming- ls hi/apps/entity/templates/entity/svg/type.smart_door_lock.svg-- # Verify enum name matches file name- # EntityType.SMART_DOOR_LOCK → type.smart_door_lock.svg- ```--2. **Check Registration** ([Icon Registration](#register-icon-configuration))- ```python- # Verify in hi.hi_styles.EntityStyle.EntityTypesWithIcons- print(EntityType.SMART_DOOR_LOCK in EntityStyle.EntityTypesWithIcons)- # Should print: True- ```--3. **Validate SVG Content** ([SVG Icon Requirements](#create-svg-icon-asset))- ```xml- <!-- Check file content structure -->- <!-- GOOD: No <svg> wrapper, has clickable background -->- <rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>- <circle cx="32" cy="32" r="20" fill="currentColor"/>-- <!-- BAD: Has <svg> wrapper -->- <svg viewBox="0 0 64 64">- <circle cx="32" cy="32" r="20" fill="currentColor"/>- </svg>- ```--4. **Check Template Symbol Generation** ([Template Integration](#template-integration))- ```django- <!-- Verify symbol is generated in template -->- <defs>- {% for entity_type in entity_types_with_icons %}- <symbol id="icon-{{ entity_type.name.lower }}" viewBox="{{ entity_type.get_viewbox }}">- {% include entity_type.get_icon_template %}- </symbol>- {% endfor %}- </defs>-- <!-- Check in browser dev tools if symbol exists -->- <!-- Should find: <symbol id="icon-smart_door_lock"> -->- ```--5. **Test Direct Icon Usage** ([Testing](#testing-visual-configuration))- ```html- <!-- Test icon directly in browser console -->- <script>- // Check if symbol exists- const symbol = document.querySelector('#icon-smart_door_lock');- console.log('Symbol found:', symbol);-- // Test manual icon usage- const testIcon = document.createElementNS('http://www.w3.org/2000/svg', 'use');- testIcon.setAttribute('href', '#icon-smart_door_lock');- testIcon.setAttribute('class', 'entity-svg');- document.querySelector('svg').appendChild(testIcon);- </script>- ```--6. **Check ViewBox Issues** ([Custom ViewBox](#register-icon-configuration))- ```python- # If icon appears but wrong size, check viewbox- # Add custom viewbox if needed- EntityTypeToIconViewbox = {- EntityType.SMART_DOOR_LOCK: "0 0 80 80", # If icon designed differently- }- ```--**Common Resolutions**:-- File name doesn't match enum (case sensitivity)-- SVG has `<svg>` wrapper (remove it)-- Missing clickable background rectangle-- Not registered in `EntityTypesWithIcons`-------### Workflow 4: Creating Entity Type Family with Consistent Styling--**Scenario**: Create multiple related security device types (door lock, window sensor, security camera) with consistent visual styling.--**Coordinated Implementation:**--1. **Design Visual Family** ([Visual Asset Guidelines](#visual-asset-guidelines))- ```css- /* Define consistent family styling */- .security-device {- stroke-width: 2;- stroke: #333333;- }-- .security-device.state-secure {- fill: #28a745; /* Green family */- }-- .security-device.state-alert {- fill: #dc3545; /* Red family */- }-- .security-device.state-warning {- fill: #ffc107; /* Yellow family */- }- ```--2. **Create Icon Family** ([SVG Icon Standards](#visual-asset-guidelines))- ```xml- <!-- Common 64x64 viewbox, similar design elements -->-- <!-- type.door_lock.svg -->- <rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>- <rect x="20" y="15" width="24" height="34" fill="none" stroke="currentColor" stroke-width="2"/>- <circle cx="32" cy="32" r="4" fill="currentColor"/>-- <!-- type.window_sensor.svg -->- <rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>- <rect x="15" y="20" width="34" height="24" fill="none" stroke="currentColor" stroke-width="2"/>- <rect x="18" y="23" width="28" height="18" fill="currentColor" opacity="0.3"/>-- <!-- type.security_camera.svg -->- <rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>- <rect x="20" y="25" width="24" height="16" rx="4" fill="currentColor"/>- <circle cx="44" cy="33" r="8" fill="none" stroke="currentColor" stroke-width="2"/>- ```--3. **Register All Types** ([Batch Registration](#register-icon-configuration))- ```python- # Add all security devices to icons- EntityTypesWithIcons = {- # ... existing types- EntityType.DOOR_LOCK,- EntityType.WINDOW_SENSOR,- EntityType.SECURITY_CAMERA,- # ... other types- }- ```--4. **Apply Family CSS Classes** ([CSS Class Application](../entity-status-display.md#css-class-mapping))- ```python- # In status calculation logic- def get_security_device_classes(entity):- base_classes = ['security-device']-- if entity.entity_type in [EntityType.DOOR_LOCK, EntityType.WINDOW_SENSOR]:- state = entity.get_current_state('security_state')- if state and state.value == 'secure':- base_classes.append('state-secure')- elif state and state.value == 'breached':- base_classes.append('state-alert')- else:- base_classes.append('state-warning')-- return base_classes- ```--5. **Test Family Consistency** ([Visual Testing](#testing-visual-configuration))- ```python- # Create test entities for all family members- security_devices = [- ('Front Door Lock', EntityType.DOOR_LOCK),- ('Living Room Window', EntityType.WINDOW_SENSOR),- ('Driveway Camera', EntityType.SECURITY_CAMERA),- ]-- for name, entity_type in security_devices:- test_entity = Entity.objects.create(- name=name,- entity_type=entity_type,- location=test_location- )- # Test all status states for visual consistency- ```--**Expected Result**: All security devices have cohesive visual design with consistent status colors and styling patterns.--## Common Patterns Library--### Standard Entity Icon Templates--#### Basic Icon SVG Structure-```xml-<!-- Standard template for entity type icons -->-<!-- File: hi/apps/entity/templates/entity/svg/type.{TYPE_NAME}.svg -->-<rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>-<!-- Entity-specific icon content here -->-<circle cx="32" cy="32" r="20" fill="currentColor"/>-<!-- Optional status indicator -->-<circle cx="50" cy="14" r="6" fill="currentColor" opacity="0.8"/>-```--#### Icon Family Consistency Pattern-```xml-<!-- Motion sensor icon -->-<rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>-<circle cx="32" cy="32" r="18" fill="currentColor"/>-<path d="M20,32 L32,20 L44,32 L32,44 Z" fill="white" opacity="0.8"/>--<!-- Door sensor icon -->-<rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>-<rect x="22" y="16" width="20" height="32" fill="none" stroke="currentColor" stroke-width="2"/>-<circle cx="36" cy="32" r="3" fill="currentColor"/>--<!-- Window sensor icon -->-<rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>-<rect x="16" y="22" width="32" height="20" fill="none" stroke="currentColor" stroke-width="2"/>-<rect x="19" y="25" width="26" height="14" fill="currentColor" opacity="0.3"/>-```--#### Status-Aware Icon Variants-```xml-<!-- Base thermostat icon -->-<rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>-<circle cx="32" cy="32" r="20" fill="none" stroke="currentColor" stroke-width="3"/>-<circle cx="32" cy="32" r="12" fill="currentColor"/>-<!-- Temperature display area -->-<text x="32" y="36" text-anchor="middle" fill="white" font-size="8">72°</text>--<!-- Heating indicator (conditional element) -->-<g class="heating-indicator">- <path d="M32,15 L35,20 L29,20 Z" fill="#ff4444"/>-</g>--<!-- Cooling indicator (conditional element) -->-<g class="cooling-indicator">- <path d="M32,49 L35,44 L29,44 Z" fill="#4444ff"/>-</g>-```--### Standard Entity Configuration Patterns--#### Icon Registration Pattern-```python-# Standard pattern for registering icon entity types-# In hi.hi_styles.EntityStyle--EntityTypesWithIcons = {- # Security devices family- EntityType.MOTION_SENSOR,- EntityType.DOOR_SENSOR,- EntityType.WINDOW_SENSOR,- EntityType.SECURITY_CAMERA,-- # Climate control family- EntityType.TEMPERATURE_SENSOR,- EntityType.THERMOSTAT,- EntityType.HUMIDITY_SENSOR,-- # Lighting family- EntityType.LIGHT_SWITCH,- EntityType.DIMMER_SWITCH,- EntityType.SMART_BULB,-- # Add new entity types here following family grouping-}--# Custom viewboxes for non-standard icons-EntityTypeToIconViewbox = {- EntityType.WIDE_SENSOR: "0 0 100 50", # Wide rectangular sensor- EntityType.TALL_SENSOR: "0 0 40 80", # Tall vertical sensor- EntityType.DETAILED_CAMERA: "0 0 80 60", # More detailed camera icon-}-```--#### Path Registration Pattern-```python-# Standard pattern for registering path entity types-# In hi.hi_styles.EntityStyle--# Closed paths (filled areas)-EntityTypeClosedPaths = {- # Room and zone types- EntityType.ROOM,- EntityType.ZONE,- EntityType.COVERAGE_AREA,-- # Detection/sensor coverage areas- EntityType.MOTION_DETECTION_ZONE,- EntityType.SECURITY_PERIMETER,-- # Add new area-based entity types here-}--# Open paths (lines and curves)-EntityTypeOpenPaths = {- # Boundary and connection types- EntityType.BOUNDARY_LINE,- EntityType.CORRIDOR,- EntityType.FENCE_LINE,-- # Connection paths- EntityType.CABLE_RUN,- EntityType.PIPE_LINE,-- # Add new line-based entity types here-}-```--#### Visual Style Mapping Pattern-```python-# Standard pattern for mapping entity types to visual styles-# In hi.hi_styles.EntityStyle--PathEntityTypeToSvgStatusStyle = {- # Security areas- EntityType.SECURITY_PERIMETER: SecurityPerimeterStyle,- EntityType.MOTION_DETECTION_ZONE: MotionZoneStyle,-- # Climate zones- EntityType.HVAC_ZONE: HvacZoneStyle,- EntityType.TEMPERATURE_ZONE: TemperatureZoneStyle,-- # Room types- EntityType.ROOM: RoomStyle,- EntityType.BATHROOM: BathroomStyle,- EntityType.BEDROOM: BedroomStyle,-}--# Standard size overrides-EntityTypePathInitialRadius = {- EntityType.SMALL_SENSOR_COVERAGE: 15.0,- EntityType.ROOM: 30.0,- EntityType.LARGE_DETECTION_ZONE: 50.0,-}-```--### Standard Visual Style Classes--#### Basic SVG Status Style Template-```python-# Standard template for SVG status style classes-class StandardSvgStatusStyle:- """Base template for entity visual styling"""-- # Default styling (idle/unknown state)- default_fill = "#E0E0E0"- default_stroke = "#808080"- default_stroke_width = "2"- default_opacity = "0.6"-- # Active state styling- active_fill = "#DC3545"- active_stroke = "#B02A37"- active_stroke_width = "3"- active_opacity = "0.9"-- # Recent activity styling- recent_fill = "#FD7E14"- recent_stroke = "#CC6200"- recent_stroke_width = "2"- recent_opacity = "0.7"-- # Past activity styling- past_fill = "#FFC107"- past_stroke = "#CC9A00"- past_stroke_width = "2"- past_opacity = "0.5"-- # Idle/safe state styling- idle_fill = "#28A745"- idle_stroke = "#1E7E34"- idle_stroke_width = "2"- idle_opacity = "0.4"--# Security-specific styling-class SecurityDeviceStyle(StandardSvgStatusStyle):- """Visual styling for security devices"""-- # Override for security-specific colors- active_fill = "#FF0000" # Bright red for security alerts- active_opacity = "1.0" # Full opacity for alerts-- idle_fill = "#00AA00" # Green for secure state- idle_opacity = "0.6"--# Climate-specific styling-class ClimateDeviceStyle(StandardSvgStatusStyle):- """Visual styling for climate control devices"""-- # Climate-specific state colors- heating_fill = "#FF4444"- heating_stroke = "#CC0000"-- cooling_fill = "#4444FF"- cooling_stroke = "#0000CC"-- idle_fill = "#44AA44" # Green for idle HVAC-```--### Standard Template Integration Patterns--#### Icon Entity Template Pattern-```django-<!-- Standard template for icon-based entities in location views -->-<defs>- {% for entity_type in entity_types_with_icons %}- <symbol id="icon-{{ entity_type.name.lower }}"- viewBox="{{ entity_type.get_viewbox }}">- {% include entity_type.get_icon_template %}- </symbol>- {% endfor %}-</defs>--<!-- Entity rendering loop -->-{% for entity in positioned_entities %}- <g class="entity-group" data-entity-id="{{ entity.id }}"- data-entity-type="{{ entity.entity_type.name.lower }}">- <use href="#icon-{{ entity.entity_type.name.lower }}"- class="entity-svg {{ entity.get_status_css_classes|join:' ' }}"- transform="translate({{ entity.position.x }}, {{ entity.position.y }})- scale({{ entity.position.scale|default:1.0 }})- rotate({{ entity.position.rotation|default:0 }})"/>- <!-- Optional entity label -->- {% if entity.show_label %}- <text x="{{ entity.position.x }}"- y="{{ entity.position.y|add:25 }}"- class="entity-label">{{ entity.name }}</text>- {% endif %}- </g>-{% endfor %}-```--#### Path Entity Template Pattern-```django-<!-- Standard template for path-based entities -->-{% for entity in path_entities %}- <g class="entity-group" data-entity-id="{{ entity.id }}"- data-entity-type="{{ entity.entity_type.name.lower }}">- <path class="entity-path {{ entity.get_status_css_classes|join:' ' }}"- d="{{ entity.path.svg_path }}"- style="fill: {{ entity.get_status_fill }};- stroke: {{ entity.get_status_stroke }};- stroke-width: {{ entity.get_status_stroke_width }};- opacity: {{ entity.get_status_opacity }}"/>- <!-- Optional path label at centroid -->- {% if entity.show_label %}- <text x="{{ entity.path.centroid_x }}"- y="{{ entity.path.centroid_y }}"- class="entity-label path-label">{{ entity.name }}</text>- {% endif %}- </g>-{% endfor %}-```--#### Entity Collection Template Pattern-```django-<!-- Standard template for entity collections/groups -->-<div class="entity-collection" data-collection-id="{{ collection.id }}">- <h4 class="collection-title">{{ collection.name }}</h4>- <div class="entity-grid">- {% for entity in collection.entities %}- <div class="entity-card" data-entity-id="{{ entity.id }}">- <div class="entity-icon-container">- {% if entity.has_position %}- <svg viewBox="0 0 64 64" class="entity-card-icon">- <use href="#icon-{{ entity.entity_type.name.lower }}"- class="entity-svg {{ entity.get_status_css_classes|join:' ' }}"/>- </svg>- {% else %}- <div class="entity-placeholder {{ entity.get_status_css_classes|join:' ' }}">- {{ entity.entity_type.display_name|first }}- </div>- {% endif %}- </div>- <div class="entity-info">- <span class="entity-name">{{ entity.name }}</span>- <span class="entity-status">{{ entity.get_display_state }}</span>- </div>- </div>- {% endfor %}- </div>-</div>-```--### Standard Testing Patterns for Visual Configuration--#### Icon Registration Testing Pattern-```python-# Standard test pattern for icon registration-class IconRegistrationTestCase(TestCase):- def test_entity_type_icon_registration(self):- """Test that entity type is properly registered for icon display"""- entity_type = EntityType.MOTION_SENSOR-- # Verify type is in icon registry- self.assertIn(entity_type, EntityStyle.EntityTypesWithIcons)-- # Verify icon template file exists- icon_template_path = entity_type.get_icon_template_path()- self.assertTrue(os.path.exists(icon_template_path))-- # Verify viewbox is defined- viewbox = entity_type.get_viewbox()- self.assertIsNotNone(viewbox)- self.assertRegex(viewbox, r'\d+ \d+ \d+ \d+') # "x y width height" format-- def test_icon_svg_content_requirements(self):- """Test that icon SVG meets requirements"""- entity_type = EntityType.MOTION_SENSOR- svg_content = entity_type.get_icon_svg_content()-- # Must have clickable background- self.assertIn('class="hi-entity-bg"', svg_content)-- # Should not have wrapping <svg> element- self.assertNotIn('<svg', svg_content)-- # Should use currentColor for primary elements- self.assertIn('currentColor', svg_content)-```--#### Path Configuration Testing Pattern-```python-# Standard test pattern for path configuration-class PathConfigurationTestCase(TestCase):- def test_path_entity_type_registration(self):- """Test that path entity type is properly configured"""- entity_type = EntityType.ROOM-- # Verify type is in appropriate path registry- is_closed = entity_type in EntityStyle.EntityTypeClosedPaths- is_open = entity_type in EntityStyle.EntityTypeOpenPaths- self.assertTrue(is_closed or is_open, f"{entity_type} not in any path registry")-- # Verify style is assigned- self.assertIn(entity_type, EntityStyle.PathEntityTypeToSvgStatusStyle)-- # Verify style class exists and has required properties- style_class = EntityStyle.PathEntityTypeToSvgStatusStyle[entity_type]- self.assertTrue(hasattr(style_class, 'default_fill'))- self.assertTrue(hasattr(style_class, 'active_fill'))-- def test_path_entity_creation_and_display(self):- """Test creating and displaying path entities"""- room = Entity.objects.create(- name='Test Room',- entity_type=EntityType.ROOM,- location=self.test_location- )-- # Create path data- path_data = "M10,10 L50,10 L50,50 L10,50 Z" # Simple rectangle- EntityPath.objects.create(- entity=room,- svg_path=path_data- )-- # Verify entity can provide display data- css_classes = room.get_status_css_classes()- self.assertIsInstance(css_classes, list)-- fill_color = room.get_status_fill()- self.assertIsInstance(fill_color, str)- self.assertRegex(fill_color, r'^#[0-9A-Fa-f]{6}$') # Valid hex color-```--#### Visual Style Testing Pattern-```python-# Standard test pattern for visual style classes-class VisualStyleTestCase(TestCase):- def test_style_class_completeness(self):- """Test that style class defines all required properties"""- style_class = SecurityDeviceStyle-- required_properties = [- 'default_fill', 'default_stroke', 'default_opacity',- 'active_fill', 'active_stroke', 'active_opacity',- 'idle_fill', 'idle_stroke', 'idle_opacity'- ]-- for prop in required_properties:- self.assertTrue(hasattr(style_class, prop),- f"Style class missing property: {prop}")-- def test_color_format_validation(self):- """Test that style colors are valid hex format"""- style_class = SecurityDeviceStyle-- color_properties = ['default_fill', 'active_fill', 'idle_fill']- for prop in color_properties:- color_value = getattr(style_class, prop)- self.assertRegex(color_value, r'^#[0-9A-Fa-f]{6}$',- f"Invalid color format in {prop}: {color_value}")-```--#### JavaScript Testing Pattern for Entity Configuration-```javascript-// Standard pattern for testing entity visual configuration-function testEntityVisualConfiguration() {- // Test icon symbol generation- const iconSymbol = document.querySelector('#icon-motion-sensor');- console.assert(iconSymbol !== null, 'Icon symbol not generated');- console.assert(iconSymbol.getAttribute('viewBox') === '0 0 64 64',- 'Incorrect viewBox');-- // Test entity element creation- const testEntityHtml = `- <g data-entity-id="test-123" data-entity-type="motion-sensor">- <use href="#icon-motion-sensor" class="entity-svg state-idle"/>- </g>- `;- document.querySelector('svg').innerHTML += testEntityHtml;-- // Test CSS class application- const entityElement = document.querySelector('[data-entity-id="test-123"] use');- console.assert(entityElement.classList.contains('entity-svg'),- 'Base entity class missing');- console.assert(entityElement.classList.contains('state-idle'),- 'Status class missing');-- // Test visual style application- const computedStyle = window.getComputedStyle(entityElement);- const fillColor = computedStyle.fill;- console.assert(fillColor !== '', 'Fill color not applied');-- console.log('Entity visual configuration test passed');-}-```--### Standard Maintenance Patterns--#### Icon File Organization Pattern-```-hi/apps/entity/templates/entity/svg/-├── families/-│ ├── security/-│ │ ├── type.motion_sensor.svg-│ │ ├── type.door_sensor.svg-│ │ └── type.security_camera.svg-│ ├── climate/-│ │ ├── type.thermostat.svg-│ │ └── type.temperature_sensor.svg-│ └── lighting/-│ ├── type.light_switch.svg-│ └── type.dimmer_switch.svg-└── deprecated/- └── old_icon_files_kept_for_reference.svg-```--#### Configuration Review Checklist-```python-# Standard checklist for reviewing entity visual configuration-"""-Entity Visual Configuration Review Checklist:--□ Icon File Requirements:- - SVG file exists in correct location- - No <svg> wrapper element- - Contains hi-entity-bg rectangle for clickability- - Uses currentColor for status-responsive elements- - Follows 64x64 viewBox standard (or custom viewBox registered)--□ Registration Requirements:- - EntityType added to appropriate registry (Icons vs Paths)- - Style class assigned in PathEntityTypeToSvgStatusStyle (for paths)- - Custom viewBox registered if needed--□ Style Requirements:- - Style class defines all required state properties- - Colors use valid hex format- - Opacity values are between 0.0 and 1.0- - Stroke widths are reasonable (1-4 typical)--□ Template Integration:- - Entity appears in location views- - Status changes trigger visual updates- - CSS classes apply correctly- - Cross-browser compatibility verified--□ Testing Requirements:- - Tests cover registration- - Visual tests verify appearance- - Status change tests verify dynamic updates- - Error cases handled gracefully-"""-```--## Performance Optimization Guide--### Overview--Entity visual configuration can significantly impact rendering performance, especially with many entity types, complex SVG icons, or large-scale deployments. This guide provides optimization strategies for efficient entity visual management.--### SVG Icon Performance Optimization--#### Icon Complexity Management-```xml-<!-- EFFICIENT: Simple geometric shapes -->-<rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>-<circle cx="32" cy="32" r="20" fill="currentColor"/>-<rect x="28" y="28" width="8" height="8" fill="white"/>--<!-- INEFFICIENT: Complex path with many points -->-<rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>-<path d="M32,10 L35,15 L40,15 L37,20 L38,25 L32,23 L26,25 L27,20 L24,15 L29,15 Z" fill="currentColor"/>-<path d="M20,30 Q25,25 30,30 Q35,35 40,30 Q45,25 50,30" fill="none" stroke="currentColor"/>-```--#### SVG Optimization Pipeline-```javascript-// Automated SVG optimization during build-class SvgIconOptimizer {- constructor(options = {}) {- this.options = {- removeUnusedDefs: true,- simplifyPaths: true,- mergeShapes: true,- removeComments: true,- minifyCoordinates: true,- ...options- };- }-- optimizeSvgContent(svgString) {- let optimized = svgString;-- if (this.options.removeComments) {- optimized = this.removeComments(optimized);- }-- if (this.options.simplifyPaths) {- optimized = this.simplifyPaths(optimized);- }-- if (this.options.minifyCoordinates) {- optimized = this.minifyCoordinates(optimized);- }-- return optimized;- }-- removeComments(svg) {- return svg.replace(/<!--[\s\S]*?-->/g, '');- }-- simplifyPaths(svg) {- // Convert complex paths to simpler equivalents- return svg.replace(/(<path[^>]*d=")([^"]+)(")/g, (match, start, pathData, end) => {- const simplified = this.simplifyPathData(pathData);- return start + simplified + end;- });- }-- simplifyPathData(pathData) {- // Remove unnecessary precision- return pathData.replace(/(\d+\.\d{3,})/g, (match, num) => {- return parseFloat(num).toFixed(2);- });- }-- minifyCoordinates(svg) {- // Round coordinates to reduce file size- return svg.replace(/(\d+\.\d{2,})/g, (match, coord) => {- return Math.round(parseFloat(coord) * 100) / 100;- });- }-}-```--#### Icon Caching Strategy-```javascript-// Efficient icon loading and caching-class IconCacheManager {- constructor() {- this.iconCache = new Map();- this.preloadQueue = [];- this.isPreloading = false;- }-- async preloadIcons(iconTypes) {- this.preloadQueue.push(...iconTypes);-- if (!this.isPreloading) {- this.processPreloadQueue();- }- }-- async processPreloadQueue() {- this.isPreloading = true;-- while (this.preloadQueue.length > 0) {- const iconType = this.preloadQueue.shift();-- if (!this.iconCache.has(iconType)) {- try {- const iconContent = await this.loadIconContent(iconType);- this.iconCache.set(iconType, iconContent);- } catch (error) {- console.warn(`Failed to preload icon ${iconType}:`, error);- }- }-- // Yield control to prevent blocking- await new Promise(resolve => setTimeout(resolve, 0));- }-- this.isPreloading = false;- }-- async loadIconContent(iconType) {- const iconPath = `/static/entity/svg/type.${iconType.toLowerCase()}.svg`;- const response = await fetch(iconPath);-- if (!response.ok) {- throw new Error(`Failed to load icon: ${response.status}`);- }-- return await response.text();- }-- getIcon(iconType) {- return this.iconCache.get(iconType);- }-- // Lazy load icons on demand with memory limits- async ensureIconLoaded(iconType, priority = 'normal') {- if (this.iconCache.has(iconType)) {- return this.iconCache.get(iconType);- }-- // Manage cache size- if (this.iconCache.size >= 100) {- this.evictLeastRecentlyUsed();- }-- const iconContent = await this.loadIconContent(iconType);- this.iconCache.set(iconType, {- content: iconContent,- lastUsed: Date.now(),- priority- });-- return iconContent;- }-- evictLeastRecentlyUsed() {- let oldestTime = Date.now();- let oldestKey = null;-- for (const [key, value] of this.iconCache) {- if (value.priority !== 'high' && value.lastUsed < oldestTime) {- oldestTime = value.lastUsed;- oldestKey = key;- }- }-- if (oldestKey) {- this.iconCache.delete(oldestKey);- }- }-}-```--### Registration and Configuration Performance--#### Lazy Registration Pattern-```python-# Optimize entity type registration for large numbers of types-class LazyEntityTypeRegistry:- """Lazy-load entity type configurations to improve startup performance"""-- def __init__(self):- self._icon_registry = None- self._path_registry = None- self._style_registry = None- self._viewbox_registry = None-- @property- def entity_types_with_icons(self):- if self._icon_registry is None:- self._icon_registry = self._build_icon_registry()- return self._icon_registry-- @property- def entity_type_closed_paths(self):- if self._path_registry is None:- self._path_registry = self._build_path_registry()- return self._path_registry-- def _build_icon_registry(self):- """Build icon registry on first access"""- icon_types = set()-- # Load from configuration files or database- # This allows for dynamic entity type registration- icon_config = self.load_icon_configuration()-- for entity_type_name in icon_config:- try:- entity_type = EntityType[entity_type_name]- icon_types.add(entity_type)- except KeyError:- logger.warning(f"Unknown entity type in icon config: {entity_type_name}")-- return icon_types-- def load_icon_configuration(self):- """Load icon configuration from external source"""- # Can be loaded from JSON, database, or environment- return getattr(settings, 'ENTITY_ICON_TYPES', DEFAULT_ICON_TYPES)-```--#### Batch Configuration Updates-```python-# Efficient bulk configuration changes-class EntityConfigurationBatcher:- """Batch entity configuration changes for better performance"""-- def __init__(self):- self.pending_icon_registrations = set()- self.pending_path_registrations = set()- self.pending_style_updates = {}- self.batch_size = 50-- def add_icon_registration(self, entity_type):- self.pending_icon_registrations.add(entity_type)-- if len(self.pending_icon_registrations) >= self.batch_size:- self.flush_icon_registrations()-- def add_path_registration(self, entity_type, path_type):- self.pending_path_registrations.add((entity_type, path_type))-- if len(self.pending_path_registrations) >= self.batch_size:- self.flush_path_registrations()-- def flush_icon_registrations(self):- """Apply all pending icon registrations at once"""- if not self.pending_icon_registrations:- return-- # Update registry in single operation- EntityStyle.EntityTypesWithIcons.update(self.pending_icon_registrations)-- # Clear template caches that depend on icon registry- self.clear_related_caches(['entity_icon_symbols', 'location_view_templates'])-- self.pending_icon_registrations.clear()-- def flush_all(self):- """Flush all pending configuration changes"""- self.flush_icon_registrations()- self.flush_path_registrations()- self.flush_style_updates()-- def clear_related_caches(self, cache_keys):- """Clear Django template and view caches"""- from django.core.cache import cache- for key in cache_keys:- cache.delete_many(cache.get_many([f"{key}:*"]))-```--### Template Rendering Optimization--#### Template Fragment Caching-```django-<!-- Cache expensive template fragments -->-{% load cache %}--<!-- Cache entity symbol definitions -->-{% cache 3600 entity_symbols entity_types_hash %}-<defs>- {% for entity_type in entity_types_with_icons %}- <symbol id="icon-{{ entity_type.name.lower }}"- viewBox="{{ entity_type.get_viewbox }}">- {% include entity_type.get_icon_template %}- </symbol>- {% endfor %}-</defs>-{% endcache %}--<!-- Cache per-entity-type rendering -->-{% for entity in positioned_entities %}- {% cache 300 entity_rendering entity.id entity.last_modified entity_type_version %}- <g class="entity-group" data-entity-id="{{ entity.id }}">- <use href="#icon-{{ entity.entity_type.name.lower }}"- class="entity-svg {{ entity.get_status_css_classes|join:' ' }}"- transform="{{ entity.get_transform_string }}"/>- </g>- {% endcache %}-{% endfor %}-```--#### Conditional Template Loading-```python-# Load templates conditionally based on entity types present-class OptimizedLocationViewMixin:- def get_context_data(self, **kwargs):- context = super().get_context_data(**kwargs)-- # Only load entity types that are actually used in this location- present_entity_types = self.get_present_entity_types()- context['entity_types_with_icons'] = [- et for et in EntityStyle.EntityTypesWithIcons- if et in present_entity_types- ]-- # Pre-calculate expensive template data- context['entity_transforms'] = self.precalculate_transforms()- context['entity_type_hash'] = self.get_entity_types_cache_key()-- return context-- def get_present_entity_types(self):- """Get only entity types that exist in current location"""- return set(- Entity.objects- .filter(location=self.object)- .values_list('entity_type', flat=True)- .distinct()- )-- def precalculate_transforms(self):- """Pre-calculate transform strings to avoid template computation"""- transforms = {}- for entity in self.get_positioned_entities():- transforms[entity.id] = entity.get_transform_string()- return transforms-```--### CSS Performance for Visual Configuration--#### CSS Custom Properties Optimization-```css-/* Efficient CSS custom property usage */-:root {- /* Define base colors once */- --entity-base-active: #dc3545;- --entity-base-idle: #28a745;- --entity-base-unknown: #6c757d;-- /* Derive variations using calc() */- --entity-active-light: color-mix(in srgb, var(--entity-base-active) 80%, white);- --entity-active-dark: color-mix(in srgb, var(--entity-base-active) 80%, black);-}--/* Use efficient selectors for entity styling */-[data-entity-type="motion_sensor"] {- --entity-color: var(--entity-base-active);- --entity-stroke: var(--entity-active-dark);-}--[data-entity-type="door_sensor"] {- --entity-color: var(--entity-base-idle);- --entity-stroke: var(--entity-active-dark);-}--/* Apply colors using custom properties */-.entity-svg {- fill: var(--entity-color);- stroke: var(--entity-stroke);-}-```--#### Critical CSS for Entity Display-```css-/* Critical CSS - load first for entity display */-.entity-svg, .entity-path {- /* Essential properties only */- fill: currentColor;- stroke: currentColor;- cursor: pointer;-}--.entity-group {- /* Minimal base styling */- pointer-events: all;-}--/* Non-critical styling - can be loaded later */-@media (min-width: 768px) {- .entity-svg:hover {- filter: brightness(1.1);- transform: scale(1.05);- transition: all 0.2s ease;- }-}-```--### Browser Performance Optimization--#### Feature Detection and Polyfills-```javascript-// Conditional feature loading based on browser capabilities-class BrowserOptimizedEntityRenderer {- constructor() {- this.capabilities = this.detectCapabilities();- this.loadOptimalStrategies();- }-- detectCapabilities() {- return {- hasIntersectionObserver: 'IntersectionObserver' in window,- hasResizeObserver: 'ResizeObserver' in window,- supportsCustomElements: 'customElements' in window,- supportsCSSSCustomProperties: CSS.supports('--test', 'test'),- hasRequestIdleCallback: 'requestIdleCallback' in window,- memoryInfo: navigator.memory || { usedJSHeapSize: 50 * 1024 * 1024 },- hardwareConcurrency: navigator.hardwareConcurrency || 4- };- }-- loadOptimalStrategies() {- if (this.capabilities.hasIntersectionObserver) {- this.useIntersectionBasedRendering();- } else {- this.useScrollBasedRendering();- }-- if (this.capabilities.hasRequestIdleCallback) {- this.useIdleTimeProcessing();- } else {- this.useTimeSlicedProcessing();- }-- // Adjust strategies based on device memory- if (this.capabilities.memoryInfo.usedJSHeapSize > 100 * 1024 * 1024) {- this.enableMemoryConservationMode();- }- }-- useIntersectionBasedRendering() {- const observer = new IntersectionObserver((entries) => {- entries.forEach(entry => {- const entityId = entry.target.getAttribute('data-entity-id');- if (entry.isIntersecting) {- this.enableEntityRendering(entityId);- } else {- this.disableEntityRendering(entityId);- }- });- }, {- rootMargin: '50px',- threshold: 0.1- });-- document.querySelectorAll('[data-entity-id]').forEach(el => {- observer.observe(el);- });- }-- useIdleTimeProcessing() {- const processQueue = (deadline) => {- while (deadline.timeRemaining() > 0 && this.processingQueue.length > 0) {- const task = this.processingQueue.shift();- task();- }-- if (this.processingQueue.length > 0) {- requestIdleCallback(processQueue);- }- };-- requestIdleCallback(processQueue);- }-- enableMemoryConservationMode() {- // Reduce icon cache size- this.maxIconCacheSize = 25;-- // Use simplified rendering for non-critical entities- this.useSimplifiedRendering = true;-- // Disable expensive visual effects- this.disableVisualEffects = true;- }-}-```--### Testing Performance Optimizations--#### Performance Testing Framework-```javascript-// Automated performance testing for entity configurations-class EntityPerformanceTester {- constructor(testConfig = {}) {- this.config = {- maxEntityCount: 1000,- testDuration: 30000, // 30 seconds- acceptableFrameTime: 16, // 60 FPS- ...testConfig- };- this.results = {};- }-- async runEntityLoadTest(entityCount) {- console.log(`Starting entity load test with ${entityCount} entities`);-- const startTime = performance.now();- const frameTimes = [];-- // Create test entities- const testEntities = this.createTestEntities(entityCount);-- // Measure rendering performance- const measureFrame = () => {- const frameStart = performance.now();-- // Simulate entity updates- testEntities.forEach(entity => {- this.updateEntityVisuals(entity);- });-- const frameEnd = performance.now();- frameTimes.push(frameEnd - frameStart);-- if (frameEnd - startTime < this.config.testDuration) {- requestAnimationFrame(measureFrame);- } else {- this.analyzeResults(frameTimes, entityCount);- }- };-- requestAnimationFrame(measureFrame);- }-- createTestEntities(count) {- const entities = [];- const entityTypes = ['motion_sensor', 'door_sensor', 'temperature_sensor'];-- for (let i = 0; i < count; i++) {- const entityType = entityTypes[i % entityTypes.length];- const entity = {- id: `test-entity-${i}`,- type: entityType,- x: Math.random() * 1000,- y: Math.random() * 1000,- status: Math.random() > 0.5 ? 'active' : 'idle'- };- entities.push(entity);- }-- return entities;- }-- updateEntityVisuals(entity) {- const element = document.querySelector(`[data-entity-id="${entity.id}"]`);- if (element) {- element.classList.toggle('state-active', entity.status === 'active');- element.classList.toggle('state-idle', entity.status === 'idle');- }- }-- analyzeResults(frameTimes, entityCount) {- const avgFrameTime = frameTimes.reduce((a, b) => a + b, 0) / frameTimes.length;- const maxFrameTime = Math.max(...frameTimes);- const slowFrames = frameTimes.filter(t => t > this.config.acceptableFrameTime).length;- const slowFramePercentage = (slowFrames / frameTimes.length) * 100;-- const result = {- entityCount,- averageFrameTime: avgFrameTime.toFixed(2),- maxFrameTime: maxFrameTime.toFixed(2),- slowFramePercentage: slowFramePercentage.toFixed(1),- acceptable: slowFramePercentage < 10 // Less than 10% slow frames- };-- this.results[entityCount] = result;- console.log('Performance test results:', result);-- return result;- }-- async runComprehensiveTest() {- const testSizes = [50, 100, 250, 500, 750, 1000];-- for (const size of testSizes) {- await this.runEntityLoadTest(size);-- // Wait between tests- await new Promise(resolve => setTimeout(resolve, 2000));- }-- this.generatePerformanceReport();- }-- generatePerformanceReport() {- console.log('\n=== Entity Performance Report ===');- Object.values(this.results).forEach(result => {- const status = result.acceptable ? '✅ PASS' : '❌ FAIL';- console.log(`${status} ${result.entityCount} entities: ${result.averageFrameTime}ms avg, ${result.slowFramePercentage}% slow frames`);- });-- // Find performance breakpoint- const breakpoint = this.findPerformanceBreakpoint();- if (breakpoint) {- console.log(`\n⚠️ Performance degradation detected at ${breakpoint} entities`);- }- }-- findPerformanceBreakpoint() {- const results = Object.values(this.results);- for (let i = 0; i < results.length - 1; i++) {- if (results[i].acceptable && !results[i + 1].acceptable) {- return results[i + 1].entityCount;- }- }- return null;- }-}-```--### Memory Management for Entity Configurations--#### Resource Cleanup Patterns-```javascript-// Proper cleanup to prevent memory leaks-class EntityConfigurationManager {- constructor() {- this.iconElements = new Map();- this.styleSheets = new Map();- this.eventListeners = new WeakMap();- this.cleanupTasks = [];- }-- registerEntity(entityId, entityType) {- // Create icon elements- const iconElement = this.createIconElement(entityType);- this.iconElements.set(entityId, iconElement);-- // Add cleanup task- this.cleanupTasks.push(() => {- this.iconElements.delete(entityId);- this.removeEntityEventListeners(entityId);- });- }-- unregisterEntity(entityId) {- // Clean up icon element- const iconElement = this.iconElements.get(entityId);- if (iconElement && iconElement.parentNode) {- iconElement.parentNode.removeChild(iconElement);- }-- this.iconElements.delete(entityId);- this.removeEntityEventListeners(entityId);- }-- cleanup() {- // Run all cleanup tasks- this.cleanupTasks.forEach(task => {- try {- task();- } catch (error) {- console.warn('Cleanup task failed:', error);- }- });-- this.cleanupTasks = [];- this.iconElements.clear();- this.styleSheets.clear();- }-- // Automatic cleanup on page unload- setupAutoCleanup() {- window.addEventListener('beforeunload', () => {- this.cleanup();- });-- // Clean up periodically- setInterval(() => {- this.performPeriodicCleanup();- }, 60000); // Every minute- }-- performPeriodicCleanup() {- // Remove references to non-existent entities- const existingEntityIds = new Set();- document.querySelectorAll('[data-entity-id]').forEach(el => {- existingEntityIds.add(el.getAttribute('data-entity-id'));- });-- for (const [entityId] of this.iconElements) {- if (!existingEntityIds.has(entityId)) {- this.unregisterEntity(entityId);- }- }- }-}-```-## OverviewThis document covers the frontend configuration required to set up visual representations for entity types. It includes icon configuration, path styling, viewbox management, and visual asset creation.+### Key Configuration Files+- **Icons**: `hi/apps/entity/templates/entity/svg/type.{TYPE}.svg`+- **Registration**: `hi.hi_styles.EntityStyle.EntityTypesWithIcons`+- **Path Types**: `hi.hi_styles.EntityStyle.EntityTypeClosedPaths/EntityTypeOpenPaths`+- **Styling**: `hi.hi_styles.EntityStyle.PathEntityTypeToSvgStatusStyle`+## Entity Display MethodsEntities can be visually represented through two primary methods:@@ -1892,257 +267,215 @@ SimEntityType = Enum('SimEntityType', [])```-## Troubleshooting-### Entity Icon Not Displaying+## Real-World Workflow Examples++### Workflow 1: Adding a New Entity Type with Custom Icon++**Scenario**: Add support for a "Smart Door Lock" entity type with a custom icon and status colors.-**Symptoms**: Entity shows as placeholder or missing icon-**Diagnostic Steps**:+**Complete Implementation Process:**-1. **Check File Path and Naming**- ```bash- # Verify file exists with correct name- ls hi/apps/entity/templates/entity/svg/type.{enum_name}.svg+1. **Domain Setup** (Cross-reference: [Entity Patterns](../domain/entity-patterns.md))+ ```python+ # Add to hi.apps.entity.enums.EntityType+ class EntityType(Enum):+ # ... existing types+ SMART_DOOR_LOCK = ("smart_door_lock", "Smart Door Lock")- # Example: for EntityType.MOTION_SENSOR- ls hi/apps/entity/templates/entity/svg/type.motion_sensor.svg+ # Add to appropriate group+ class EntityGroupType(Enum):+ SECURITY_DEVICES = "security_devices"+ # Add SMART_DOOR_LOCK to this group+ ```++2. **Create Custom SVG Icon** ([Create SVG Icon Asset](#create-svg-icon-asset))++Note: Do **not** use the `<g>` tag inside these SVGs!++ ```xml+ <!-- File: hi/apps/entity/templates/entity/svg/type.smart_door_lock.svg -->+ <rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>+ <!-- Door outline -->+ <rect x="20" y="10" width="24" height="44" fill="none" stroke="currentColor" stroke-width="2"/>+ <!-- Lock mechanism -->+ <circle cx="32" cy="32" r="6" fill="currentColor"/>+ <!-- Key hole -->+ <circle cx="32" cy="32" r="2" fill="white"/>+ <!-- Status indicator (will change color based on state) -->+ <circle cx="45" cy="15" r="4" fill="currentColor" opacity="0.8"/>```- - **Rule**: File name must match enum name in lowercase with underscores-2. **Verify Icon Registration**+3. **Register Icon Type** ([Register Icon Configuration](#register-icon-configuration))```python- # Check in hi.hi_styles.EntityStyle.EntityTypesWithIcons+ # In hi.hi_styles.EntityStyle.EntityTypesWithIconsEntityTypesWithIcons = {- EntityType.MOTION_SENSOR, # Must be present- # ... your new entity type+ EntityType.MOTION_SENSOR,+ EntityType.DOOR_SENSOR,+ EntityType.SMART_DOOR_LOCK, # Add this line+ # ... existing types}```-3. **Check SVG File Content**- ```xml- <!-- File should NOT have <svg> wrapper -->- <!-- GOOD -->- <rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>- <circle cx="32" cy="32" r="20" fill="currentColor"/>+4. **Define Status-Specific Styling** ([Status Colors](../entity-status-display.md#status-color-system))+ ```css+ /* Add to your CSS file */+ .entity-svg.door-lock-locked {+ fill: var(--status-idle); /* Green - secure */+ stroke: #006600;+ }++ .entity-svg.door-lock-unlocked {+ fill: var(--status-recent); /* Orange - caution */+ stroke: #cc6600;+ }++ .entity-svg.door-lock-jammed {+ fill: var(--status-active); /* Red - problem */+ stroke: #cc0000;+ }- <!-- BAD -->- <svg viewBox="0 0 64 64">- <circle cx="32" cy="32" r="20" fill="currentColor"/>- </svg>+ .entity-svg.door-lock-offline {+ fill: var(--status-unknown); /* Gray - unknown */+ stroke: #666666;+ }```-**Common Fixes**:-- **Incorrect enum case**: Ensure file name uses lowercase and underscores-- **Missing registration**: Add entity type to `EntityTypesWithIcons` set-- **Invalid SVG**: Remove `<svg>` wrapper, keep only drawing commands-- **Missing clickable background**: Add `hi-entity-bg` rectangle+5. **Test Visual Configuration** ([Testing Visual Configuration](#testing-visual-configuration))+ ```python+ # Create test entity+ test_door_lock = Entity.objects.create(+ name="Front Door Lock",+ entity_type=EntityType.SMART_DOOR_LOCK,+ location=test_location+ )++ # Create EntityPosition for icon display+ EntityPosition.objects.create(+ entity=test_door_lock,+ x=100, y=150,+ scale=1.0, rotation=0+ )+ ```-### Entity Icon Wrong Size or Position+6. **Verify in Location View**+ - Navigate to location view containing the door lock+ - Verify icon displays correctly+ - Test status changes trigger color updates+ - Check click interactions work (clickable background)-**Symptoms**: Icon appears too large, small, or positioned incorrectly-**Root Causes & Solutions**:+**Expected Result**: Smart door lock appears as custom icon with status-based color changes.-1. **ViewBox Issues**- ```python- # Check custom viewbox registration- EntityTypeToIconViewbox = {- EntityType.YOUR_TYPE: "0 0 100 50", # Custom viewbox- }- ```- - **Default**: `0 0 64 64` - if icon designed differently, register custom viewbox+----2. **SVG Coordinate Problems**- ```xml- <!-- Icons should be designed for 64x64 viewbox -->- <rect class="hi-entity-bg" x="0" y="0" width="64" height="64" fill="none"/>- <!-- Center elements around 32,32 -->- <circle cx="32" cy="32" r="20" fill="currentColor"/>- ```+### Workflow 2: Converting Icon Entity to Path Entity-3. **Template Transform Issues**- ```django- <!-- Check entity positioning in template -->- <g transform="translate({{ entity.position.x }}, {{ entity.position.y }})- scale({{ entity.position.scale }})- rotate({{ entity.position.rotation }})">- <use href="#icon-{{ entity.entity_type.name.lower }}"/>- </g>- ```+**Scenario**: Motion sensor needs to represent a coverage area rather than just a point location.-### Entity Path Not Rendering+**Migration Process:**-**Symptoms**: Path-based entities don't appear or have no styling-**Diagnostic Approach**:+1. **Plan Path Representation** ([Entity Display Methods](#entity-display-methods))+ ```python+ # Motion sensor coverage area as circular path+ # Center: sensor position+ # Radius: detection range+ coverage_radius = 50 # units in SVG coordinates+ center_x, center_y = 200, 300+ ```-1. **Verify Path Type Registration**+2. **Remove from Icon Registry** ([Icon Configuration](#register-icon-configuration))```python- # Check appropriate path type set- EntityTypeClosedPaths = {- EntityType.ROOM,- EntityType.YOUR_AREA_TYPE, # For filled areas- }-- EntityTypeOpenPaths = {- EntityType.BOUNDARY_LINE,- EntityType.YOUR_LINE_TYPE, # For lines/curves+ # Remove from hi.hi_styles.EntityStyle.EntityTypesWithIcons+ EntityTypesWithIcons = {+ # EntityType.MOTION_SENSOR, # Comment out or remove+ EntityType.DOOR_SENSOR,+ # ... other types}```-2. **Check Style Assignment**+3. **Add to Path Registry** ([Path-Based Configuration](#path-based-entity-configuration))```python- # Verify style is assigned- PathEntityTypeToSvgStatusStyle = {- EntityType.YOUR_TYPE: YourCustomSvgStatusStyle,+ # Add to hi.hi_styles.EntityStyle.EntityTypeClosedPaths+ EntityTypeClosedPaths = {+ EntityType.ROOM,+ EntityType.MOTION_SENSOR, # Add this line+ # ... existing types}```-3. **Validate SVG Path Data**- ```django- <!-- Entity must have valid SVG path -->- <path class="entity-path"- d="{{ entity.path.svg_path }}" <!-- Must be valid SVG path data -->- style="{{ entity.get_path_styling }}"/>+4. **Create SVG Path Data** ([SVG Path Requirements](#path-based-entity-configuration))+ ```python+ import math++ def create_circular_path(center_x, center_y, radius):+ """Create SVG path for circular coverage area"""+ # Create circle using path commands (more flexible than <circle>)+ path_data = (+ f"M {center_x - radius} {center_y} "+ f"A {radius} {radius} 0 0 1 {center_x + radius} {center_y} "+ f"A {radius} {radius} 0 0 1 {center_x - radius} {center_y} "+ f"Z"+ )+ return path_data++ # Update existing motion sensor entities+ for motion_sensor in Entity.objects.filter(entity_type=EntityType.MOTION_SENSOR):+ # Get current position+ position = motion_sensor.entityposition_set.first()+ if position:+ # Create EntityPath with coverage area+ EntityPath.objects.create(+ entity=motion_sensor,+ svg_path=create_circular_path(position.x, position.y, 50)+ )+ # Remove EntityPosition+ position.delete()```-**Solutions**:-- **Missing path registration**: Add to correct path type set (closed vs open)-- **No style defined**: Create and assign `SvgStatusStyle` class-- **Invalid path data**: Ensure `entity.path.svg_path` contains valid SVG path commands--### Entity Colors/Styling Not Applied--**Symptoms**: Entity shows default colors, status changes don't affect appearance-**Troubleshooting Steps**:--1. **Check Style Class Definition**+5. **Define Path Styling** ([Define Visual Style](#define-visual-style))```python- class YourCustomSvgStatusStyle:- # Must define all required properties+ # Create new style class in hi.hi_styles.EntityStyle+ class MotionSensorPathStyle:default_fill = "#E0E0E0"default_stroke = "#808080"+ default_opacity = 0.3active_fill = "#FF4444"active_stroke = "#CC0000"+ active_opacity = 0.6- # ... other states- ```--2. **Verify CSS Class Application**- ```html- <!-- Entity element should have status classes -->- <path class="entity-path state-active" .../>+ recent_fill = "#FF8844"+ recent_stroke = "#CC4400"+ recent_opacity = 0.5++ idle_fill = "#44FF44"+ idle_stroke = "#00CC00"+ idle_opacity = 0.3- <!-- CSS rules should exist -->- .entity-path.state-active {- fill: #FF4444;- stroke: #CC0000;+ # Register the style+ PathEntityTypeToSvgStatusStyle = {+ EntityType.MOTION_SENSOR: MotionSensorPathStyle,+ # ... existing mappings}```-3. **Test Status Changes**- ```javascript- // Manually test CSS class changes- const element = document.querySelector('[data-entity-id="123"]');- element.classList.add('state-active');- // Should see visual change- ```--### Template Integration Problems--**Symptoms**: New entity types don't appear in location views-**Checklist**:--1. **Entity Creation**- ```python- # Entity must be properly created with type- entity = Entity.objects.create(- name="Test Entity",- entity_type=EntityType.YOUR_NEW_TYPE,- location=location- )- ```--2. **Template Symbol Definitions**- ```django- <!-- Icons must be defined in template -->- <defs>- {% for entity_type in entity_types_with_icons %}- <symbol id="icon-{{ entity_type.name.lower }}"- viewBox="{{ entity_type.get_viewbox }}">- {% include entity_type.get_icon_template %}- </symbol>- {% endfor %}- </defs>- ```--3. **Entity Rendering Logic**+6. **Update Templates** (Cross-reference: [Template Integration](#template-integration))```django+ <!-- Motion sensors now render as paths instead of icons -->{% for entity in entities %}- {% if entity.has_position %}- <!-- Icon entity rendering -->- {% elif entity.has_path %}- <!-- Path entity rendering -->+ {% if entity.entity_type.name == 'MOTION_SENSOR' %}+ <path class="entity-path {{ entity.get_status_css_classes }}"+ data-entity-id="{{ entity.id }}"+ d="{{ entity.path.svg_path }}"+ style="{{ entity.get_path_styling }}"/>+ {% elif entity.has_position %}+ <!-- Other icon entities -->+ <use href="#icon-{{ entity.entity_type.name.lower }}"/>{% endif %}{% endfor %}```-### Performance and Visual Quality Issues--**Symptoms**: Icons appear pixelated, slow rendering, or memory issues-**Optimizations**:--1. **SVG Optimization**- ```xml- <!-- Use simple shapes, avoid complex paths -->- <!-- GOOD - simple circle -->- <circle cx="32" cy="32" r="20"/>-- <!-- AVOID - complex path when simple shape works -->- <path d="M12,32 A20,20 0 1,1 52,32 A20,20 0 1,1 12,32"/>- ```--2. **Reduce Icon Complexity**- ```xml- <!-- Limit number of elements per icon -->- <!-- Combine shapes where possible -->- <!-- Use fill over stroke for better performance -->- ```--3. **Browser Rendering Optimization**- ```css- /* Force hardware acceleration for smooth animations */- .entity-svg {- transform: translateZ(0);- will-change: transform;- }- ```--### Browser Compatibility Issues--**Symptoms**: Icons work in some browsers but not others-**Common Problems & Solutions**:--1. **SVG Symbol Support (IE)**- ```html- <!-- Use polyfill for older browsers -->- <script src="svg4everybody.js"></script>- <script>svg4everybody();</script>- ```--2. **CSS Custom Properties (IE/Edge)**- ```css- /* Provide fallbacks */- .entity-path {- fill: #E0E0E0; /* fallback */- fill: var(--entity-default-fill, #E0E0E0);- }- ```--3. **ViewBox Issues (Safari)**- ```xml- <!-- Always specify explicit dimensions -->- <symbol id="icon-sensor" viewBox="0 0 64 64" width="64" height="64">- ```+**Expected Result**: Motion sensors display as coverage areas that show detection zones rather than point icons.## Related Documentation- Entity domain patterns: [Entity Patterns](../domain/entity-patterns.md)diff --git a/docs/dev/frontend/icon-system.md b/docs/dev/frontend/icon-system.mdindex 9cc87c10..ecaf9d39 100644--- a/docs/dev/frontend/icon-system.md+++ b/docs/dev/frontend/icon-system.md@@ -2,7 +2,7 @@## Icon System Overview-Use the standardized `{% icon %}` template tag. See `hi/apps/common/templatetags/icons.py` for implementation details and parameters.+Use the standardized `{% icon %}` template tag for consistent icon rendering. See `hi/apps/common/templatetags/icons.py` for available icons and parameters.## UX Principles for Icon Usage@@ -10,13 +10,12 @@ Use the standardized `{% icon %}` template tag. See `hi/apps/common/templatetagsIcons provide faster recognition, universal language, space efficiency, and visual hierarchy.### ALWAYS Add Icons When-- **Universal Actions**: Add (+), Delete (trash), Edit (pencil), Save (checkmark), Cancel (×)- **Navigation**: Back/Forward arrows, Up/Down, Expand/Collapse- **Media Controls**: Play, Pause, Video, Camera- **Status/Feedback**: Success, Warning, Error, Info-### Key Principle+### Key Design PrincipleFocus on **ACTION TYPE** (add, delete, edit), not object specificity. "Add Item" and "Add Rule" both get the same + icon because they're both "add" actions.## Implementation Requirements@@ -27,6 +26,29 @@ Focus on **ACTION TYPE** (add, delete, edit), not object specificity. "Add Item"- Include appropriate ARIA labels for accessibility- Maintain consistency: same action = same icon across the application+## Icon Parameters++### Size Options+- `xs` - Extra small (12px)+- `sm` - Small (16px) - **Most common**+- `md` - Medium (20px) - Default+- `lg` - Large (24px)+- `xl` - Extra large (32px)++### CSS Classes+- `hi-icon-left` - Icon positioned to the left of text+- `hi-icon-right` - Icon positioned to the right of text+- `hi-icon-only` - Icon without accompanying text+- `hi-icon-spin` - Spinning animation for loading states++### Color Options+When available through the icon system:+- `text-primary` - Primary theme color+- `text-success` - Success/positive actions+- `text-warning` - Warning/caution+- `text-danger` - Danger/destructive actions+- `text-muted` - Subtle/disabled state+## Template Usage Examples### Basic Icon Usage@@ -51,12 +73,6 @@ Focus on **ACTION TYPE** (add, delete, edit), not object specificity. "Add Item"{% icon "save" size="sm" css_class="hi-icon-left" %}Save Changes</button>--<!-- Cancel action -->-<a class="btn btn-tertiary" href="#" data-dismiss="modal">- {% icon "cancel" size="sm" css_class="hi-icon-left" %}- Cancel-</a>```### Icon-Only Actions@@ -73,19 +89,6 @@ Use for space-constrained areas with proper accessibility:<button type="button" class="close" data-dismiss="modal" aria-label="Close">{% icon "close" size="sm" %}</button>--<!-- Toolbar actions -->-<div class="btn-group" role="group">- <button type="button" class="btn btn-outline-secondary" aria-label="Bold">- {% icon "bold" size="sm" %}- </button>- <button type="button" class="btn btn-outline-secondary" aria-label="Italic">- {% icon "italic" size="sm" %}- </button>- <button type="button" class="btn btn-outline-secondary" aria-label="Underline">- {% icon "underline" size="sm" %}- </button>-</div>```### Status and Feedback Icons@@ -102,92 +105,8 @@ Use for space-constrained areas with proper accessibility:{% icon "exclamation-triangle" size="sm" css_class="hi-icon-left" %}Please review your settings before continuing.</div>--<!-- Error message -->-<div class="alert alert-danger">- {% icon "times-circle" size="sm" css_class="hi-icon-left" %}- An error occurred while processing your request.-</div>--<!-- Info message -->-<div class="alert alert-info">- {% icon "info-circle" size="sm" css_class="hi-icon-left" %}- This feature is currently in beta.-</div>```-### Navigation Icons--```django-<!-- Breadcrumb navigation -->-<nav aria-label="breadcrumb">- <ol class="breadcrumb">- <li class="breadcrumb-item">- <a href="{% url 'home' %}">- {% icon "home" size="sm" css_class="hi-icon-left" %}- Home- </a>- </li>- <li class="breadcrumb-item">- <a href="{% url 'entities' %}">Entities</a>- </li>- <li class="breadcrumb-item active">Edit Entity</li>- </ol>-</nav>--<!-- Back button -->-<a href="{{ back_url }}" class="btn btn-secondary">- {% icon "arrow-left" size="sm" css_class="hi-icon-left" %}- Back-</a>--<!-- Pagination -->-<nav>- <ul class="pagination">- <li class="page-item">- <a class="page-link" href="?page={{ page.previous_page_number }}">- {% icon "chevron-left" size="sm" %}- Previous- </a>- </li>- <li class="page-item active">- <span class="page-link">{{ page.number }}</span>- </li>- <li class="page-item">- <a class="page-link" href="?page={{ page.next_page_number }}">- Next- {% icon "chevron-right" size="sm" %}- </a>- </li>- </ul>-</nav>-```--## Icon Parameters--All icon CSS rules are defined in `src/hi/static/css/icons.css`.--### Size Options-- `xs` - Extra small (12px)-- `sm` - Small (16px) - **Most common**-- `md` - Medium (20px) - Default-- `lg` - Large (24px)-- `xl` - Extra large (32px)--### CSS Classes-- `hi-icon-left` - Icon positioned to the left of text-- `hi-icon-right` - Icon positioned to the right of text-- `hi-icon-only` - Icon without accompanying text-- `hi-icon-spin` - Spinning animation for loading states--### Color Options-When available through the icon system:-- `text-primary` - Primary theme color-- `text-success` - Success/positive actions-- `text-warning` - Warning/caution-- `text-danger` - Danger/destructive actions-- `text-muted` - Subtle/disabled state-## Accessibility Considerations### ARIA Labels@@ -222,49 +141,15 @@ Ensure icon buttons have visible focus indicators:}```-## Available Icons--Common icons available in the system (see `hi/apps/common/templatetags/icons.py` for complete list):--### Actions-- `plus` - Add/Create-- `edit` / `pencil` - Edit/Modify-- `delete` / `trash` - Delete/Remove-- `save` / `check` - Save/Confirm-- `cancel` / `times` - Cancel/Close-- `copy` - Duplicate-- `download` - Export/Download-- `upload` - Import/Upload--### Navigation-- `home` - Home page-- `arrow-left` / `arrow-right` - Back/Forward-- `chevron-left` / `chevron-right` - Previous/Next-- `arrow-up` / `arrow-down` - Up/Down-- `external-link` - External links--### Status/Feedback-- `check-circle` - Success-- `exclamation-triangle` - Warning-- `times-circle` - Error-- `info-circle` - Information-- `question-circle` - Help--### Media-- `play` - Play action-- `pause` - Pause action-- `video` - Video content-- `camera` - Camera/Photo--### UI Elements-- `search` - Search functionality-- `filter` - Filter/Sort-- `settings` / `cog` - Configuration-- `user` - User/Profile-- `list` - List view-- `grid` - Grid view+## Icon Discovery and Creation++For finding appropriate icons or creating new ones, use the `/icon` command which will:+- Search existing icons for semantic matches+- Recommend existing icons when appropriate+- Guide creation of new icons when needed+- Maintain consistency with the icon system## Related Documentation- Frontend guidelines: [Frontend Guidelines](frontend-guidelines.md)- Style guidelines: [Style Guidelines](style-guidelines.md)-- Template conventions: [Template Conventions](template-conventions.md)+- Template conventions: [Template Conventions](template-conventions.md)\ No newline at end of filediff --git a/docs/dev/frontend/style-guidelines.md b/docs/dev/frontend/style-guidelines.mdindex e3d6c7dd..3d19d234 100644--- a/docs/dev/frontend/style-guidelines.md+++ b/docs/dev/frontend/style-guidelines.md@@ -1,325 +1,90 @@# Style Guidelines-## Responsiveness+## Design Targets-The predominant use of this app is in a tablet in landscape mode with a touch screen. Secondary usage would be a laptop or desktop. For mobile (phone) devices, we only need for it to render well enough to be usable in the phone's landscape mode. We can assume that we do not have to support very narrow widths of a phone in portrait mode.+**Primary**: Tablet landscape mode with touch screen+**Secondary**: Laptop/desktop+**Minimum**: Phone landscape mode (not portrait)-### Breakpoint Strategy+## Responsive Design-```scss-// Bootstrap 4 breakpoints we use-// Small devices (landscape phones, 576px and up)-@media (min-width: 576px) { ... }+### Breakpoints+Bootstrap 4 breakpoints with tablet-first approach:+- **768px+ (md)**: Primary target - tablets+- **992px+ (lg)**: Desktops+- **1200px+ (xl)**: Large desktops-// Medium devices (tablets, 768px and up) - PRIMARY TARGET-@media (min-width: 768px) { ... }+### Touch-Friendly Requirements+- **Minimum touch target**: 44x44px for all interactive elements+- **No hover dependencies**: Use click/tap interactions+- **Adequate spacing**: Between clickable elements+- **Standard gestures**: Swipe, pinch-zoom for SVGs-// Large devices (desktops, 992px and up)-@media (min-width: 992px) { ... }--// Extra large devices (large desktops, 1200px and up)-@media (min-width: 1200px) { ... }-```--### Touch-Friendly Design--1. **Minimum Touch Target**: 44x44px for all interactive elements-2. **Spacing**: Adequate spacing between clickable elements-3. **Hover States**: Don't rely on hover - use click/tap interactions-4. **Gestures**: Support standard touch gestures (swipe, pinch-zoom for SVGs)--## Color System--### Status Colors--Consistent color usage for entity states:+## Color System & Variables+### Status Colors (Traffic Light Pattern)```css:root {- /* Status colors following traffic light metaphor */- --status-active: #dc3545; /* Red - Active/Alert */- --status-recent: #fd7e14; /* Orange - Recently active */- --status-past: #ffc107; /* Yellow - Past activity */- --status-idle: #28a745; /* Green - Idle/Safe */- --status-unknown: #6c757d; /* Gray - Unknown/Offline */-- /* Alert levels */- --alert-critical: #dc3545; /* Red */- --alert-warning: #ffc107; /* Yellow */- --alert-info: #17a2b8; /* Cyan */- --alert-success: #28a745; /* Green */-}-```--### Theme Variables--```css-:root {- /* Primary palette */- --primary: #007bff;- --secondary: #6c757d;- --success: #28a745;- --info: #17a2b8;- --warning: #ffc107;- --danger: #dc3545;-- /* UI elements */- --border-color: #dee2e6;- --shadow: 0 0.125rem 0.25rem rgba(0,0,0,0.075);- --shadow-lg: 0 1rem 3rem rgba(0,0,0,0.175);-}-```--## Component Styling--### Cards and Panels--```css-.hi-card {- background: white;- border: 1px solid var(--border-color);- border-radius: 0.25rem;- box-shadow: var(--shadow);- padding: 1rem;- margin-bottom: 1rem;-}--.hi-card--clickable {- cursor: pointer;- transition: box-shadow 0.2s;-}--.hi-card--clickable:hover {- box-shadow: var(--shadow-lg);-}-```--### Buttons--Extend Bootstrap buttons with consistent icon usage:--```css-.btn {- display: inline-flex;- align-items: center;- min-height: 44px; /* Touch-friendly */- padding: 0.5rem 1rem;-}--.hi-icon-left {- margin-right: 0.5rem;-}--.hi-icon-right {- margin-left: 0.5rem;-}-```--### Forms--Touch-optimized form controls:--```css-.form-control {- min-height: 44px;- font-size: 16px; /* Prevents zoom on iOS */-}--.form-group {- margin-bottom: 1.5rem; /* More spacing for touch */-}--select.form-control {- padding-right: 2rem; /* Room for dropdown arrow */+ --status-active: #dc3545; /* Red - Active/Alert */+ --status-recent: #fd7e14; /* Orange - Recently active */+ --status-past: #ffc107; /* Yellow - Past activity */+ --status-idle: #28a745; /* Green - Idle/Safe */+ --status-unknown: #6c757d; /* Gray - Unknown/Offline */}```-## SVG Styling-### Entity State Visualization--```css-/* Base entity styling */-.entity-svg {- transition: fill 0.3s, stroke 0.3s, opacity 0.3s;-}--/* State-based styling */-.entity-svg.state-active {- fill: var(--status-active);- fill-opacity: 0.8;-}--.entity-svg.state-recent {- fill: var(--status-recent);- fill-opacity: 0.6;-}--.entity-svg.state-past {- fill: var(--status-past);- fill-opacity: 0.4;-}--.entity-svg.state-idle {- fill: var(--status-idle);- fill-opacity: 0.3;-}-```--### Interactive SVG Elements--```css-.entity-clickable {- cursor: pointer;-}--.entity-clickable:hover {- stroke: var(--primary);- stroke-width: 2;-}--.entity-selected {- stroke: var(--primary);- stroke-width: 3;- stroke-dasharray: 5,5;-}-```--## Layout Patterns--### Grid System--Use Bootstrap's grid with tablet-first approach:--```html-<!-- Tablet-optimized layout -->-<div class="row">- <div class="col-md-8">- <!-- Main content - larger on tablet -->- </div>- <div class="col-md-4">- <!-- Sidebar - narrower on tablet -->- </div>-</div>-```--### Flex Utilities--Use flexbox for component layouts:--```css-.hi-toolbar {- display: flex;- justify-content: space-between;- align-items: center;- padding: 0.5rem;- background: #f8f9fa;- border-bottom: 1px solid var(--border-color);-}--.hi-toolbar__actions {- display: flex;- gap: 0.5rem;-}-```--## Animation and Transitions--### Performance Considerations--```css-/* Use transform and opacity for smooth animations */-.modal {- transition: opacity 0.3s, transform 0.3s;-}--.modal.show {- opacity: 1;- transform: translateY(0);-}--/* Avoid animating expensive properties */-/* Bad: transition: all 0.3s; */-/* Good: transition: opacity 0.3s, transform 0.3s; */-```--### Loading States--```css-.loading-spinner {- display: inline-block;- width: 1rem;- height: 1rem;- border: 2px solid #f3f3f3;- border-top: 2px solid var(--primary);- border-radius: 50%;- animation: spin 1s linear infinite;-}--@keyframes spin {- 0% { transform: rotate(0deg); }- 100% { transform: rotate(360deg); }-}-```--## Accessibility--### Focus Indicators--```css-/* Visible focus for keyboard navigation */-:focus {- outline: 2px solid var(--primary);- outline-offset: 2px;-}--/* Remove outline for mouse users */-:focus:not(:focus-visible) {- outline: none;-}-```--### High Contrast Support--```css-@media (prefers-contrast: high) {- :root {- --border-color: #000;- --shadow: 0 0 0 1px #000;- }-- .btn {- border: 2px solid currentColor;- }-}-```--## Print Styles--```css-@media print {- /* Hide navigation and controls */- .hi-toolbar,- .hi-sidebar,- .btn-group {- display: none !important;- }-- /* Ensure content fits on page */- .hi-main-content {- width: 100%;- margin: 0;- }-- /* Avoid page breaks in cards */- .hi-card {- page-break-inside: avoid;- }-}-```+CSS classes for SVG entity styling:+- `.entity-svg.state-active` - Red with 0.8 opacity+- `.entity-svg.state-recent` - Orange with 0.6 opacity+- `.entity-svg.state-past` - Yellow with 0.4 opacity+- `.entity-svg.state-idle` - Green with 0.3 opacity++## Component Classes++### Layout Components+- `.hi-card` - Standard card styling with shadow and padding+- `.hi-card--clickable` - Clickable card with hover effects+- `.hi-toolbar` - Flexbox toolbar with actions+- `.hi-toolbar__actions` - Action buttons container++### Icon Integration+- `.hi-icon-left` - Icon positioned left of text+- `.hi-icon-right` - Icon positioned right of text+- `.hi-icon-only` - Icon without text+- `.hi-icon-spin` - Spinning animation for loading++### Interactive Elements+- `.entity-clickable` - Cursor pointer for SVG elements+- `.entity-selected` - Dashed stroke for selected entities+- `.loading-spinner` - Rotating spinner animation++## Form Styling++### Touch Optimization+- **Minimum height**: 44px for all form controls+- **Font size**: 16px minimum (prevents iOS zoom)+- **Spacing**: 1.5rem margin between form groups+- **Select padding**: Extra right padding for dropdown arrow++## Performance Guidelines++### Animation Best Practices+- **Use**: `opacity` and `transform` for smooth animations+- **Avoid**: `transition: all` - specify properties explicitly+- **Timing**: 0.3s standard transition duration++### Accessibility Features+- **Focus indicators**: 2px outline with offset+- **High contrast support**: Media query for `prefers-contrast: high`+- **Keyboard navigation**: Visible focus states++## Key CSS Files+- `src/hi/static/css/base.css` - Core styles and variables+- `src/hi/static/css/components.css` - Component-specific styles+- `src/hi/static/css/entity.css` - Entity state visualization## Related Documentation-- Icon system: [Icon System](icon-system.md)-- Frontend guidelines: [Frontend Guidelines](frontend-guidelines.md)-- Template conventions: [Template Conventions](template-conventions.md)-- UI testing: [UI Testing](ui-testing.md)\ No newline at end of file+- [Icon System](icon-system.md)+- [Frontend Guidelines](frontend-guidelines.md)+- [Template Conventions](template-conventions.md)\ No newline at end of filediff --git a/docs/dev/frontend/svg-coordinate-operations.md b/docs/dev/frontend/svg-coordinate-operations.mddeleted file mode 100644index 3cc0a3be..00000000--- a/docs/dev/frontend/svg-coordinate-operations.md+++ /dev/null@@ -1,3031 +0,0 @@-# SVG Coordinate Operations--## Quick Reference--### Common Tasks-- **Convert SVG to screen coords** → [Use coordinate transform](#screen-position-calculation) → `calculate_entity_position()`-- **Handle mouse clicks** → [Screen to SVG conversion](#interactive-coordinate-conversion) → `screenToSvgCoordinates()`-- **Implement zoom controls** → [Viewport controller](#zoom-and-pan-operations) → `SvgViewportController`-- **Position entities dynamically** → [Entity positioning](#entity-positioning-and-scaling) → `updateEntityPosition()`-- **Debug coordinate issues** → [Check coordinate systems](#coordinate-system-types) → Verify SVG vs screen vs viewport--### Key JavaScript Classes-- **`SvgCoordinateTransform`**: Converts between coordinate systems-- **`SvgInteractionHandler`**: Handles mouse events and SVG interactions-- **`SvgViewportController`**: Manages zoom, pan, and viewport transforms-- **`EntityPositionManager`**: Updates entity positions based on viewport--### Quick Fixes-| Problem | Solution | Location |-|---------|----------|----------|-| Click detection wrong | Check coordinate conversion | [Interactive Coordinate](#interactive-coordinate-conversion) |-| Entity positions wrong | Verify viewBox parsing | [Screen Position](#screen-position-calculation) |-| Zoom not working | Initialize viewport controller | [Zoom Operations](#zoom-and-pan-operations) |-| Performance issues | Use requestAnimationFrame | [Performance](#efficient-coordinate-calculations) |--### Coordinate System Quick Guide-```-Mouse Click (screen pixels)- ↓ getBoundingClientRect()-SVG Viewport Coordinates- ↓ getScreenCTM().inverse()-SVG Document Coordinates- ↓ viewBox transformation-Entity Local Coordinates-```--### Common Coordinate Conversions-- **Screen → SVG**: `element.createSVGPoint()` + `getScreenCTM().inverse()`-- **SVG → Screen**: `(svg_coord - viewbox_origin) * scale_factor`-- **Viewport → Entity**: Apply entity transform matrix---## Real-World Workflow Examples--### Workflow 1: Implementing Click-to-Details for Location Entities--**Scenario**: Users should be able to click on any entity in a location view to open a details modal with current status and controls.--**Complete Implementation:**--1. **Set Up SVG Event Handling** ([Interactive Coordinate Conversion](#interactive-coordinate-conversion))- ```javascript- class EntityClickHandler {- constructor(svgElement) {- this.svgElement = svgElement;- this.setupEventListeners();- }-- setupEventListeners() {- this.svgElement.addEventListener('click', (event) => {- const entityElement = event.target.closest('[data-entity-id]');- if (entityElement) {- const entityId = entityElement.getAttribute('data-entity-id');- this.handleEntityClick(event, entityId);- }- });- }-- handleEntityClick(event, entityId) {- // Convert screen click to SVG coordinates for context- const svgCoords = this.screenToSvgCoordinates(event.clientX, event.clientY);-- // Open entity details modal- this.openEntityModal(entityId, svgCoords);- }-- screenToSvgCoordinates(screenX, screenY) {- const rect = this.svgElement.getBoundingClientRect();- const svgPoint = this.svgElement.createSVGPoint();- svgPoint.x = screenX - rect.left;- svgPoint.y = screenY - rect.top;-- const ctm = this.svgElement.getScreenCTM().inverse();- return svgPoint.matrixTransform(ctm);- }- }- ```--2. **Template Setup for Clickable Entities** ([Template Integration](#template-integration))- ```django- <!-- Ensure all entities have proper data attributes -->- <svg id="location-svg" viewBox="0 0 1000 800">- <g id="main-group">- <!-- Icon entities -->- {% for entity in icon_entities %}- <g class="entity-group" data-entity-id="{{ entity.id }}" data-entity-name="{{ entity.name }}">- <use href="#icon-{{ entity.entity_type.name.lower }}"- transform="translate({{ entity.position.x }}, {{ entity.position.y }})"/>- </g>- {% endfor %}-- <!-- Path entities -->- {% for entity in path_entities %}- <path class="entity-path"- data-entity-id="{{ entity.id }}"- data-entity-name="{{ entity.name }}"- d="{{ entity.path.svg_path }}"/>- {% endfor %}- </g>- </svg>- ```--3. **Handle Edge Cases** ([Troubleshooting - Click Detection](#click-detection-not-working))- ```javascript- class RobustEntityClickHandler extends EntityClickHandler {- handleEntityClick(event, entityId) {- // Prevent event bubbling issues- event.stopPropagation();-- // Validate entity exists- if (!this.validateEntity(entityId)) {- console.warn('Invalid entity clicked:', entityId);- return;- }-- // Handle coordinate conversion errors- try {- const svgCoords = this.screenToSvgCoordinates(event.clientX, event.clientY);- this.openEntityModal(entityId, svgCoords);- } catch (error) {- console.error('Coordinate conversion failed:', error);- // Fallback: open modal without coordinate context- this.openEntityModal(entityId, null);- }- }-- validateEntity(entityId) {- // Check if entity element still exists- return document.querySelector(`[data-entity-id="${entityId}"]`) !== null;- }- }- ```--4. **Initialize Click Handling** ([Template Integration](#template-integration))- ```javascript- // Initialize when DOM is ready- document.addEventListener('DOMContentLoaded', function() {- const locationSvg = document.getElementById('location-svg');- if (locationSvg) {- window.entityClickHandler = new RobustEntityClickHandler(locationSvg);- console.log('Entity click handling initialized');- }- });- ```--**Expected Result**: Clicking any entity opens a details modal, with reliable coordinate conversion and error handling.-------### Workflow 2: Implementing Zoom and Pan Controls--**Scenario**: Large location views need zoom and pan functionality for better navigation, especially on mobile devices.--**Implementation Process:**--1. **Create Viewport Controller** ([Zoom and Pan Operations](#zoom-and-pan-operations))- ```javascript- class LocationViewportController {- constructor(svgElement) {- this.svgElement = svgElement;- this.mainGroup = svgElement.querySelector('#main-group');- this.currentZoom = 1.0;- this.currentPan = { x: 0, y: 0 };- this.isDragging = false;- this.lastPanPoint = null;-- this.setupControls();- this.setupMouseHandling();- this.setupTouchHandling();- }-- setupControls() {- // Create zoom control buttons- const controlsHtml = `- <div class="viewport-controls">- <button id="zoom-in" class="btn btn-sm btn-outline-primary">+</button>- <button id="zoom-out" class="btn btn-sm btn-outline-primary">−</button>- <button id="zoom-fit" class="btn btn-sm btn-outline-secondary">Fit</button>- </div>- `;-- this.svgElement.parentElement.insertAdjacentHTML('beforeend', controlsHtml);-- // Attach event listeners- document.getElementById('zoom-in').addEventListener('click', () => this.zoomIn());- document.getElementById('zoom-out').addEventListener('click', () => this.zoomOut());- document.getElementById('zoom-fit').addEventListener('click', () => this.zoomToFit());- }- ```--2. **Implement Zoom Functions** ([Zoom Operations](#zoom-and-pan-operations))- ```javascript- zoomIn(factor = 1.2) {- this.currentZoom = Math.min(this.currentZoom * factor, 5.0); // Max 5x zoom- this.applyTransform();- }-- zoomOut(factor = 0.8) {- this.currentZoom = Math.max(this.currentZoom * factor, 0.1); // Min 0.1x zoom- this.applyTransform();- }-- zoomToFit() {- // Calculate bounding box of all entities- const entities = this.svgElement.querySelectorAll('[data-entity-id]');- if (entities.length === 0) return;-- let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;-- entities.forEach(entity => {- const bbox = entity.getBBox();- minX = Math.min(minX, bbox.x);- minY = Math.min(minY, bbox.y);- maxX = Math.max(maxX, bbox.x + bbox.width);- maxY = Math.max(maxY, bbox.y + bbox.height);- });-- // Add padding- const padding = 50;- const contentWidth = maxX - minX + (padding * 2);- const contentHeight = maxY - minY + (padding * 2);-- // Calculate zoom to fit- const svgRect = this.svgElement.getBoundingClientRect();- const scaleX = svgRect.width / contentWidth;- const scaleY = svgRect.height / contentHeight;- this.currentZoom = Math.min(scaleX, scaleY);-- // Center the content- this.currentPan = {- x: -(minX - padding) * this.currentZoom,- y: -(minY - padding) * this.currentZoom- };-- this.applyTransform();- }- ```--3. **Add Pan Support** ([Pan Operations](#zoom-and-pan-operations))- ```javascript- setupMouseHandling() {- this.svgElement.addEventListener('mousedown', (event) => {- if (event.button === 1 || (event.button === 0 && event.ctrlKey)) {- this.startPan(event.clientX, event.clientY);- event.preventDefault();- }- });-- document.addEventListener('mousemove', (event) => {- if (this.isDragging) {- this.updatePan(event.clientX, event.clientY);- }- });-- document.addEventListener('mouseup', () => {- this.endPan();- });-- // Mouse wheel zoom- this.svgElement.addEventListener('wheel', (event) => {- event.preventDefault();- const delta = event.deltaY > 0 ? 0.9 : 1.1;- this.zoomAt(event.clientX, event.clientY, delta);- });- }-- startPan(clientX, clientY) {- this.isDragging = true;- this.lastPanPoint = { x: clientX, y: clientY };- this.svgElement.style.cursor = 'grabbing';- }-- updatePan(clientX, clientY) {- if (!this.isDragging || !this.lastPanPoint) return;-- const deltaX = clientX - this.lastPanPoint.x;- const deltaY = clientY - this.lastPanPoint.y;-- this.currentPan.x += deltaX;- this.currentPan.y += deltaY;-- this.lastPanPoint = { x: clientX, y: clientY };- this.applyTransform();- }- ```--4. **Mobile Touch Support** ([Touch and Mobile Issues](#touch-and-mobile-issues))- ```javascript- setupTouchHandling() {- let lastTouchDistance = 0;-- this.svgElement.addEventListener('touchstart', (event) => {- if (event.touches.length === 1) {- // Single touch - pan- const touch = event.touches[0];- this.startPan(touch.clientX, touch.clientY);- } else if (event.touches.length === 2) {- // Two finger - zoom- const touch1 = event.touches[0];- const touch2 = event.touches[1];- lastTouchDistance = this.getTouchDistance(touch1, touch2);- }- event.preventDefault();- });-- this.svgElement.addEventListener('touchmove', (event) => {- if (event.touches.length === 1 && this.isDragging) {- const touch = event.touches[0];- this.updatePan(touch.clientX, touch.clientY);- } else if (event.touches.length === 2) {- const touch1 = event.touches[0];- const touch2 = event.touches[1];- const currentDistance = this.getTouchDistance(touch1, touch2);-- if (lastTouchDistance > 0) {- const scale = currentDistance / lastTouchDistance;- this.currentZoom *= scale;- this.applyTransform();- }-- lastTouchDistance = currentDistance;- }- event.preventDefault();- });- }- ```--**Expected Result**: Smooth zoom and pan controls work on both desktop and mobile, with proper touch gesture support.-------### Workflow 3: Dynamic Entity Positioning Based on Real-Time Data--**Scenario**: Entities need to move to new positions based on real-time location updates (e.g., tracking mobile devices or vehicles).--**Implementation Steps:**--1. **Create Position Update Manager** ([Entity Positioning and Scaling](#entity-positioning-and-scaling))- ```javascript- class DynamicEntityPositioner {- constructor(svgElement) {- this.svgElement = svgElement;- this.positionCache = new Map();- this.animationQueue = [];- this.isAnimating = false;- }-- updateEntityPosition(entityId, newPosition, animate = true) {- const element = this.svgElement.querySelector(`[data-entity-id="${entityId}"]`);- if (!element) {- console.warn('Entity not found for positioning:', entityId);- return;- }-- const currentPos = this.getCurrentPosition(element);-- if (animate) {- this.animateToPosition(element, currentPos, newPosition);- } else {- this.setPosition(element, newPosition);- }-- // Cache new position- this.positionCache.set(entityId, newPosition);- }-- getCurrentPosition(element) {- // Parse current transform to get position- const transform = element.getAttribute('transform') || '';- const match = transform.match(/translate\(([^,]+),\s*([^)]+)\)/);-- if (match) {- return {- x: parseFloat(match[1]),- y: parseFloat(match[2])- };- }-- return { x: 0, y: 0 };- }- ```--2. **Implement Smooth Animation** ([Performance Considerations](#performance-considerations))- ```javascript- animateToPosition(element, fromPos, toPos, duration = 1000) {- const startTime = performance.now();-- const animate = (currentTime) => {- const elapsed = currentTime - startTime;- const progress = Math.min(elapsed / duration, 1);-- // Easing function (ease-out)- const easeOut = 1 - Math.pow(1 - progress, 3);-- const currentX = fromPos.x + (toPos.x - fromPos.x) * easeOut;- const currentY = fromPos.y + (toPos.y - fromPos.y) * easeOut;-- this.setPosition(element, { x: currentX, y: currentY });-- if (progress < 1) {- requestAnimationFrame(animate);- }- };-- requestAnimationFrame(animate);- }-- setPosition(element, position) {- // Preserve other transform properties (scale, rotation)- const currentTransform = element.getAttribute('transform') || '';- const scale = this.extractTransformValue(currentTransform, 'scale') || 1;- const rotation = this.extractTransformValue(currentTransform, 'rotate') || 0;-- const newTransform = `translate(${position.x}, ${position.y}) scale(${scale}) rotate(${rotation})`;- element.setAttribute('transform', newTransform);- }- ```--3. **Handle Real-Time Updates** ([Performance - Batch Updates](#performance-issues))- ```javascript- processBatchPositionUpdates(positionUpdates) {- // Group updates to avoid excessive DOM manipulation- const batchSize = 10;- let currentBatch = 0;-- const processBatch = () => {- const start = currentBatch * batchSize;- const end = Math.min(start + batchSize, positionUpdates.length);-- for (let i = start; i < end; i++) {- const update = positionUpdates[i];- this.updateEntityPosition(update.entityId, update.position, update.animate);- }-- currentBatch++;-- if (end < positionUpdates.length) {- requestAnimationFrame(processBatch);- }- };-- processBatch();- }- ```--4. **Integration with Status Updates** ([Client-Server Integration](../entity-status-display.md#client-server-status-updates))- ```javascript- // Extend existing status polling to include position updates- class EnhancedStatusPoller extends StatusPoller {- constructor(svgElement) {- super();- this.positioner = new DynamicEntityPositioner(svgElement);- }-- updateEntityStates(statusData) {- // Handle standard status updates- super.updateEntityStates(statusData);-- // Handle position updates if included- if (statusData.positions) {- const positionUpdates = Object.entries(statusData.positions).map(- ([entityId, posData]) => ({- entityId,- position: posData.position,- animate: posData.animate !== false- })- );-- this.positioner.processBatchPositionUpdates(positionUpdates);- }- }- }- ```--**Expected Result**: Entities smoothly animate to new positions based on real-time data, with efficient batching and performance optimization.-------### Workflow 4: Troubleshooting Coordinate Transformation Issues--**Scenario**: After a template change, entity click detection stopped working, and zoom controls behave erratically.--**Systematic Debugging:**--1. **Diagnose Click Detection** ([Troubleshooting - Click Detection](#click-detection-not-working))- ```javascript- // Debug click detection step by step- function debugClickDetection(event) {- console.group('Click Detection Debug');-- // 1. Check if event reaches handler- console.log('Click event:', event);- console.log('Click target:', event.target);-- // 2. Check entity element selection- const entityElement = event.target.closest('[data-entity-id]');- console.log('Entity element found:', entityElement);-- if (entityElement) {- console.log('Entity ID:', entityElement.getAttribute('data-entity-id'));- }-- // 3. Test coordinate conversion- try {- const svgElement = document.getElementById('location-svg');- const handler = new SvgInteractionHandler(svgElement);- const svgCoords = handler.screenToSvgCoordinates(event.clientX, event.clientY);- console.log('SVG coordinates:', svgCoords);- } catch (error) {- console.error('Coordinate conversion failed:', error);- }-- console.groupEnd();- }-- // Temporarily attach debug handler- document.getElementById('location-svg').addEventListener('click', debugClickDetection);- ```--2. **Check SVG Structure** ([Template Integration](#template-integration))- ```javascript- function validateSvgStructure() {- const svg = document.getElementById('location-svg');- console.group('SVG Structure Validation');-- // Check required elements- console.log('SVG element:', svg);- console.log('Main group:', svg?.querySelector('#main-group'));- console.log('ViewBox:', svg?.getAttribute('viewBox'));- console.log('Entities with data-entity-id:', svg?.querySelectorAll('[data-entity-id]').length);-- // Check for common issues- const entitiesWithoutIds = svg?.querySelectorAll('.entity-group:not([data-entity-id])');- if (entitiesWithoutIds?.length > 0) {- console.warn('Entities missing data-entity-id:', entitiesWithoutIds);- }-- console.groupEnd();- }-- validateSvgStructure();- ```--3. **Test Coordinate Transformation Matrix** ([Troubleshooting - Transform Matrix](#entity-positions-incorrect))- ```javascript- function debugCoordinateTransformation() {- const svg = document.getElementById('location-svg');- console.group('Coordinate Transformation Debug');-- try {- // Test SVG DOM APIs- console.log('createSVGPoint available:', typeof svg.createSVGPoint === 'function');- console.log('getScreenCTM available:', typeof svg.getScreenCTM === 'function');-- // Test actual transformation- const ctm = svg.getScreenCTM();- console.log('Current CTM:', ctm);-- if (ctm) {- console.log('CTM values:', {- a: ctm.a, b: ctm.b, c: ctm.c,- d: ctm.d, e: ctm.e, f: ctm.f- });-- // Test point transformation- const testPoint = svg.createSVGPoint();- testPoint.x = 100;- testPoint.y = 100;-- const transformedPoint = testPoint.matrixTransform(ctm.inverse());- console.log('Test coordinate transformation:', {- screen: { x: 100, y: 100 },- svg: { x: transformedPoint.x, y: transformedPoint.y }- });- }-- } catch (error) {- console.error('Coordinate transformation error:', error);- }-- console.groupEnd();- }-- debugCoordinateTransformation();- ```--4. **Fix Common Issues** ([Common Fixes](#click-detection-not-working))- ```javascript- // Fix missing data-entity-id attributes- function fixMissingDataAttributes() {- const entitiesWithoutIds = document.querySelectorAll('.entity-group:not([data-entity-id])');-- entitiesWithoutIds.forEach((element, index) => {- // Generate temporary ID for debugging- const tempId = `temp-entity-${index}`;- element.setAttribute('data-entity-id', tempId);- console.warn(`Added temporary data-entity-id: ${tempId}`);- });- }-- // Reset viewport transformation if corrupted- function resetViewportTransform() {- const mainGroup = document.querySelector('#main-group');- if (mainGroup) {- mainGroup.setAttribute('transform', 'translate(0,0) scale(1)');- console.log('Reset viewport transform to default');- }- }-- // Apply fixes- fixMissingDataAttributes();- resetViewportTransform();- ```--**Expected Result**: Systematic debugging identifies and resolves coordinate transformation issues, restoring full functionality.--## Common Patterns Library--### Standard Coordinate Transformation Classes--#### Basic SVG Coordinate Transform-```javascript-// Standard class for coordinate system conversions-class SvgCoordinateTransform {- constructor(svgElement) {- this.svgElement = svgElement;- this.viewBox = this.parseViewBox(svgElement.getAttribute('viewBox'));- }-- parseViewBox(viewBoxStr) {- if (!viewBoxStr) return { x: 0, y: 0, width: 100, height: 100 };-- const [x, y, width, height] = viewBoxStr.split(' ').map(Number);- return { x, y, width, height };- }-- // Screen coordinates to SVG coordinates- screenToSvg(screenPoint) {- const rect = this.svgElement.getBoundingClientRect();- const svgPoint = this.svgElement.createSVGPoint();-- svgPoint.x = screenPoint.x - rect.left;- svgPoint.y = screenPoint.y - rect.top;-- return svgPoint.matrixTransform(- this.svgElement.getScreenCTM().inverse()- );- }-- // SVG coordinates to screen coordinates- svgToScreen(svgPoint) {- const screenPoint = svgPoint.matrixTransform(- this.svgElement.getScreenCTM()- );-- const rect = this.svgElement.getBoundingClientRect();- return {- x: screenPoint.x + rect.left,- y: screenPoint.y + rect.top- };- }-- // Entity local coordinates to SVG coordinates- entityToSvg(entityCoord, transform) {- const matrix = this.parseTransform(transform);- return {- x: entityCoord.x * matrix.scaleX + matrix.translateX,- y: entityCoord.y * matrix.scaleY + matrix.translateY- };- }-- parseTransform(transformStr) {- const translate = transformStr.match(/translate\(([^)]+)\)/);- const scale = transformStr.match(/scale\(([^)]+)\)/);- const rotate = transformStr.match(/rotate\(([^)]+)\)/);-- let translateX = 0, translateY = 0, scaleX = 1, scaleY = 1, rotation = 0;-- if (translate) {- [translateX, translateY] = translate[1].split(',').map(Number);- }-- if (scale) {- const scaleValues = scale[1].split(',').map(Number);- scaleX = scaleValues[0];- scaleY = scaleValues[1] || scaleX;- }-- if (rotate) {- rotation = Number(rotate[1]);- }-- return { translateX, translateY, scaleX, scaleY, rotation };- }-}-```--#### Standard SVG Interaction Handler-```javascript-// Standard class for handling SVG mouse and touch interactions-class SvgInteractionHandler {- constructor(svgElement, options = {}) {- this.svgElement = svgElement;- this.coordinateTransform = new SvgCoordinateTransform(svgElement);- this.isInteracting = false;- this.lastInteractionPoint = null;-- // Configuration options- this.options = {- enableClick: options.enableClick !== false,- enableDrag: options.enableDrag !== false,- clickThreshold: options.clickThreshold || 5,- ...options- };-- this.bindEvents();- }-- bindEvents() {- if (this.options.enableClick) {- this.svgElement.addEventListener('click', (e) => this.handleClick(e));- }-- if (this.options.enableDrag) {- this.svgElement.addEventListener('mousedown', (e) => this.handleMouseDown(e));- document.addEventListener('mousemove', (e) => this.handleMouseMove(e));- document.addEventListener('mouseup', (e) => this.handleMouseUp(e));-- // Touch events for mobile- this.svgElement.addEventListener('touchstart', (e) => this.handleTouchStart(e));- document.addEventListener('touchmove', (e) => this.handleTouchMove(e));- document.addEventListener('touchend', (e) => this.handleTouchEnd(e));- }- }-- handleClick(event) {- const svgPoint = this.coordinateTransform.screenToSvg({- x: event.clientX,- y: event.clientY- });-- const clickedElement = this.findEntityAt(svgPoint);- if (clickedElement) {- this.onEntityClick(clickedElement, svgPoint, event);- } else {- this.onBackgroundClick(svgPoint, event);- }- }-- findEntityAt(svgPoint) {- // Find the topmost entity element at the given SVG coordinate- const elements = document.elementsFromPoint(- svgPoint.x, svgPoint.y- ).filter(el =>- el.closest('[data-entity-id]') &&- el.closest('svg') === this.svgElement- );-- return elements.length > 0 ? elements[0].closest('[data-entity-id]') : null;- }-- onEntityClick(entityElement, svgPoint, originalEvent) {- const entityId = entityElement.getAttribute('data-entity-id');- const entityType = entityElement.getAttribute('data-entity-type');-- // Emit custom event- this.svgElement.dispatchEvent(new CustomEvent('entityClick', {- detail: {- entityId,- entityType,- svgCoordinates: svgPoint,- screenCoordinates: { x: originalEvent.clientX, y: originalEvent.clientY },- element: entityElement- }- }));- }-- onBackgroundClick(svgPoint, originalEvent) {- this.svgElement.dispatchEvent(new CustomEvent('backgroundClick', {- detail: {- svgCoordinates: svgPoint,- screenCoordinates: { x: originalEvent.clientX, y: originalEvent.clientY }- }- }));- }-- // Touch event handling- handleTouchStart(event) {- if (event.touches.length === 1) {- const touch = event.touches[0];- this.handleMouseDown({- clientX: touch.clientX,- clientY: touch.clientY,- target: event.target,- preventDefault: () => event.preventDefault()- });- }- }-- handleTouchMove(event) {- if (event.touches.length === 1) {- const touch = event.touches[0];- this.handleMouseMove({- clientX: touch.clientX,- clientY: touch.clientY- });- }- }-- handleTouchEnd(event) {- this.handleMouseUp({});- }-}-```--#### Standard Viewport Controller-```javascript-// Standard class for managing SVG zoom and pan operations-class SvgViewportController {- constructor(svgElement, options = {}) {- this.svgElement = svgElement;- this.currentTransform = { scale: 1, translateX: 0, translateY: 0 };- this.originalViewBox = this.parseViewBox(svgElement.getAttribute('viewBox'));-- this.options = {- minScale: options.minScale || 0.1,- maxScale: options.maxScale || 10,- zoomSpeed: options.zoomSpeed || 0.1,- enablePan: options.enablePan !== false,- enableZoom: options.enableZoom !== false,- ...options- };-- this.bindEvents();- }-- parseViewBox(viewBoxStr) {- if (!viewBoxStr) return { x: 0, y: 0, width: 100, height: 100 };- const [x, y, width, height] = viewBoxStr.split(' ').map(Number);- return { x, y, width, height };- }-- bindEvents() {- if (this.options.enableZoom) {- this.svgElement.addEventListener('wheel', (e) => this.handleWheel(e));- }-- if (this.options.enablePan) {- let isPanning = false;- let startPoint = null;- let startTransform = null;-- this.svgElement.addEventListener('mousedown', (e) => {- if (e.button === 1 || (e.button === 0 && e.ctrlKey)) { // Middle mouse or Ctrl+click- isPanning = true;- startPoint = { x: e.clientX, y: e.clientY };- startTransform = { ...this.currentTransform };- e.preventDefault();- }- });-- document.addEventListener('mousemove', (e) => {- if (isPanning && startPoint) {- const dx = (e.clientX - startPoint.x) / this.currentTransform.scale;- const dy = (e.clientY - startPoint.y) / this.currentTransform.scale;-- this.currentTransform.translateX = startTransform.translateX + dx;- this.currentTransform.translateY = startTransform.translateY + dy;-- this.updateViewBox();- e.preventDefault();- }- });-- document.addEventListener('mouseup', (e) => {- if (isPanning) {- isPanning = false;- startPoint = null;- startTransform = null;- }- });- }- }-- handleWheel(event) {- event.preventDefault();-- const rect = this.svgElement.getBoundingClientRect();- const centerX = (event.clientX - rect.left) / rect.width;- const centerY = (event.clientY - rect.top) / rect.height;-- const scaleDelta = event.deltaY > 0 ?- (1 - this.options.zoomSpeed) :- (1 + this.options.zoomSpeed);-- this.zoomAt(centerX, centerY, scaleDelta);- }-- zoomAt(centerX, centerY, scaleDelta) {- const newScale = Math.max(- this.options.minScale,- Math.min(this.options.maxScale, this.currentTransform.scale * scaleDelta)- );-- if (newScale !== this.currentTransform.scale) {- // Calculate new translation to keep zoom centered- const scaleChange = newScale / this.currentTransform.scale;-- const viewBoxCenterX = this.originalViewBox.x + centerX * this.originalViewBox.width;- const viewBoxCenterY = this.originalViewBox.y + centerY * this.originalViewBox.height;-- this.currentTransform.translateX = viewBoxCenterX -- (viewBoxCenterX - this.currentTransform.translateX) * scaleChange;- this.currentTransform.translateY = viewBoxCenterY -- (viewBoxCenterY - this.currentTransform.translateY) * scaleChange;-- this.currentTransform.scale = newScale;- this.updateViewBox();- }- }-- updateViewBox() {- const width = this.originalViewBox.width / this.currentTransform.scale;- const height = this.originalViewBox.height / this.currentTransform.scale;-- const x = this.currentTransform.translateX - width / 2;- const y = this.currentTransform.translateY - height / 2;-- this.svgElement.setAttribute('viewBox', `${x} ${y} ${width} ${height}`);-- // Emit transform change event- this.svgElement.dispatchEvent(new CustomEvent('viewportChanged', {- detail: {- scale: this.currentTransform.scale,- translateX: this.currentTransform.translateX,- translateY: this.currentTransform.translateY,- viewBox: { x, y, width, height }- }- }));- }-- // Public API methods- zoomIn() {- this.zoomAt(0.5, 0.5, 1 + this.options.zoomSpeed);- }-- zoomOut() {- this.zoomAt(0.5, 0.5, 1 - this.options.zoomSpeed);- }-- resetView() {- this.currentTransform = { scale: 1, translateX: 0, translateY: 0 };- this.svgElement.setAttribute('viewBox',- `${this.originalViewBox.x} ${this.originalViewBox.y} ${this.originalViewBox.width} ${this.originalViewBox.height}`- );- this.updateViewBox();- }-- fitToContent() {- // Calculate bounding box of all visible entities- const entities = this.svgElement.querySelectorAll('[data-entity-id]');- if (entities.length === 0) return;-- let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;-- entities.forEach(entity => {- const bbox = entity.getBBox();- minX = Math.min(minX, bbox.x);- minY = Math.min(minY, bbox.y);- maxX = Math.max(maxX, bbox.x + bbox.width);- maxY = Math.max(maxY, bbox.y + bbox.height);- });-- const padding = Math.min(maxX - minX, maxY - minY) * 0.1;- const contentWidth = maxX - minX + padding * 2;- const contentHeight = maxY - minY + padding * 2;-- this.svgElement.setAttribute('viewBox',- `${minX - padding} ${minY - padding} ${contentWidth} ${contentHeight}`- );- }-}-```--### Standard Entity Positioning Patterns--#### Entity Position Manager-```javascript-// Standard class for managing entity positions and transforms-class EntityPositionManager {- constructor(svgElement) {- this.svgElement = svgElement;- this.coordinateTransform = new SvgCoordinateTransform(svgElement);- }-- updateEntityPosition(entityId, position, options = {}) {- const entityElement = this.svgElement.querySelector(- `[data-entity-id="${entityId}"]`- );-- if (!entityElement) {- console.warn(`Entity ${entityId} not found in SVG`);- return;- }-- const transform = this.buildTransform(position, options);- const targetElement = entityElement.querySelector('use, path') || entityElement;-- if (options.animate) {- this.animateTransform(targetElement, transform, options.duration || 300);- } else {- targetElement.setAttribute('transform', transform);- }-- // Update data attributes for tracking- entityElement.setAttribute('data-x', position.x);- entityElement.setAttribute('data-y', position.y);- if (position.scale) entityElement.setAttribute('data-scale', position.scale);- if (position.rotation) entityElement.setAttribute('data-rotation', position.rotation);- }-- buildTransform(position, options = {}) {- const { x, y, scale = 1, rotation = 0 } = position;- const transforms = [];-- transforms.push(`translate(${x}, ${y})`);-- if (scale !== 1) {- transforms.push(`scale(${scale})`);- }-- if (rotation !== 0) {- transforms.push(`rotate(${rotation})`);- }-- return transforms.join(' ');- }-- animateTransform(element, newTransform, duration) {- const currentTransform = element.getAttribute('transform') || '';-- // Create animation element- const animateTransform = document.createElementNS(- 'http://www.w3.org/2000/svg',- 'animateTransform'- );-- animateTransform.setAttribute('attributeName', 'transform');- animateTransform.setAttribute('attributeType', 'XML');- animateTransform.setAttribute('type', 'transform');- animateTransform.setAttribute('from', currentTransform);- animateTransform.setAttribute('to', newTransform);- animateTransform.setAttribute('dur', `${duration}ms`);- animateTransform.setAttribute('fill', 'freeze');-- element.appendChild(animateTransform);-- // Clean up animation after completion- setTimeout(() => {- element.setAttribute('transform', newTransform);- if (animateTransform.parentNode) {- animateTransform.parentNode.removeChild(animateTransform);- }- }, duration);- }-- getEntityPosition(entityId) {- const entityElement = this.svgElement.querySelector(- `[data-entity-id="${entityId}"]`- );-- if (!entityElement) return null;-- return {- x: parseFloat(entityElement.getAttribute('data-x')) || 0,- y: parseFloat(entityElement.getAttribute('data-y')) || 0,- scale: parseFloat(entityElement.getAttribute('data-scale')) || 1,- rotation: parseFloat(entityElement.getAttribute('data-rotation')) || 0- };- }-- moveEntity(entityId, deltaX, deltaY, options = {}) {- const currentPosition = this.getEntityPosition(entityId);- if (!currentPosition) return;-- const newPosition = {- ...currentPosition,- x: currentPosition.x + deltaX,- y: currentPosition.y + deltaY- };-- this.updateEntityPosition(entityId, newPosition, options);- }-- scaleEntity(entityId, scaleFactor, options = {}) {- const currentPosition = this.getEntityPosition(entityId);- if (!currentPosition) return;-- const newPosition = {- ...currentPosition,- scale: currentPosition.scale * scaleFactor- };-- this.updateEntityPosition(entityId, newPosition, options);- }-}-```--### Standard Template Integration Patterns--#### Basic SVG Template Structure-```django-<!-- Standard SVG structure for location views -->-<div class="location-view-container">- <svg id="location-svg"- class="location-view-svg"- viewBox="{{ viewbox.x }} {{ viewbox.y }} {{ viewbox.width }} {{ viewbox.height }}"- xmlns="http://www.w3.org/2000/svg">-- <!-- Background layers -->- <defs>- <!-- Entity icon definitions -->- {% for entity_type in entity_types_with_icons %}- <symbol id="icon-{{ entity_type.name.lower }}"- viewBox="{{ entity_type.get_viewbox }}">- {% include entity_type.get_icon_template %}- </symbol>- {% endfor %}-- <!-- Common patterns and gradients -->- <pattern id="grid-pattern" patternUnits="userSpaceOnUse" width="10" height="10">- <path d="M 10 0 L 0 0 0 10" fill="none" stroke="#e0e0e0" stroke-width="0.5"/>- </pattern>- </defs>-- <!-- Background grid (optional) -->- {% if show_grid %}- <rect width="100%" height="100%" fill="url(#grid-pattern)"/>- {% endif %}-- <!-- Floor plan background -->- {% if location.background_image %}- <image href="{{ location.background_image.url }}"- width="{{ viewbox.width }}"- height="{{ viewbox.height }}"/>- {% endif %}-- <!-- Path-based entities (rooms, zones) -->- {% for entity in path_entities %}- <g class="entity-group"- data-entity-id="{{ entity.id }}"- data-entity-type="{{ entity.entity_type.name.lower }}">- <path class="entity-path {{ entity.get_status_css_classes|join:' ' }}"- d="{{ entity.path.svg_path }}"- style="{{ entity.get_path_styling }}"/>- </g>- {% endfor %}-- <!-- Icon-based entities (sensors, devices) -->- {% for entity in positioned_entities %}- <g class="entity-group"- data-entity-id="{{ entity.id }}"- data-entity-type="{{ entity.entity_type.name.lower }}">- <use href="#icon-{{ entity.entity_type.name.lower }}"- class="entity-svg {{ entity.get_status_css_classes|join:' ' }}"- transform="translate({{ entity.position.x }}, {{ entity.position.y }})- scale({{ entity.position.scale|default:1.0 }})- rotate({{ entity.position.rotation|default:0 }})"/>- </g>- {% endfor %}-- <!-- Overlay elements -->- <g class="overlay-group">- <!-- Selection indicators -->- <circle id="selection-indicator"- class="selection-circle"- r="25"- fill="none"- stroke="#007bff"- stroke-width="2"- style="display: none"/>-- <!-- Temporary drawing elements -->- <g id="temp-drawings"></g>- </g>- </svg>-- <!-- SVG Controls -->- <div class="svg-controls">- <button id="zoom-in" class="btn btn-sm btn-outline-secondary">- <i class="fas fa-search-plus"></i>- </button>- <button id="zoom-out" class="btn btn-sm btn-outline-secondary">- <i class="fas fa-search-minus"></i>- </button>- <button id="fit-content" class="btn btn-sm btn-outline-secondary">- <i class="fas fa-expand-arrows-alt"></i>- </button>- <button id="reset-view" class="btn btn-sm btn-outline-secondary">- <i class="fas fa-home"></i>- </button>- </div>-</div>-```--#### Standard JavaScript Initialization-```javascript-// Standard pattern for initializing SVG coordinate operations-document.addEventListener('DOMContentLoaded', function() {- const svgElement = document.getElementById('location-svg');- if (!svgElement) return;-- // Initialize coordinate systems- const coordinateTransform = new SvgCoordinateTransform(svgElement);- const interactionHandler = new SvgInteractionHandler(svgElement, {- enableClick: true,- enableDrag: false- });- const viewportController = new SvgViewportController(svgElement, {- minScale: 0.1,- maxScale: 5.0,- enablePan: true,- enableZoom: true- });- const positionManager = new EntityPositionManager(svgElement);-- // Bind control buttons- document.getElementById('zoom-in')?.addEventListener('click', () => {- viewportController.zoomIn();- });-- document.getElementById('zoom-out')?.addEventListener('click', () => {- viewportController.zoomOut();- });-- document.getElementById('fit-content')?.addEventListener('click', () => {- viewportController.fitToContent();- });-- document.getElementById('reset-view')?.addEventListener('click', () => {- viewportController.resetView();- });-- // Handle entity interactions- svgElement.addEventListener('entityClick', function(event) {- const { entityId, svgCoordinates, element } = event.detail;-- // Show selection indicator- const indicator = document.getElementById('selection-indicator');- indicator.setAttribute('cx', svgCoordinates.x);- indicator.setAttribute('cy', svgCoordinates.y);- indicator.style.display = 'block';-- // Open entity details modal- openEntityDetailsModal(entityId);- });-- svgElement.addEventListener('backgroundClick', function(event) {- // Hide selection indicator- document.getElementById('selection-indicator').style.display = 'none';- });-- // Handle viewport changes- svgElement.addEventListener('viewportChanged', function(event) {- const { scale, translateX, translateY } = event.detail;-- // Update scale-dependent elements- updateScaleDependentElements(scale);-- // Trigger entity visibility updates if needed- updateEntityVisibility(event.detail.viewBox);- });-- // Store references globally for debugging- window.svgCoordinateTransform = coordinateTransform;- window.svgInteractionHandler = interactionHandler;- window.svgViewportController = viewportController;- window.entityPositionManager = positionManager;-});--// Utility functions-function openEntityDetailsModal(entityId) {- // Standard modal opening pattern- fetch(`/entity/${entityId}/details/`)- .then(response => response.json())- .then(data => {- if (data.modal) {- showModal(data.modal);- }- })- .catch(error => {- console.error('Error loading entity details:', error);- });-}--function updateScaleDependentElements(scale) {- // Adjust element sizes based on zoom level- const scaleDependentElements = document.querySelectorAll('.scale-dependent');- scaleDependentElements.forEach(element => {- const baseSize = parseFloat(element.getAttribute('data-base-size')) || 1;- const newSize = Math.max(0.5, baseSize / scale);- element.setAttribute('stroke-width', newSize);- });-}--function updateEntityVisibility(viewBox) {- // Hide entities outside visible area for performance- const entities = document.querySelectorAll('[data-entity-id]');- entities.forEach(entity => {- const bbox = entity.getBBox();- const isVisible = !(- bbox.x + bbox.width < viewBox.x ||- bbox.x > viewBox.x + viewBox.width ||- bbox.y + bbox.height < viewBox.y ||- bbox.y > viewBox.y + viewBox.height- );-- entity.style.display = isVisible ? 'block' : 'none';- });-}-```--### Standard Testing Patterns for Coordinate Operations--#### Coordinate Conversion Testing-```javascript-// Standard test patterns for coordinate transformations-function testCoordinateConversions() {- const svg = document.getElementById('location-svg');- const transform = new SvgCoordinateTransform(svg);-- // Test screen to SVG conversion- const screenPoint = { x: 100, y: 50 };- const svgPoint = transform.screenToSvg(screenPoint);- console.assert(typeof svgPoint.x === 'number', 'SVG X coordinate should be number');- console.assert(typeof svgPoint.y === 'number', 'SVG Y coordinate should be number');-- // Test round-trip conversion- const backToScreen = transform.svgToScreen(svgPoint);- const tolerance = 1; // 1 pixel tolerance- console.assert(- Math.abs(backToScreen.x - screenPoint.x) < tolerance,- 'Round-trip X conversion failed'- );- console.assert(- Math.abs(backToScreen.y - screenPoint.y) < tolerance,- 'Round-trip Y conversion failed'- );-- console.log('Coordinate conversion tests passed');-}--function testViewportOperations() {- const svg = document.getElementById('location-svg');- const viewport = new SvgViewportController(svg);-- const originalViewBox = svg.getAttribute('viewBox');-- // Test zoom operations- viewport.zoomIn();- const zoomedViewBox = svg.getAttribute('viewBox');- console.assert(zoomedViewBox !== originalViewBox, 'Zoom in should change viewBox');-- viewport.resetView();- const resetViewBox = svg.getAttribute('viewBox');- console.assert(resetViewBox === originalViewBox, 'Reset should restore original viewBox');-- console.log('Viewport operation tests passed');-}--function testEntityPositioning() {- const svg = document.getElementById('location-svg');- const positionManager = new EntityPositionManager(svg);-- // Create test entity- const testEntityHtml = `- <g data-entity-id="test-entity" class="entity-group">- <use href="#icon-motion-sensor" class="entity-svg"/>- </g>- `;- svg.innerHTML += testEntityHtml;-- // Test position update- const newPosition = { x: 100, y: 150, scale: 1.5, rotation: 45 };- positionManager.updateEntityPosition('test-entity', newPosition);-- // Verify position was applied- const retrievedPosition = positionManager.getEntityPosition('test-entity');- console.assert(retrievedPosition.x === 100, 'X position not set correctly');- console.assert(retrievedPosition.y === 150, 'Y position not set correctly');- console.assert(retrievedPosition.scale === 1.5, 'Scale not set correctly');- console.assert(retrievedPosition.rotation === 45, 'Rotation not set correctly');-- console.log('Entity positioning tests passed');-}-```--#### Performance Testing Pattern-```javascript-// Standard performance testing for coordinate operations-function performanceTestCoordinateOperations() {- const svg = document.getElementById('location-svg');- const transform = new SvgCoordinateTransform(svg);-- const testPoints = [];- for (let i = 0; i < 1000; i++) {- testPoints.push({- x: Math.random() * window.innerWidth,- y: Math.random() * window.innerHeight- });- }-- // Test coordinate conversion performance- console.time('1000 screen-to-SVG conversions');- testPoints.forEach(point => {- transform.screenToSvg(point);- });- console.timeEnd('1000 screen-to-SVG conversions');-- // Test entity positioning performance- const positionManager = new EntityPositionManager(svg);- const positions = testPoints.map(point => ({- x: point.x,- y: point.y,- scale: 1 + Math.random(),- rotation: Math.random() * 360- }));-- console.time('1000 entity position updates');- positions.forEach((position, index) => {- positionManager.updateEntityPosition(`entity-${index}`, position);- });- console.timeEnd('1000 entity position updates');-- console.log('Performance tests completed');-}-```--## Performance Optimization Guide--### Overview--SVG coordinate operations can become computationally expensive with complex transformations, frequent updates, or large numbers of entities. This guide provides optimization strategies for maintaining smooth, responsive coordinate operations.--### Coordinate Transformation Optimization--#### Caching Transformation Matrices-```javascript-// Cache expensive matrix calculations-class OptimizedCoordinateTransform extends SvgCoordinateTransform {- constructor(svgElement) {- super(svgElement);- this.matrixCache = new Map();- this.cacheHitCount = 0;- this.cacheMissCount = 0;- }-- getScreenCTM() {- const cacheKey = this.generateMatrixCacheKey();-- if (this.matrixCache.has(cacheKey)) {- this.cacheHitCount++;- return this.matrixCache.get(cacheKey);- }-- const matrix = this.svgElement.getScreenCTM();- this.matrixCache.set(cacheKey, matrix);- this.cacheMissCount++;-- // Limit cache size to prevent memory leaks- if (this.matrixCache.size > 100) {- const firstKey = this.matrixCache.keys().next().value;- this.matrixCache.delete(firstKey);- }-- return matrix;- }-- generateMatrixCacheKey() {- const viewBox = this.svgElement.getAttribute('viewBox');- const transform = this.svgElement.getAttribute('transform') || '';- const boundingRect = this.svgElement.getBoundingClientRect();-- return `${viewBox}|${transform}|${boundingRect.width}x${boundingRect.height}`;- }-- invalidateCache() {- this.matrixCache.clear();- }-- getCacheStats() {- const totalRequests = this.cacheHitCount + this.cacheMissCount;- const hitRate = totalRequests > 0 ? (this.cacheHitCount / totalRequests) * 100 : 0;-- return {- hits: this.cacheHitCount,- misses: this.cacheMissCount,- hitRate: hitRate.toFixed(1) + '%',- cacheSize: this.matrixCache.size- };- }-}-```--#### Optimized Batch Coordinate Conversions-```javascript-// Process multiple coordinates efficiently-class BatchCoordinateProcessor {- constructor(svgElement) {- this.svgElement = svgElement;- this.transform = new OptimizedCoordinateTransform(svgElement);- }-- batchScreenToSvg(screenPoints) {- const results = [];- const matrix = this.transform.getScreenCTM()?.inverse();-- if (!matrix) {- return screenPoints.map(p => ({ x: p.x, y: p.y }));- }-- const rect = this.svgElement.getBoundingClientRect();-- // Process all points using the same matrix- for (const point of screenPoints) {- const svgPoint = this.svgElement.createSVGPoint();- svgPoint.x = point.x - rect.left;- svgPoint.y = point.y - rect.top;-- const transformed = svgPoint.matrixTransform(matrix);- results.push({ x: transformed.x, y: transformed.y });- }-- return results;- }-- batchSvgToScreen(svgPoints) {- const results = [];- const matrix = this.transform.getScreenCTM();-- if (!matrix) {- return svgPoints;- }-- const rect = this.svgElement.getBoundingClientRect();-- // Process all points using the same matrix- for (const point of svgPoints) {- const svgPoint = this.svgElement.createSVGPoint();- svgPoint.x = point.x;- svgPoint.y = point.y;-- const transformed = svgPoint.matrixTransform(matrix);- results.push({- x: transformed.x + rect.left,- y: transformed.y + rect.top- });- }-- return results;- }-- // Optimized bulk entity position updates- updateEntityPositions(entityUpdates) {- const startTime = performance.now();-- // Group updates by transformation type- const transformGroups = this.groupTransformations(entityUpdates);-- // Process each group efficiently- Object.entries(transformGroups).forEach(([transformType, entities]) => {- this.processTransformGroup(transformType, entities);- });-- const endTime = performance.now();- console.log(`Batch position update: ${entityUpdates.length} entities in ${(endTime - startTime).toFixed(2)}ms`);- }-- groupTransformations(entityUpdates) {- const groups = {};-- entityUpdates.forEach(update => {- const key = `${update.scale || 1}_${update.rotation || 0}`;- if (!groups[key]) {- groups[key] = [];- }- groups[key].push(update);- });-- return groups;- }-- processTransformGroup(transformType, entities) {- // Apply same transformation parameters to multiple entities- entities.forEach(entity => {- const element = document.querySelector(`[data-entity-id="${entity.id}"]`);- if (element) {- const transform = `translate(${entity.x}, ${entity.y})`;- const targetElement = element.querySelector('use, path') || element;- targetElement.setAttribute('transform', transform);- }- });- }-}-```--### Viewport Operation Performance--#### Optimized Viewport Controller-```javascript-// High-performance viewport operations-class PerformantViewportController extends SvgViewportController {- constructor(svgElement, options = {}) {- super(svgElement, options);- this.updateThrottle = options.updateThrottle || 16; // ~60fps- this.lastUpdateTime = 0;- this.pendingUpdate = null;- this.performanceMode = this.detectPerformanceMode();- }-- detectPerformanceMode() {- // Detect if we need to use performance mode- const entityCount = this.svgElement.querySelectorAll('[data-entity-id]').length;- const isLowEndDevice = navigator.hardwareConcurrency < 4;- const hasLimitedMemory = navigator.deviceMemory && navigator.deviceMemory < 4;-- return entityCount > 100 || isLowEndDevice || hasLimitedMemory;- }-- updateViewBox() {- const now = performance.now();-- // Throttle updates to prevent excessive redraws- if (now - this.lastUpdateTime < this.updateThrottle) {- if (this.pendingUpdate) {- cancelAnimationFrame(this.pendingUpdate);- }-- this.pendingUpdate = requestAnimationFrame(() => {- this.performViewBoxUpdate();- });- return;- }-- this.performViewBoxUpdate();- }-- performViewBoxUpdate() {- this.lastUpdateTime = performance.now();-- const width = this.originalViewBox.width / this.currentTransform.scale;- const height = this.originalViewBox.height / this.currentTransform.scale;-- const x = this.currentTransform.translateX - width / 2;- const y = this.currentTransform.translateY - height / 2;-- // Use CSS transforms for better performance if supported- if (this.performanceMode && this.supportsCSSTransforms()) {- this.applyCSSTransform();- } else {- this.svgElement.setAttribute('viewBox', `${x} ${y} ${width} ${height}`);- }-- // Emit transform change event (throttled)- this.emitThrottledViewportEvent();- }-- supportsCSSTransforms() {- return CSS.supports('transform', 'scale(1) translate(0px, 0px)');- }-- applyCSSTransform() {- const scale = this.currentTransform.scale;- const translateX = -this.currentTransform.translateX * scale;- const translateY = -this.currentTransform.translateY * scale;-- this.svgElement.style.transform =- `scale(${scale}) translate(${translateX}px, ${translateY}px)`;- }-- emitThrottledViewportEvent() {- // Only emit events at most once per frame- if (!this.eventPending) {- this.eventPending = true;-- requestAnimationFrame(() => {- this.svgElement.dispatchEvent(new CustomEvent('viewportChanged', {- detail: {- scale: this.currentTransform.scale,- translateX: this.currentTransform.translateX,- translateY: this.currentTransform.translateY,- viewBox: this.getCurrentViewBox()- }- }));- this.eventPending = false;- });- }- }-- // Optimized zoom operation- zoomAt(centerX, centerY, scaleDelta) {- // Pre-calculate to avoid expensive operations during zoom- const newScale = this.clampScale(this.currentTransform.scale * scaleDelta);-- if (newScale === this.currentTransform.scale) {- return; // No change needed- }-- // Use efficient transform calculation- this.updateTransformOptimized(centerX, centerY, newScale);-- if (this.performanceMode) {- // In performance mode, defer heavy operations- this.deferHeavyOperations();- } else {- this.updateViewBox();- }- }-- clampScale(scale) {- return Math.max(- this.options.minScale,- Math.min(this.options.maxScale, scale)- );- }-- updateTransformOptimized(centerX, centerY, newScale) {- // Optimized transform calculation- const scaleChange = newScale / this.currentTransform.scale;-- const viewBoxCenterX = this.originalViewBox.x + centerX * this.originalViewBox.width;- const viewBoxCenterY = this.originalViewBox.y + centerY * this.originalViewBox.height;-- // Update transform in one operation- this.currentTransform.translateX = viewBoxCenterX -- (viewBoxCenterX - this.currentTransform.translateX) * scaleChange;- this.currentTransform.translateY = viewBoxCenterY -- (viewBoxCenterY - this.currentTransform.translateY) * scaleChange;- this.currentTransform.scale = newScale;- }-- deferHeavyOperations() {- // Defer expensive operations until zoom is complete- clearTimeout(this.deferredOperationsTimeout);- this.deferredOperationsTimeout = setTimeout(() => {- this.updateViewBox();- this.updateEntityVisibility();- }, 100);- }-}-```--### Entity Positioning Performance--#### High-Performance Entity Position Manager-```javascript-// Optimized entity positioning with spatial indexing-class PerformantEntityPositionManager extends EntityPositionManager {- constructor(svgElement) {- super(svgElement);- this.spatialIndex = new SpatialIndex();- this.positionCache = new Map();- this.updateQueue = [];- this.isProcessingQueue = false;- }-- // Spatial indexing for efficient entity queries- buildSpatialIndex() {- this.spatialIndex.clear();-- const entities = this.svgElement.querySelectorAll('[data-entity-id]');- entities.forEach(entity => {- const entityId = entity.getAttribute('data-entity-id');- const position = this.getEntityPosition(entityId);-- if (position) {- this.spatialIndex.insert({- id: entityId,- x: position.x,- y: position.y,- width: 32, // Assume standard entity size- height: 32- });- }- });- }-- // Queue position updates for batch processing- queuePositionUpdate(entityId, position, options = {}) {- this.updateQueue.push({ entityId, position, options });-- if (!this.isProcessingQueue) {- this.processUpdateQueue();- }- }-- async processUpdateQueue() {- this.isProcessingQueue = true;-- while (this.updateQueue.length > 0) {- const batch = this.updateQueue.splice(0, 20); // Process 20 at a time-- // Process batch synchronously for better performance- batch.forEach(update => {- this.updateEntityPositionImmediate(- update.entityId,- update.position,- update.options- );- });-- // Yield control periodically- if (this.updateQueue.length > 0) {- await new Promise(resolve => setTimeout(resolve, 0));- }- }-- this.isProcessingQueue = false;- }-- updateEntityPositionImmediate(entityId, position, options = {}) {- const element = this.svgElement.querySelector(`[data-entity-id="${entityId}"]`);-- if (!element) {- return;- }-- // Use cached transform calculation when possible- const transformString = this.getCachedTransform(position) ||- this.buildTransform(position, options);-- const targetElement = element.querySelector('use, path') || element;-- if (options.animate && !this.performanceMode) {- this.animateTransform(targetElement, transformString, options.duration || 300);- } else {- // Direct attribute update is faster than animation- targetElement.setAttribute('transform', transformString);- }-- // Update position cache- this.positionCache.set(entityId, position);-- // Update spatial index- this.spatialIndex.update(entityId, position);- }-- getCachedTransform(position) {- const cacheKey = `${position.x}_${position.y}_${position.scale || 1}_${position.rotation || 0}`;- return this.transformCache?.get(cacheKey);- }-- // Efficient entity queries using spatial indexing- getEntitiesInRegion(x, y, width, height) {- return this.spatialIndex.query(x, y, width, height);- }-- getNearestEntities(x, y, maxDistance = 50, limit = 10) {- return this.spatialIndex.queryNearest(x, y, maxDistance, limit);- }-- // Bulk position updates with optimizations- updateMultipleEntityPositions(positionUpdates) {- const startTime = performance.now();-- // Sort updates to minimize DOM access patterns- positionUpdates.sort((a, b) => a.entityId.localeCompare(b.entityId));-- // Disable transitions during bulk update- this.disableTransitions();-- positionUpdates.forEach(update => {- this.updateEntityPositionImmediate(update.entityId, update.position);- });-- // Re-enable transitions- this.enableTransitions();-- // Update spatial index in batch- this.spatialIndex.batchUpdate(positionUpdates);-- const endTime = performance.now();- console.log(`Bulk position update: ${positionUpdates.length} entities in ${(endTime - startTime).toFixed(2)}ms`);- }-- disableTransitions() {- const style = document.createElement('style');- style.id = 'disable-entity-transitions';- style.textContent = '.entity-svg, .entity-path { transition: none !important; }';- document.head.appendChild(style);- }-- enableTransitions() {- const style = document.getElementById('disable-entity-transitions');- if (style) {- style.remove();- }- }-}-```--### Spatial Indexing for Performance--#### Efficient Spatial Data Structure-```javascript-// Simple spatial index for entity queries-class SpatialIndex {- constructor(cellSize = 100) {- this.cellSize = cellSize;- this.cells = new Map();- this.entityLocations = new Map();- }-- insert(entity) {- const cellKey = this.getCellKey(entity.x, entity.y);-- if (!this.cells.has(cellKey)) {- this.cells.set(cellKey, new Set());- }-- this.cells.get(cellKey).add(entity.id);- this.entityLocations.set(entity.id, { cellKey, ...entity });- }-- update(entityId, newPosition) {- const oldLocation = this.entityLocations.get(entityId);-- if (oldLocation) {- // Remove from old cell- const oldCell = this.cells.get(oldLocation.cellKey);- if (oldCell) {- oldCell.delete(entityId);- if (oldCell.size === 0) {- this.cells.delete(oldLocation.cellKey);- }- }- }-- // Add to new cell- const newCellKey = this.getCellKey(newPosition.x, newPosition.y);- if (!this.cells.has(newCellKey)) {- this.cells.set(newCellKey, new Set());- }-- this.cells.get(newCellKey).add(entityId);- this.entityLocations.set(entityId, { cellKey: newCellKey, ...newPosition });- }-- query(x, y, width, height) {- const entities = new Set();-- const minCellX = Math.floor(x / this.cellSize);- const maxCellX = Math.floor((x + width) / this.cellSize);- const minCellY = Math.floor(y / this.cellSize);- const maxCellY = Math.floor((y + height) / this.cellSize);-- for (let cellX = minCellX; cellX <= maxCellX; cellX++) {- for (let cellY = minCellY; cellY <= maxCellY; cellY++) {- const cellKey = `${cellX},${cellY}`;- const cell = this.cells.get(cellKey);-- if (cell) {- cell.forEach(entityId => entities.add(entityId));- }- }- }-- return Array.from(entities);- }-- queryNearest(x, y, maxDistance, limit = 10) {- const candidates = [];- const searchRadius = Math.ceil(maxDistance / this.cellSize);-- const centerCellX = Math.floor(x / this.cellSize);- const centerCellY = Math.floor(y / this.cellSize);-- // Search in expanding squares- for (let radius = 0; radius <= searchRadius; radius++) {- for (let dx = -radius; dx <= radius; dx++) {- for (let dy = -radius; dy <= radius; dy++) {- if (Math.abs(dx) === radius || Math.abs(dy) === radius) {- const cellKey = `${centerCellX + dx},${centerCellY + dy}`;- const cell = this.cells.get(cellKey);-- if (cell) {- cell.forEach(entityId => {- const entity = this.entityLocations.get(entityId);- if (entity) {- const distance = Math.sqrt(- Math.pow(entity.x - x, 2) + Math.pow(entity.y - y, 2)- );-- if (distance <= maxDistance) {- candidates.push({ entityId, distance });- }- }- });- }- }- }- }-- // Early exit if we have enough candidates- if (candidates.length >= limit * 2) {- break;- }- }-- // Sort by distance and return top results- return candidates- .sort((a, b) => a.distance - b.distance)- .slice(0, limit)- .map(c => c.entityId);- }-- getCellKey(x, y) {- const cellX = Math.floor(x / this.cellSize);- const cellY = Math.floor(y / this.cellSize);- return `${cellX},${cellY}`;- }-- clear() {- this.cells.clear();- this.entityLocations.clear();- }-- batchUpdate(updates) {- // Disable individual updates during batch- const oldUpdate = this.update;- this.update = () => {}; // No-op during batch-- updates.forEach(update => {- oldUpdate.call(this, update.entityId, update.position);- });-- // Restore update function- this.update = oldUpdate;- }-}-```--### Interaction Performance Optimization--#### Optimized Event Handling-```javascript-// High-performance SVG interaction handling-class PerformantInteractionHandler extends SvgInteractionHandler {- constructor(svgElement, options = {}) {- super(svgElement, options);- this.eventThrottle = options.eventThrottle || 10; // 100fps max- this.lastEventTime = 0;- this.eventCache = new Map();- this.spatialIndex = new SpatialIndex();- }-- handleClick(event) {- // Throttle click events to prevent spam- const now = performance.now();- if (now - this.lastEventTime < this.eventThrottle) {- return;- }- this.lastEventTime = now;-- const svgPoint = this.coordinateTransform.screenToSvg({- x: event.clientX,- y: event.clientY- });-- // Use spatial index for faster entity lookup- const nearbyEntities = this.spatialIndex.queryNearest(- svgPoint.x, svgPoint.y, 50, 5- );-- let clickedElement = null;- for (const entityId of nearbyEntities) {- const element = document.querySelector(`[data-entity-id="${entityId}"]`);- if (element && this.isPointInsideEntity(svgPoint, element)) {- clickedElement = element;- break;- }- }-- if (clickedElement) {- this.onEntityClick(clickedElement, svgPoint, event);- } else {- this.onBackgroundClick(svgPoint, event);- }- }-- isPointInsideEntity(point, element) {- // Use cached bounding boxes when possible- const cacheKey = element.getAttribute('data-entity-id');- let bbox = this.eventCache.get(`bbox_${cacheKey}`);-- if (!bbox) {- bbox = element.getBBox();- this.eventCache.set(`bbox_${cacheKey}`, bbox);-- // Cache cleanup- if (this.eventCache.size > 200) {- const firstKey = this.eventCache.keys().next().value;- this.eventCache.delete(firstKey);- }- }-- return point.x >= bbox.x &&- point.x <= bbox.x + bbox.width &&- point.y >= bbox.y &&- point.y <= bbox.y + bbox.height;- }-- // Optimized mouse move handling- handleMouseMove(event) {- if (!this.isInteracting) return;-- // Use requestAnimationFrame to throttle mouse move events- if (this.mouseMoveFrame) {- cancelAnimationFrame(this.mouseMoveFrame);- }-- this.mouseMoveFrame = requestAnimationFrame(() => {- this.processMouseMove(event);- });- }-- processMouseMove(event) {- const svgPoint = this.coordinateTransform.screenToSvg({- x: event.clientX,- y: event.clientY- });-- // Only process if movement is significant- if (this.lastInteractionPoint) {- const dx = svgPoint.x - this.lastInteractionPoint.x;- const dy = svgPoint.y - this.lastInteractionPoint.y;- const distance = Math.sqrt(dx * dx + dy * dy);-- if (distance < 1) { // Less than 1 SVG unit- return; // Skip insignificant movements- }- }-- this.lastInteractionPoint = svgPoint;- this.emitMouseMoveEvent(svgPoint, event);- }-- emitMouseMoveEvent(svgPoint, originalEvent) {- this.svgElement.dispatchEvent(new CustomEvent('svgMouseMove', {- detail: {- svgCoordinates: svgPoint,- screenCoordinates: {- x: originalEvent.clientX,- y: originalEvent.clientY- }- }- }));- }-}-```--### Memory and Resource Management--#### Resource Pool for Coordinate Operations-```javascript-// Efficient resource management for coordinate operations-class CoordinateResourcePool {- constructor() {- this.svgPointPool = [];- this.matrixPool = [];- this.transformPool = [];- this.maxPoolSize = 100;- }-- // Object pooling for SVG points- acquireSVGPoint() {- if (this.svgPointPool.length > 0) {- return this.svgPointPool.pop();- }-- // Create new if pool is empty- const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');- return svg.createSVGPoint();- }-- releaseSVGPoint(point) {- if (this.svgPointPool.length < this.maxPoolSize) {- // Reset point- point.x = 0;- point.y = 0;- this.svgPointPool.push(point);- }- }-- // Batch coordinate conversion using pooled objects- batchConvertCoordinates(coordinates, converter) {- const results = [];- const points = coordinates.map(() => this.acquireSVGPoint());-- try {- // Use pooled points for conversion- coordinates.forEach((coord, index) => {- const point = points[index];- point.x = coord.x;- point.y = coord.y;-- const result = converter(point);- results.push({ x: result.x, y: result.y });- });- } finally {- // Always return points to pool- points.forEach(point => this.releaseSVGPoint(point));- }-- return results;- }-- // Memory cleanup- cleanup() {- this.svgPointPool.length = 0;- this.matrixPool.length = 0;- this.transformPool.length = 0;- }-}-```--### Performance Monitoring and Analytics--#### Coordinate Performance Profiler-```javascript-// Performance monitoring for coordinate operations-class CoordinatePerformanceProfiler {- constructor() {- this.metrics = {- transformations: [],- entityUpdates: [],- viewportChanges: [],- interactions: []- };- this.isEnabled = false;- }-- enable() {- this.isEnabled = true;- this.startTime = performance.now();- }-- disable() {- this.isEnabled = false;- }-- profileTransformation(operation, duration) {- if (!this.isEnabled) return;-- this.metrics.transformations.push({- operation,- duration,- timestamp: performance.now() - this.startTime- });-- // Keep metrics size manageable- if (this.metrics.transformations.length > 1000) {- this.metrics.transformations.splice(0, 100);- }- }-- profileEntityUpdate(entityCount, duration) {- if (!this.isEnabled) return;-- this.metrics.entityUpdates.push({- entityCount,- duration,- timestamp: performance.now() - this.startTime- });- }-- profileInteraction(type, duration) {- if (!this.isEnabled) return;-- this.metrics.interactions.push({- type,- duration,- timestamp: performance.now() - this.startTime- });- }-- generateReport() {- const report = {- transformations: this.analyzeTransformations(),- entityUpdates: this.analyzeEntityUpdates(),- interactions: this.analyzeInteractions(),- recommendations: this.generateRecommendations()- };-- console.table(report.transformations);- console.table(report.entityUpdates);- console.log('Performance Recommendations:', report.recommendations);-- return report;- }-- analyzeTransformations() {- if (this.metrics.transformations.length === 0) return {};-- const durations = this.metrics.transformations.map(t => t.duration);- const operations = {};-- this.metrics.transformations.forEach(t => {- if (!operations[t.operation]) {- operations[t.operation] = [];- }- operations[t.operation].push(t.duration);- });-- return Object.entries(operations).map(([op, durations]) => ({- operation: op,- count: durations.length,- average: (durations.reduce((a, b) => a + b, 0) / durations.length).toFixed(2),- max: Math.max(...durations).toFixed(2),- min: Math.min(...durations).toFixed(2)- }));- }-- analyzeEntityUpdates() {- if (this.metrics.entityUpdates.length === 0) return {};-- const updates = this.metrics.entityUpdates;- const avgEntitiesPerUpdate = updates.reduce((sum, u) => sum + u.entityCount, 0) / updates.length;- const avgDuration = updates.reduce((sum, u) => sum + u.duration, 0) / updates.length;-- return {- totalUpdates: updates.length,- avgEntitiesPerUpdate: avgEntitiesPerUpdate.toFixed(1),- avgDuration: avgDuration.toFixed(2),- entitiesPerSecond: (avgEntitiesPerUpdate / (avgDuration / 1000)).toFixed(0)- };- }-- analyzeInteractions() {- const interactions = {};-- this.metrics.interactions.forEach(i => {- if (!interactions[i.type]) {- interactions[i.type] = [];- }- interactions[i.type].push(i.duration);- });-- return Object.entries(interactions).map(([type, durations]) => ({- type,- count: durations.length,- average: (durations.reduce((a, b) => a + b, 0) / durations.length).toFixed(2)- }));- }-- generateRecommendations() {- const recommendations = [];-- // Analyze transformation performance- const transformData = this.analyzeTransformations();- if (Array.isArray(transformData)) {- const slowTransforms = transformData.filter(t => parseFloat(t.average) > 5);- if (slowTransforms.length > 0) {- recommendations.push('Consider caching or optimizing slow transformation operations');- }- }-- // Analyze entity update performance- const entityData = this.analyzeEntityUpdates();- if (entityData.entitiesPerSecond && parseInt(entityData.entitiesPerSecond) < 1000) {- recommendations.push('Entity update performance is below optimal (< 1000 entities/sec)');- }-- return recommendations;- }-}-```--## Overview--This document covers the frontend-specific SVG coordinate operations used in location-based entity displays. These operations handle the conversion between different coordinate systems and the visual positioning of entities within SVG-based floor plans.--## Coordinate System Types--### SVG Document Coordinates-- **Origin**: Top-left corner of the SVG viewBox-- **Units**: SVG units (typically corresponding to real-world measurements)-- **Usage**: Entity positioning data stored in EntityPosition and EntityPath models--### Screen/Canvas Coordinates-- **Origin**: Top-left corner of the rendered SVG element-- **Units**: CSS pixels-- **Usage**: Mouse interactions, click detection, dynamic positioning--### Viewport Coordinates-- **Origin**: Top-left corner of the visible viewport area-- **Units**: CSS pixels-- **Usage**: Scroll position, panning operations--## Frontend SVG Operations--### Screen Position Calculation--Convert SVG coordinates to screen position for interactions:--```python-class SvgCoordinateTransform:- def calculate_entity_position(self, svg_coords, viewbox, canvas_size):- """Convert SVG coordinates to screen position"""- # Extract viewbox parameters- vb_x, vb_y, vb_width, vb_height = self.parse_viewbox(viewbox)- canvas_width, canvas_height = canvas_size-- # Calculate scale factors- scale_x = canvas_width / vb_width- scale_y = canvas_height / vb_height-- # Transform SVG coordinates to screen coordinates- screen_x = (svg_coords.x - vb_x) * scale_x- screen_y = (svg_coords.y - vb_y) * scale_y-- return ScreenPosition(screen_x, screen_y)-- def parse_viewbox(self, viewbox_string):- """Parse SVG viewBox string into components"""- parts = viewbox_string.split()- return float(parts[0]), float(parts[1]), float(parts[2]), float(parts[3])-```--### Interactive Coordinate Conversion--Handle mouse events and convert to SVG coordinates:--```javascript-class SvgInteractionHandler {- constructor(svgElement) {- this.svgElement = svgElement;- }-- screenToSvgCoordinates(screenX, screenY) {- // Get SVG bounding rectangle- const rect = this.svgElement.getBoundingClientRect();-- // Convert screen coordinates to SVG viewport coordinates- const svgPoint = this.svgElement.createSVGPoint();- svgPoint.x = screenX - rect.left;- svgPoint.y = screenY - rect.top;-- // Transform through CTM (Current Transformation Matrix)- const ctm = this.svgElement.getScreenCTM().inverse();- const svgCoords = svgPoint.matrixTransform(ctm);-- return {- x: svgCoords.x,- y: svgCoords.y- };- }-- handleEntityClick(event, entityId) {- const svgCoords = this.screenToSvgCoordinates(event.clientX, event.clientY);-- // Process entity interaction at SVG coordinates- this.processEntityInteraction(entityId, svgCoords);- }-}-```--### Zoom and Pan Operations--Handle viewport transformations for navigation:--```javascript-class SvgViewportController {- constructor(svgElement) {- this.svgElement = svgElement;- this.currentZoom = 1.0;- this.currentPan = { x: 0, y: 0 };- }-- zoomToFit(entities) {- // Calculate bounding box of all entities- const bbox = this.calculateEntityBoundingBox(entities);-- // Add padding- const padding = 20;- const paddedBounds = {- x: bbox.x - padding,- y: bbox.y - padding,- width: bbox.width + (padding * 2),- height: bbox.height + (padding * 2)- };-- // Update viewBox to fit entities- const viewBox = `${paddedBounds.x} ${paddedBounds.y} ${paddedBounds.width} ${paddedBounds.height}`;- this.svgElement.setAttribute('viewBox', viewBox);- }-- zoomIn(factor = 1.2) {- this.currentZoom *= factor;- this.applyTransform();- }-- zoomOut(factor = 0.8) {- this.currentZoom *= factor;- this.applyTransform();- }-- pan(deltaX, deltaY) {- this.currentPan.x += deltaX / this.currentZoom;- this.currentPan.y += deltaY / this.currentZoom;- this.applyTransform();- }-- applyTransform() {- const transform = `translate(${this.currentPan.x}, ${this.currentPan.y}) scale(${this.currentZoom})`;- const mainGroup = this.svgElement.querySelector('#main-group');- if (mainGroup) {- mainGroup.setAttribute('transform', transform);- }- }-}-```--### Entity Positioning and Scaling--Handle dynamic entity positioning based on viewport:--```javascript-class EntityPositionManager {- updateEntityPosition(entityElement, position, viewportScale) {- // Calculate scaled position- const scaledX = position.x * viewportScale;- const scaledY = position.y * viewportScale;- const scaledSize = position.scale * viewportScale;-- // Apply transform to entity element- const transform = `translate(${scaledX}, ${scaledY}) scale(${scaledSize}) rotate(${position.rotation})`;- entityElement.setAttribute('transform', transform);- }-- updateEntityPath(pathElement, pathData, viewportTransform) {- // Apply viewport transformation to path data- const transformedPath = this.transformSvgPath(pathData, viewportTransform);- pathElement.setAttribute('d', transformedPath);- }-- transformSvgPath(pathData, transform) {- // Parse and transform SVG path data- // This is a simplified example - real implementation would use SVG path parsing library- return pathData; // Placeholder for actual path transformation- }-}-```--## Template Integration--### SVG Viewport Setup--```django-<!-- Location view SVG setup -->-<svg id="location-svg"- class="location-display"- viewBox="{{ location_view.get_viewbox }}"- preserveAspectRatio="xMidYMid meet">-- <!-- Main transform group for zoom/pan -->- <g id="main-group">-- <!-- Background layer -->- <g class="background-layer">- {% if location.floor_plan_svg %}- {% include location.floor_plan_svg %}- {% endif %}- </g>-- <!-- Entity layer -->- <g class="entity-layer">- {% for entity in entities %}- {% if entity.has_position %}- <g class="entity-group"- data-entity-id="{{ entity.id }}"- transform="translate({{ entity.position.x }}, {{ entity.position.y }})- scale({{ entity.position.scale }})- rotate({{ entity.position.rotation }})">- {% include entity.get_visual_template %}- </g>- {% elif entity.has_path %}- <path class="entity-path"- data-entity-id="{{ entity.id }}"- d="{{ entity.path.svg_path }}"- style="{{ entity.get_path_styling }}"/>- {% endif %}- {% endfor %}- </g>-- </g>-</svg>-```--### JavaScript Integration--```javascript-// Initialize SVG coordinate handling-document.addEventListener('DOMContentLoaded', function() {- const locationSvg = document.getElementById('location-svg');-- if (locationSvg) {- // Initialize interaction handler- const interactionHandler = new SvgInteractionHandler(locationSvg);-- // Initialize viewport controller- const viewportController = new SvgViewportController(locationSvg);-- // Initialize entity position manager- const positionManager = new EntityPositionManager();-- // Set up event listeners- locationSvg.addEventListener('click', function(event) {- const entityElement = event.target.closest('[data-entity-id]');- if (entityElement) {- const entityId = entityElement.getAttribute('data-entity-id');- interactionHandler.handleEntityClick(event, entityId);- }- });-- // Set up zoom controls- document.getElementById('zoom-in').addEventListener('click', () => {- viewportController.zoomIn();- });-- document.getElementById('zoom-out').addEventListener('click', () => {- viewportController.zoomOut();- });-- // Set up pan controls (mouse drag)- let isPanning = false;- let lastPanPoint = null;-- locationSvg.addEventListener('mousedown', function(event) {- if (event.button === 1 || (event.button === 0 && event.ctrlKey)) { // Middle mouse or Ctrl+click- isPanning = true;- lastPanPoint = { x: event.clientX, y: event.clientY };- event.preventDefault();- }- });-- document.addEventListener('mousemove', function(event) {- if (isPanning && lastPanPoint) {- const deltaX = event.clientX - lastPanPoint.x;- const deltaY = event.clientY - lastPanPoint.y;- viewportController.pan(deltaX, deltaY);- lastPanPoint = { x: event.clientX, y: event.clientY };- }- });-- document.addEventListener('mouseup', function() {- isPanning = false;- lastPanPoint = null;- });- }-});-```--## Performance Considerations--### Efficient Coordinate Calculations--```javascript-// Cache frequently used calculations-class CoordinateCache {- constructor() {- this.transformCache = new Map();- this.boundingBoxCache = new Map();- }-- getCachedTransform(viewBox, canvasSize) {- const key = `${viewBox}_${canvasSize.width}x${canvasSize.height}`;-- if (!this.transformCache.has(key)) {- const transform = this.calculateTransform(viewBox, canvasSize);- this.transformCache.set(key, transform);- }-- return this.transformCache.get(key);- }-- clearCache() {- this.transformCache.clear();- this.boundingBoxCache.clear();- }-}-```--### Optimize Frequent Updates--```javascript-// Use requestAnimationFrame for smooth updates-class SmoothPositionUpdater {- constructor() {- this.pendingUpdates = new Map();- this.isUpdateScheduled = false;- }-- scheduleUpdate(entityId, newPosition) {- this.pendingUpdates.set(entityId, newPosition);-- if (!this.isUpdateScheduled) {- this.isUpdateScheduled = true;- requestAnimationFrame(() => this.processPendingUpdates());- }- }-- processPendingUpdates() {- this.pendingUpdates.forEach((position, entityId) => {- const element = document.querySelector(`[data-entity-id="${entityId}"]`);- if (element) {- this.applyPositionUpdate(element, position);- }- });-- this.pendingUpdates.clear();- this.isUpdateScheduled = false;- }-}-```--## Troubleshooting--### Click Detection Not Working--**Symptoms**: Mouse clicks on entities don't trigger expected actions-**Diagnostic Steps**:--1. **Verify Event Listener Setup**- ```javascript- // Check if click handler is attached- const svg = document.getElementById('location-svg');- console.log('Click listeners:', getEventListeners(svg));-- // Test manual click- svg.addEventListener('click', (e) => {- console.log('Click at:', e.clientX, e.clientY);- });- ```--2. **Check Coordinate Conversion**- ```javascript- // Test coordinate transformation- const handler = new SvgInteractionHandler(svg);- const svgCoords = handler.screenToSvgCoordinates(event.clientX, event.clientY);- console.log('SVG coordinates:', svgCoords);- ```--3. **Verify Element Structure**- ```html- <!-- Entity must have data-entity-id and be in correct layer -->- <g class="entity-layer">- <g data-entity-id="123" class="entity-group">- <!-- Clickable content -->- </g>- </g>- ```--**Common Fixes**:-- **Missing data-entity-id**: Add attribute to entity elements-- **Event bubbling issues**: Use `event.target.closest('[data-entity-id]')`-- **Coordinate transformation error**: Check SVG viewBox and CTM calculation-- **Z-index/layering**: Ensure entities are in front of background elements--### Entity Positions Incorrect--**Symptoms**: Entities appear in wrong locations after coordinate transformations-**Root Causes & Solutions**:--1. **ViewBox Parsing Issues**- ```javascript- // Debug viewBox parsing- const viewBox = svg.getAttribute('viewBox');- console.log('ViewBox:', viewBox);-- const [x, y, width, height] = viewBox.split(' ').map(Number);- console.log('Parsed:', { x, y, width, height });- ```--2. **Scale Factor Calculation**- ```javascript- // Verify scale factors- const rect = svg.getBoundingClientRect();- const viewBoxWidth = parseFloat(svg.viewBox.baseVal.width);- const scaleX = rect.width / viewBoxWidth;- console.log('Scale factor:', scaleX);- ```--3. **Transform Matrix Issues**- ```javascript- // Check current transformation matrix- const ctm = svg.getScreenCTM();- console.log('CTM:', ctm);- console.log('Transform values:', {- a: ctm.a, b: ctm.b, c: ctm.c,- d: ctm.d, e: ctm.e, f: ctm.f- });- ```--**Solutions**:-- **Invalid viewBox**: Ensure viewBox attribute has 4 numeric values-- **Missing CTM**: Check if SVG element has proper screen CTM-- **Nested transforms**: Account for parent group transformations-- **Dynamic sizing**: Recalculate on window resize--### Zoom and Pan Not Working--**Symptoms**: Viewport controls don't respond or behave erratically-**Troubleshooting Approach**:--1. **Check Controller Initialization**- ```javascript- // Verify controller is properly initialized- console.log('Viewport controller:', window.viewportController);-- // Test basic operations- if (viewportController) {- viewportController.zoomIn();- console.log('Current zoom:', viewportController.currentZoom);- }- ```--2. **Verify Transform Application**- ```javascript- // Check if transforms are being applied- const mainGroup = svg.querySelector('#main-group');- console.log('Main group transform:', mainGroup.getAttribute('transform'));- ```--3. **Event Handler Issues**- ```javascript- // Test zoom button events- document.getElementById('zoom-in').addEventListener('click', () => {- console.log('Zoom in clicked');- viewportController.zoomIn();- });- ```--**Common Fixes**:-- **Missing main group**: Ensure SVG has `#main-group` element-- **Event conflicts**: Check for competing mouse event handlers-- **Transform syntax**: Verify proper transform string formatting-- **Boundary limits**: Implement zoom/pan limits to prevent excessive values--### Performance Issues with Many Entities--**Symptoms**: Slow coordinate calculations, laggy interactions with large datasets-**Optimization Strategies**:--1. **Coordinate Caching**- ```javascript- // Implement coordinate result caching- class CoordinateCache {- constructor(maxSize = 1000) {- this.cache = new Map();- this.maxSize = maxSize;- }-- get(key) {- const result = this.cache.get(key);- if (result) {- // Move to end (LRU)- this.cache.delete(key);- this.cache.set(key, result);- }- return result;- }- }- ```--2. **Batch Operations**- ```javascript- // Process coordinate updates in batches- requestAnimationFrame(() => {- const updates = this.pendingCoordinateUpdates;- updates.forEach(update => {- this.applyCoordinateUpdate(update);- });- this.pendingCoordinateUpdates.clear();- });- ```--3. **Viewport Culling**- ```javascript- // Only process entities in visible viewport- function isEntityVisible(entityCoords, viewportBounds) {- return entityCoords.x >= viewportBounds.left &&- entityCoords.x <= viewportBounds.right &&- entityCoords.y >= viewportBounds.top &&- entityCoords.y <= viewportBounds.bottom;- }- ```--### SVG Viewbox and Scaling Issues--**Symptoms**: Inconsistent scaling, elements clipped or positioned wrong-**Diagnostic Steps**:--1. **Check ViewBox vs Canvas Size**- ```javascript- // Compare logical vs physical dimensions- const viewBox = svg.viewBox.baseVal;- const rect = svg.getBoundingClientRect();-- console.log('ViewBox:', viewBox.width, 'x', viewBox.height);- console.log('Canvas:', rect.width, 'x', rect.height);- console.log('Aspect ratios:',- viewBox.width/viewBox.height,- rect.width/rect.height);- ```--2. **Verify preserveAspectRatio**- ```html- <!-- Check preserveAspectRatio setting -->- <svg viewBox="0 0 1000 800"- preserveAspectRatio="xMidYMid meet" <!-- or "none" for stretching -->- ...>- ```--3. **Test Scale Consistency**- ```javascript- // Verify consistent scaling in both dimensions- function testScaling() {- const point1 = { x: 0, y: 0 };- const point2 = { x: 100, y: 100 };-- const screen1 = svgToScreen(point1);- const screen2 = svgToScreen(point2);-- const scaleX = (screen2.x - screen1.x) / (point2.x - point1.x);- const scaleY = (screen2.y - screen1.y) / (point2.y - point1.y);-- console.log('Scale factors:', { scaleX, scaleY });- }- ```--### Browser Compatibility Problems--**Symptoms**: Coordinate operations work in some browsers but not others-**Common Issues & Solutions**:--1. **SVG DOM API Support**- ```javascript- // Check for required APIs- if (!SVGElement.prototype.getScreenCTM) {- console.error('Browser lacks SVG getScreenCTM support');- // Implement fallback or show warning- }-- if (!SVGSVGElement.prototype.createSVGPoint) {- console.error('Browser lacks createSVGPoint support');- // Use alternative coordinate conversion- }- ```--2. **Transform Matrix Differences**- ```javascript- // Handle browser differences in matrix calculations- function getScreenCTMSafe(element) {- try {- return element.getScreenCTM();- } catch (e) {- console.warn('getScreenCTM failed, using fallback');- return element.getCTM();- }- }- ```--3. **Event Coordinate Differences**- ```javascript- // Normalize event coordinates across browsers- function getNormalizedCoordinates(event) {- return {- clientX: event.clientX || event.pageX,- clientY: event.clientY || event.pageY- };- }- ```--### Touch and Mobile Issues--**Symptoms**: Coordinate operations fail on touch devices-**Mobile-Specific Solutions**:--1. **Touch Event Handling**- ```javascript- // Handle touch events for mobile devices- svg.addEventListener('touchstart', (e) => {- e.preventDefault(); // Prevent default touch behaviors- const touch = e.touches[0];- handleInteraction(touch.clientX, touch.clientY);- });- ```--2. **Viewport Meta Tag**- ```html- <!-- Ensure proper mobile viewport handling -->- <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">- ```--3. **High DPI Display Issues**- ```javascript- // Account for device pixel ratio- const dpr = window.devicePixelRatio || 1;- const adjustedCoords = {- x: screenX * dpr,- y: screenY * dpr- };- ```--## Related Documentation-- Entity visual configuration: [Entity Visual Configuration](entity-visual-configuration.md)-- Entity status display: [Entity Status Display](entity-status-display.md)-- Style guidelines: [Style Guidelines](style-guidelines.md)-- Domain geometric operations: [Domain Guidelines](../domain/domain-guidelines.md#complex-calculations)-- Frontend guidelines: [Frontend Guidelines](frontend-guidelines.md)\ No newline at end of filediff --git a/docs/dev/frontend/template-conventions.md b/docs/dev/frontend/template-conventions.mdindex 124831d1..85c62ed9 100644--- a/docs/dev/frontend/template-conventions.md+++ b/docs/dev/frontend/template-conventions.md@@ -1,5 +1,13 @@# Template Conventions+## Checklist++- [ ] Template names referenced in views closely match the view names that use them.+- [ ] No templates have in-line Javascript.+- [ ] No templates have in-line CSS.+- [ ] Templates appear in a subdirectory matching their purpose: modals, panes, pages.+- [ ] Template tags `load` statments near the top of the file.+## The "Hi Grid" Template Structure### Important DIVIDs for Main Page Layout@@ -49,51 +57,6 @@ All pages should extend from appropriate base templates:{% extends "config/pages/config_base.html" %}```-### Block Structure--Common blocks to override:--```django-{% block head_title %}Page Title{% endblock %}-{% block extra_css %}- <!-- Page-specific CSS -->-{% endblock %}-{% block content %}- <!-- Main content area -->-{% endblock %}-{% block extra_js %}- <!-- Page-specific JavaScript -->-{% endblock %}-```--## Template Context Patterns--### Standard Context Variables--Views should provide consistent context variables:--```python-context = {- # Entity-related- 'entity': entity_instance,- 'entities': entity_queryset,- 'entity_position': position_instance,-- # Location-related- 'location': location_instance,- 'location_view': location_view_instance,-- # View state- 'view_mode': ViewMode.NORMAL, # Use enums, not strings- 'view_type': ViewType.SECURITY,- 'is_edit_mode': False,-- # Pre-computed flags- 'has_sensors': bool(entity.sensors.exists()),- 'can_edit': request.user.has_perm('entity.change_entity'),-}-```-### Avoiding Template Logic**Bad - Logic in template:**@@ -137,180 +100,9 @@ Always load required template tags at the top:{% load custom_filters %}```-### Custom Template Tags--Create reusable template tags for complex display logic:--```python-# In templatetags/entity_tags.py[email protected]_tag('entity/tags/status_badge.html')-def entity_status_badge(entity):- return {- 'entity': entity,- 'status_class': entity.get_status_css_class(),- 'status_label': entity.get_status_display(),- }-```--Usage:-```django-{% load entity_tags %}-{% entity_status_badge entity %}-```--## Form Templates--### Form Rendering Pattern--Use consistent form rendering:--```django-<form method="post" action="{% url 'entity_update' entity.id %}">- {% csrf_token %}-- {% if form.non_field_errors %}- <div class="alert alert-danger">- {{ form.non_field_errors }}- </div>- {% endif %}-- {% for field in form %}- <div class="form-group">- {{ field.label_tag }}- {{ field }}- {% if field.help_text %}- <small class="form-text text-muted">{{ field.help_text }}</small>- {% endif %}- {% if field.errors %}- <div class="invalid-feedback d-block">- {{ field.errors }}- </div>- {% endif %}- </div>- {% endfor %}-- <button type="submit" class="btn btn-primary">- {% icon "save" size="sm" css_class="hi-icon-left" %}- Save Changes- </button>-</form>-```--## AJAX Template Patterns--### Returning HTML Fragments--For AJAX requests returning HTML:--```django-<!-- panes/entity_row.html -->-<tr class="entity-row" data-entity-id="{{ entity.id }}">- <td>{{ entity.name }}</td>- <td>{{ entity.location.name }}</td>- <td>{% entity_status_badge entity %}</td>-</tr>-```--### JSON Response Structure--For AJAX views returning JSON with HTML:--```python-# In view-html = render_to_string('entity/panes/entity_row.html', {'entity': entity})-return JsonResponse({- 'status': 'success',- 'html': html,- 'entity_id': entity.id,- 'insert_method': 'append',- 'target_selector': '#entity-table tbody',-})-```-## Modal Templates-### Modal Structure--Standard modal template structure:--```django-<!-- modals/entity_edit.html -->-<div class="modal fade" id="entityEditModal" tabindex="-1" role="dialog">- <div class="modal-dialog modal-lg" role="document">- <div class="modal-content">- <div class="modal-header">- <h5 class="modal-title">Edit Entity</h5>- <button type="button" class="close" data-dismiss="modal" aria-label="Close">- {% icon "close" size="sm" %}- </button>- </div>- <div class="modal-body">- <!-- Modal content -->- </div>- <div class="modal-footer">- <button type="button" class="btn btn-secondary" data-dismiss="modal">- {% icon "cancel" size="sm" css_class="hi-icon-left" %}- Cancel- </button>- <button type="submit" class="btn btn-primary">- {% icon "save" size="sm" css_class="hi-icon-left" %}- Save Changes- </button>- </div>- </div>- </div>-</div>-```--## Template Performance--### Efficient Queries--Use `select_related` and `prefetch_related` in views:--```python-# In view - prevent N+1 queries-entities = Entity.objects.select_related(- 'location',- 'entity_type'-).prefetch_related(- 'sensors',- 'controllers'-)-```--### Template Fragment Caching--Cache expensive template fragments:--```django-{% load cache %}-{% cache 300 entity_detail entity.id entity.updated_at %}- <!-- Expensive template rendering -->- {% include "entity/panes/sensor_list.html" %}-{% endcache %}-```--## Debugging Templates--### Debug Toolbar--Use Django Debug Toolbar to identify template issues:-- Template rendering time-- Number of SQL queries-- Context variables--### Template Debug Mode--In development, use template debug mode:--```django-{% if debug %}- <div class="debug-info">- <pre>{{ entity|pprint }}</pre>- </div>-{% endif %}-```+Extend one of the standard modal templates: `src/hi/templates/modals`.## Related Documentation- Frontend guidelines: [Frontend Guidelines](frontend-guidelines.md)diff --git a/docs/dev/integrations/integration-guidelines.md b/docs/dev/integrations/integration-guidelines.mdindex f27083ff..0f69a340 100644--- a/docs/dev/integrations/integration-guidelines.md+++ b/docs/dev/integrations/integration-guidelines.md@@ -1,386 +1,91 @@# Integration Guidelines-## Integration Architecture+## Architecture Overview-Each integration is a Django app in the `hi/services` directory. The `hi.integration` app handles integration management and required interfaces.+Each integration is a Django app in `hi/services/` directory. The `hi.integration` app provides management interfaces and base classes.-### Responsibility Boundaries---he detail_attrs should be an opaque blob of data to main application. Only the integration populates or utiizes the data in here. It is the integration that created the SensorResponse object and it is only that level of objects that the application can access. For example, these SensorResponses get turned into Event objects with start and end times, so the Event object duration is the only place to get duration information. Though the Event duration is connected to the ZoneMinder durations, the Event object does not know or need to know this.+### Key Concepts+- **integration_id**: Unique identifier for each integration type+- **integration_key**: Associates entities/sensors with external systems+- **detail_attrs**: Opaque data blob - only the integration uses this data-## Nomenclature--- **integration_id** - Unique identifier for each integration type-- **integration_key** - Used to associate with external integration for entities, sensors, controllers, etc.-- **integration_attr_key** - Unique identifier for user-defined attributes needed by implementation+### Responsibility Boundaries+Integrations create `SensorResponse` objects which become `Event` objects with duration. The Event duration is the only accessible duration data - Event objects don't know about underlying integration specifics.-## How to Add an Integration+## Integration Setup Process### 1. Create Django App-```bashcd src/hi/services../../manage.py startapp myintegration```### 2. Configure App--Ensure `name` is fully qualified in `hi/services/myintegration/apps.py`:--```python-class MyIntegrationConfig(AppConfig):- name = 'hi.services.myintegration'-```--Add to `INSTALLED_APPS` in `hi/settings/base.py`:--```python-INSTALLED_APPS = [- # ...- 'hi.services.myintegration',-]-```+- Set fully qualified name in `apps.py`: `name = 'hi.services.myintegration'`+- Add to `INSTALLED_APPS` in `hi/settings/base.py`### 3. Define Integration Type+Add to `IntegrationType` enum in appropriate enums file-Add to the IntegrationType enum:--```python-class IntegrationType(Enum):- MYINTEGRATION = ('My Integration', 'For my stuff.')-```--### 4. Create Integration Gateway--Create `hi/services/myintegration/myintegration_gateway.py`:--```python-from hi.integration.integration_gateway import IntegrationGateway-from hi.utils.singleton import Singleton--class MyIntegrationGateway(Singleton, IntegrationGateway):-- def activate(self, integration_instance):- """Handle integration activation"""- # Validation and setup logic- integration_instance.status = IntegrationStatus.ACTIVE- integration_instance.save()- return {'status': 'success', 'message': 'Integration activated'}-- def deactivate(self, integration_instance):- """Handle integration deactivation"""- # Cleanup logic- integration_instance.status = IntegrationStatus.INACTIVE- integration_instance.save()- return {'status': 'success', 'message': 'Integration deactivated'}-- def manage(self, request, integration_instance):- """Handle management interface"""- if request.method == 'POST':- return self.handle_management_post(request, integration_instance)- return self.render_management_page(request, integration_instance)-```+### 4. Create Gateway Class+Implement `IntegrationGateway` with required methods:+- `activate(integration_instance)` - Setup and validation+- `deactivate(integration_instance)` - Cleanup and shutdown+- `manage(request, integration_instance)` - Management interface### 5. Register with Factory+Add gateway mapping in `hi/integrations/integration_factory.py`-Add to `hi/integrations/integration_factory.py`:--```python-from hi.services.myintegration.myintegration_gateway import MyIntegrationGateway--def get_integration_gateway(integration_type):- if integration_type == IntegrationType.MYINTEGRATION:- return MyIntegrationGateway()- # ... other integrations-```--## Integration Gateway Methods--### Activate Method+## Gateway Implementation Patterns-Handle integration activation flow:+### Gateway Methods+**activate()**: Validate config, test connection, initialize resources+**deactivate()**: Clean up entities, close connections, update status+**manage()**: Handle POST actions (sync, test, config), render management UI-```python-def activate(self, integration_instance):- try:- # Validate configuration- self.validate_configuration(integration_instance)-- # Test connection- self.test_connection(integration_instance)-- # Initialize resources- self.initialize_integration(integration_instance)-- integration_instance.status = IntegrationStatus.ACTIVE- integration_instance.save()-- return {- 'status': 'success',- 'message': 'Integration activated successfully',- 'redirect': None- }- except ValidationError as e:- return {- 'status': 'error',- 'message': str(e),- 'redirect': None- }-```--### Deactivate Method--Handle cleanup and deactivation:--```python-def deactivate(self, integration_instance):- try:- # Clean up entities- entities_removed = self.cleanup_entities(integration_instance)-- # Close connections- self.close_connections(integration_instance)-- integration_instance.status = IntegrationStatus.INACTIVE- integration_instance.save()-- return {- 'status': 'success',- 'message': f'Integration deactivated. Removed {entities_removed} entities.',- }- except Exception as e:- return {- 'status': 'error',- 'message': f'Error during deactivation: {str(e)}'- }-```--### Manage Method--Provide management interface:--```python-def manage(self, request, integration_instance):- if request.method == 'POST':- action = request.POST.get('action')-- if action == 'sync_entities':- return self.sync_entities(integration_instance)- elif action == 'test_connection':- return self.test_connection_endpoint(integration_instance)- elif action == 'update_config':- return self.update_configuration(request, integration_instance)-- # Render management page- context = {- 'integration': integration_instance,- 'entity_count': self.get_entity_count(integration_instance),- 'last_sync': self.get_last_sync_time(integration_instance),- 'connection_status': self.get_connection_status(integration_instance),- }- return render(request, 'myintegration/manage.html', context)-```--## API Integration Patterns--### HTTP Client Pattern--```python-import requests-from requests.adapters import HTTPAdapter-from urllib3.util.retry import Retry+### Return Format+All gateway methods return dict with:+- `status`: 'success' or 'error'+- `message`: User-friendly status message+- `redirect`: Optional redirect URL-class MyIntegrationClient:- def __init__(self, base_url, api_key, timeout=30):- self.base_url = base_url- self.api_key = api_key- self.timeout = timeout- self.session = self._create_session()-- def _create_session(self):- session = requests.Session()-- # Configure retries- retry_strategy = Retry(- total=3,- backoff_factor=1,- status_forcelist=[429, 500, 502, 503, 504],- )- adapter = HTTPAdapter(max_retries=retry_strategy)- session.mount("http://", adapter)- session.mount("https://", adapter)-- # Default headers- session.headers.update({- 'Authorization': f'Bearer {self.api_key}',- 'Content-Type': 'application/json',- 'User-Agent': 'HomeInformation/1.0'- })-- return session-- def get_entities(self):- response = self.session.get(- f'{self.base_url}/entities',- timeout=self.timeout- )- response.raise_for_status()- return response.json()-```--### WebSocket Integration Pattern--```python-import asyncio-import websockets-import json--class MyIntegrationWebSocket:- def __init__(self, url, api_key):- self.url = url- self.api_key = api_key- self.websocket = None- self.running = False-- async def connect(self):- """Establish WebSocket connection"""- headers = {'Authorization': f'Bearer {self.api_key}'}- self.websocket = await websockets.connect(self.url, extra_headers=headers)- self.running = True-- async def listen(self):- """Listen for messages"""- try:- async for message in self.websocket:- data = json.loads(message)- await self.handle_message(data)- except websockets.exceptions.ConnectionClosed:- self.running = False-- async def handle_message(self, data):- """Process received message"""- message_type = data.get('type')-- if message_type == 'entity_update':- await self.handle_entity_update(data)- elif message_type == 'status_change':- await self.handle_status_change(data)-```--## Data Synchronization Patterns+## Integration Patterns-### Entity Synchronization+### API Integration+- **HTTP Client**: Use `requests.Session` with retry strategies and circuit breakers+- **WebSocket**: Async connection handling with reconnection logic+- **Authentication**: Bearer tokens, API keys, custom headers-```python-class EntitySynchronizer:- def __init__(self, integration_instance):- self.integration = integration_instance- self.client = MyIntegrationClient(- integration_instance.base_url,- integration_instance.api_key- )-- def sync_entities(self):- """Synchronize entities from external system"""- try:- external_entities = self.client.get_entities()-- synced_count = 0- for ext_entity in external_entities:- entity, created = self.sync_single_entity(ext_entity)- if entity:- synced_count += 1-- # Remove entities no longer in external system- removed_count = self.cleanup_removed_entities(external_entities)-- return {- 'synced': synced_count,- 'removed': removed_count,- 'total': len(external_entities)- }-- except Exception as e:- raise IntegrationError(f"Entity sync failed: {str(e)}")-- def sync_single_entity(self, external_entity):- """Sync individual entity"""- integration_id = external_entity['id']-- entity, created = Entity.objects.get_or_create(- integration_name=self.integration.integration_type.name,- integration_id=integration_id,- defaults={- 'name': external_entity['name'],- 'entity_type': self.get_or_create_entity_type(external_entity),- 'location': self.get_default_location(),- }- )-- # Update entity properties- if not created:- entity.name = external_entity['name']- entity.save()-- # Sync entity states- self.sync_entity_states(entity, external_entity)-- return entity, created-```--## Error Handling Patterns--### Custom Exception Classes+### Data Synchronization+- **Entity Sync**: Map external entities to internal Entity models+- **State Sync**: Update EntityState objects from external data+- **Cleanup**: Remove entities no longer in external system-```python-class IntegrationError(Exception):- """Base class for integration errors"""- pass+### Error Handling+Custom exception hierarchy:+- `IntegrationError` - Base class+- `ConnectionError` - Network/connectivity issues+- `AuthenticationError` - Auth/authorization failures+- `DataValidationError` - Invalid data from external source-class ConnectionError(IntegrationError):- """Connection-related errors"""- pass+## Key Base Classes & Modules-class AuthenticationError(IntegrationError):- """Authentication/authorization errors"""- pass+### Core Classes+- `hi.integration.integration_gateway.IntegrationGateway` - Base gateway class+- `hi.utils.singleton.Singleton` - Singleton pattern for gateways+- `hi.integrations.enums.IntegrationStatus` - Status enumeration-class DataValidationError(IntegrationError):- """Data validation errors"""- pass-```--### Error Recovery Patterns+### Factory Pattern+- `hi.integrations.integration_factory.py` - Gateway registration+- `hi.integrations.exceptions.py` - Custom exception classes-```python-class ResilientIntegrationClient:- def __init__(self, *args, **kwargs):- super().__init__(*args, **kwargs)- self.circuit_breaker = CircuitBreaker(- failure_threshold=5,- recovery_timeout=60- )-- def make_request(self, method, endpoint, **kwargs):- """Make HTTP request with circuit breaker pattern"""- @self.circuit_breaker- def _request():- response = self.session.request(method, endpoint, **kwargs)- response.raise_for_status()- return response-- try:- return _request()- except CircuitBreakerOpenException:- raise ConnectionError("Service temporarily unavailable")- except requests.exceptions.RequestException as e:- raise IntegrationError(f"Request failed: {str(e)}")-```+### Example Integrations+- `hi.services.hass/` - Home Assistant integration+- `hi.services.zoneminder/` - ZoneMinder integration+- `hi.services.weather/` - Weather service integration## Related Documentation-- Service patterns: [Service Patterns](service-patterns.md)-- Gateway implementation: [Gateway Implementation](gateway-implementation.md)-- External API standards: [External API Standards](external-api-standards.md)-- Weather integration: [Weather Integration](weather-integration.md)-- Backend integration: [Backend Guidelines](../backend/backend-guidelines.md)+- [Service Patterns](service-patterns.md)+- [Gateway Implementation](gateway-implementation.md)+- [Weather Integration](weather-integration.md)+- [Backend Guidelines](../backend/backend-guidelines.md)diff --git a/docs/dev/backend/django-patterns.md b/docs/dev/shared/coding-patterns.mdsimilarity index 95%rename from docs/dev/backend/django-patterns.mdrename to docs/dev/shared/coding-patterns.mdindex 1d697375..b8fd86ab 100644--- a/docs/dev/backend/django-patterns.md+++ b/docs/dev/shared/coding-patterns.md@@ -1,3 +1,19 @@+## Coding Patterns++- [ ] New modal dialogs extend one of the standard base classes in `hi/templates/modals`.+- [ ] New model dialogs extend the `HiModalView` class.+- [ ] The `antinode.js` framework and pattern is used for async/ajax content updates and modals.+- [ ] Javascript uses jQuery for DOM manipulations.+- [ ] Minimal business logic in templates: views prepare the template context needed+- [ ] Minimal business logic in Django views: use helepr classes+- [ ] No ORM calls in template tags+- [ ] Only internal system icons are used (no font-awesome icon).+- [ ] Appropriate icons are selected, or new icons created.+++++zzzzzzzz# Django Patterns## Model Design Patterns@@ -423,4 +439,4 @@ class Migration(migrations.Migration):- Backend guidelines: [Backend Guidelines](backend-guidelines.md)- Database conventions: [Database Conventions](database-conventions.md)- Testing patterns: [Testing Patterns](../testing/testing-patterns.md)-- Performance optimization: [Architecture Overview](../shared/architecture-overview.md)\ No newline at end of file+- Performance optimization: [Architecture Overview](../shared/architecture-overview.md)diff --git a/docs/dev/shared/coding-standards.md b/docs/dev/shared/coding-standards.mdindex 67f29864..01177445 100644--- a/docs/dev/shared/coding-standards.md+++ b/docs/dev/shared/coding-standards.md@@ -1,37 +1,73 @@# Coding Standards-## Code Organization and Conventions--### Directory Structure--#### Top-level Directory-- `src`: application source code-- `deploy`: helper scripts and files for deploying and setting up the application-- `package`: extra items that need to be packaged up to support running the application in Docker-- `Makefile`: provides convenience wrappers around commands for building, packaging and running-- `docs`: all documentation suitable to be in markdown files--#### The `src` Directory-- `hi`: entry point urls/views and some app-wide helper classes-- `hi/templates`: For top-level views and app-wide common base templates-- `hi/apps/${APPNAME}`: For normal application modules-- `hi/integrations`: Code for dealing with integration not related to a specific integration-- `hi/services/${SERVICENAME}`: Code for a particular integration-- `hi/simulator`: The code for the separate simulator helper app-- `hi/settings`: Django settings, including runtime population from environment variables-- `hi/requirements`: Python package dependencies-- `custom`: Custom user model and other general customizations-- `bin`: Helper scripts needed with the code to run inside a Docker container--## Coding Style+## Code Conventions Checklist++Checklists for writing and reviewing code.++**General**:+- [ ] Code does not use hard-coded "magic" strings.+- [ ] Code does no use any hard-coded "magic" numbers.+- [ ] All comments add value and follow our commenting guidelines.+- [ ] No urls appear as hard-coded path and all use Django url names and `reverse()`.+- [ ] There no .flake8 linting violations.+- [ ] The file ends with a newline+- [ ] All new files follow the project structure's name and location conventions.+- [ ] There are no Emoji's in any code, templates or documentation.++**Imports**:+- [ ] All module imports are at the top of the file.+- [ ] Imports are grouped logically: system/pip, django, project, apps then module local.+- [ ] Imports have one line space between groups.+- [ ] Within a group, imports are sorted alphabetically+- [ ] No module relies on indirect (hidden) imports+- [ ] There are no unused imports++**Method Declarations**:+- [ ] All methods uses type hints for their parameters and return values.+- [ ] All method definition with more than two arguments use one line per argunment.+- [ ] All multi-line method signatures have all their types and default values aligned.+- [ ] No methods return position-dependent tuples.++**Class Declarations**:+- [ ] All dataclass definitions have all their types and default values aligned.+- [ ] All enum definitions have all their types and default values aligned.+- [ ] Are enums subclass LabeledEnum++**Method Calling**:+- [ ] All method calls use named parameters.+- [ ] All metghod calls with more than two argumants use one line per argument.+- [ ] All multi-line method calls use a comma after last item.+- [ ] Spaces surrounding all equals ("=") signs when passing parameters to methods.++**Expressions**:+- [ ] All boolean assignments to conditional clauses are wrapped in `bool()`.+- [ ] All loops end with an explicit `continue` or a `return`.+- [ ] All methods end with an explicit `return` or a `raise`?+- [ ] All multi-line arrays, sets, dictionaries use a comma after last item.+- [ ] Compound/complex conditional statements use explicit delimiting parentheses.+- [ ] Single quote are used for all strings in Python code.+- [ ] All multi-line arrays, dictionaries and sets use a comma after last item.++**Views**:+- [ ] All url paths components follow our standard ordering conventions.+- [ ] All url Django names follow our standard naming conventions+- [ ] All view names match url names (except for casing and underlining).+- [ ] ALl views raise exceptions for common error conditions. (Let middleware handle it.)++**Templates**:+- [ ] Template names referenced in views closely match the view names that use them.+- [ ] No templates have in-line Javascript.+- [ ] No templates have in-line CSS.+- [ ] Templates appear in a subdirectory matching their purpose: modals, panes, pages.+- [ ] Template tags `load` statments near the top of the file.++## Code Conventions Details### No "magic" stringsWe do not use "magic" or hard-coded strings when needing multiple references. Any string that need to be used in two or more places is a risk of them being mismatched. This includes, but is not limited to:-- All references to urls *must* use the Django url name and reverse() to construct.-- Use enum values or constants/class variables to act as coordination point and provide some amount of compiler help in identifying mismatches. Most needed strings will already have a LabeledEnum type defined, but we should add new ones as needed. See "Enums" in [Back End Guidelines](../backend/backend-guidelines.md).-- All DOM ids and class strings that are shared between client and server must adhere to our `DIVID` pattern. See "Client-Server Namespace Sharing" in [Front End Guidelines](../frontend/frontend-guidelines.md).+All DOM ids and class strings that are shared between client and server must adhere to our `DIVID` pattern. See "Client-Server Namespace Sharing" in [Front End Guidelines](../frontend/frontend-guidelines.md).### Type Hints@@ -40,7 +76,6 @@ We do not use "magic" or hard-coded strings when needing multiple references. An- Some allowed, but not required exceptions:- The `request` parameter when appearing in a Django view class.- Single parameter methods where the method name or parameter name makes its type unambiguous.-### Method Parameter Formatting@@ -49,7 +84,7 @@ For readability, besides adding type hints to method parameters, we adhere to th- If more than one parameter and app-defined types, then use a multiple line declaration.- For methods with three or more parameters, we use one line per parameter and align the type names.-**Good Examples**+**Good Examples**:```def set_entity( self, entity_id : int ) -> EntityPath:@@ -62,7 +97,7 @@ For readability, besides adding type hints to method parameters, we adhere to thsvg_path_str : str ) -> EntityPath:```-**Bad Examples**+**Bad Examples**:```def set_entity_type( self, entity_id : int, entity_type : EntityType ) -> EntityPath:@@ -97,15 +132,15 @@ We prefer to wrap all expression that evaluate to a boolean in `bool()` to make- We use one line per clause unless the combined clauses are very short and obvious.- Single boolean typed variables or methods that return a boolean do not need paretheses.-**Good**+**Good**:```if is_editing and location_view:pass-+if (( hass_state.domain == HassApi.SWITCH_DOMAIN )and ( HassApi.LIGHT_DOMAIN in prefixes_seen )):pass-+if ( HassApi.BINARY_SENSOR_DOMAIN in domain_setand device_class_set.intersection( HassApi.OPEN_CLOSE_DEVICE_CLASS_SET )):pass@@ -113,44 +148,12 @@ We prefer to wrap all expression that evaluate to a boolean in `bool()` to make```-**Bad***+**Bad**:```if hass_state.domain == HassApi.SWITCH_DOMAIN and HassApi.LIGHT_DOMAIN == 'foo':pass```-### Flake8 Configurations--The project uses two different flake8 configurations:--#### Development Configuration (`.flake8`)-Our preferred style for daily development work, with specific whitespace deviations from PEP8 for enhanced readability:--```ini-[flake8]-max-line-length = 110-# Disabled for enhanced readability with spaces:-# E129, E201, E202, E203, E221, E231, E251, W293, W291, W391, W503-ignore = E129,D203,E201,E202,E203,E221,E231,E251,W293,W291,W391,W503-```--#### CI Configuration (`.flake8-ci`)-**Hard requirement** for pull request approval. GitHub Actions enforces these standards and blocks PR merging if violations exist.--**Before submitting any PR**, you must run: `flake8 --config=src/.flake8-ci src/` and ensure it passes with no violations.--### Generated Code Standards--### Linting--All generated code (including AI-generated code) must comply with `.flake8-ci` configuration:--1. **Final Newlines**: All files must end with a single newline character-2. **Unused Imports**: Remove all unused import statements-3. **Unused Variables**: Remove or prefix unused variables with underscore (`_variable`)-4. **Line Continuation**: Proper indentation for multi-line statements following PEP 8-5. **Line Length**: Respect maximum line length limits defined in `.flake8-ci`-### Control Flow Statements- Always include explicit `continue` statements in loops- Always include explicit `return` statements in functions@@ -194,6 +197,135 @@ is_active = user.last_loginin_modal_context = request.POST.get('context') == 'modal'```+### Linting: Flake8 Configurations++The project uses two different flake8 configurations:+- Development Configuration (`src/.flake8`) : Our preferred style for daily development work, with specific whitespace deviations from PEP8 for enhanced readability:+- CI Configuration (`src/.flake8-ci`): GitHub Actions enforces these standards and blocks PR merging if violations exist.++## Commenting Guidelines++- We avoid over-commenting and let the code variable/method naming be clear on the intent.+- We believe in the philosophy: "Before add a comment, ask yourself how the code can be changed to make this comment unnecessary."+- Do not add comments that are not timeless and refer to work in progress or future work. i.e., it must make sense for future readers of the code.+- Comments should explain the **why** not the **what**. Good comments document:+ - Non-obvious design decisions+ - Complex business logic+ - External API/library quirks and workarounds+ - Time-based complexities+ - Bug fixes that prevent regression+- Avoid comments that:+ - State what the code obviously does+ - Contain development artifacts or work-stream context+ - Leave commented-out code (creates confusion)+ - Explain what better naming could clarify++ - When in doubt, ask: "Can I change the code to make this comment unnecessary?"++### Special Cases++#### TRACE Pattern (Accepted)+- `TRACE = False # for debugging` is an accepted pattern+- Addresses Python logging limitation (lacks TRACE level below DEBUG)++### Examples++#### GOOD Comments - What TO Include++1. **Design rationale that is non-obvious**+ - Example: `# Single source of truth for position vs path classification`+ - Explains architectural decisions++2. **Complex domain logic explanations**+ - Example: Multi-line explanation of entity delegation concept+ - Business rules that aren't obvious from code structure++3. **Summarize complex or non-standard coding approaches**+ - When using unusual patterns or workarounds+ - Algorithm explanations that aren't obvious++4. **Design decision rationale**+ - Example: "The general types could be used for these, since all are just name-value pairs. However, by being more specific, we can provide more specific visual and processing"+ - Explains why one approach was chosen over alternatives++5. **Mathematical/geometric calculations**+ - Example: `'80.0,40.0', # top-left (100-20, 50-10)`+ - Coordinate calculations that are difficult to verify mentally+ - Especially valuable in test cases for validation++6. **Cross-file coordination notes**+ - Example: `# Match SvgItemFactory.NEW_PATH_RADIUS_PERCENT`+ - Important synchronization between related constants/values in different files++7. **Complex domain abstractions**+ - Example: Multi-line explanation of LocationItem interface concept+ - Abstract concepts that need implementation guidance++8. **Multi-step process/algorithm documentation**+ - Example: `alert_manager.py:40-56` - Breaks down the three distinct checks and explains why HTML is always returned+ - Complex workflows that need step-by-step explanation of the "why"++9. **External API/library limitations and workarounds**+ - Example: `wmo_units.py:838-841` - Documents Pint library limitations requiring unit mappings+ - Example: `zoneminder/monitors.py:81-87` - pyzm timezone parsing quirks+ - Critical for understanding why non-obvious code patterns exist+ - Brief expressions of frustration (e.g., "ugh") acceptable when documenting known pain points++10. **External service configuration rationale**+ - Example: `usno.py:59-62` - Documents API priority, rate limits, polling intervals+ - Explains constraints and decisions for external integrations++11. **Future extension points**+ - Example: `daily_weather_tracker.py:96-100` - "Future: Add other weather field tracking here"+ - Marks logical insertion points for anticipated features+ - Should be brief hints, not commented-out code blocks++12. **Temporal/timing complexity in APIs**+ - Example: `zoneminder/monitors.py:99-110` - Events as intervals vs points, open/closed handling+ - Example: `zoneminder/monitors.py:166-171` - Why polling time cannot advance+ - Critical for understanding time-based edge cases in external systems++13. **Bug fix documentation**+ - Example: `zoneminder/monitors.py:132-133` - "This fixes the core bug where..."+ - Documents what was broken and why the current approach fixes it+ - Helps prevent regression++#### BAD Comments - What NOT To Include++1. **Avoid commenting obvious variable purposes**+ - Bad: `# Store original entity_type_str to detect changes`+ - The variable name should make this clear++2. **Remove work-stream artifacts**+ - Bad: Comments explaining why tests were removed or referencing specific issues+ - Comments should be timeless, not tied to particular development contexts++3. **Redundant descriptions of clear code**+ - Bad: `# Track EntityType change and response needed after transaction`+ - When variable names already convey this information++4. **Cryptic references**+ - Bad: `# Recreate to preserve "max" to show new form`+ - If unclear, either explain properly or remove++5. **Development phase/work-stream artifacts**+ - Bad: Comments explaining "Phase 3/Phase 4" development contexts+ - Bad: Explanations of why code was removed or changed+ - These belong in commit messages or PR descriptions, not in main branch code++6. **TODO comments (high bar to justify)**+ - Generally avoid TODOs in main branch+ - If important enough for TODO, create an issue and prioritize it+ - Only acceptable when there's a compelling reason not to address immediately+ - Must be specific and actionable, not vague intentions++7. **Commented-out code**+ - Bad: Dead code that's been disabled or replaced+ - Bad: Example implementations as large code blocks+ - Bad: Logic that looks like it might need uncommenting (e.g., `zoneminder/integration.py:65-66`)+ - If needed for future reference, create an issue instead+ - Exception: Very brief one-line hints at extension points (see "Future extension points" in good comments)+ - Commented code creates confusion about whether it should be active## Related Documentation- Testing standards: [Testing Guidelines](../testing/testing-guidelines.md)@@ -201,8 +333,5 @@ in_modal_context = request.POST.get('context') == 'modal'- Frontend standards: [Frontend Guidelines](../frontend/frontend-guidelines.md)- Workflow and commits: [Workflow Guidelines](../workflow/workflow-guidelines.md)-### Commenting-- We avoid over-commenting and let the code variable/method naming be clear on the intent.-- We believe in the philosophy: "Before add a comment, ask yourself how the code can be changed to make this comment unnecessary."-- Do not add comments that are not timeless and refer to work in progress or future work. i.e., it must make sense for future readers of the code.+diff --git a/docs/dev/shared/project-structure.md b/docs/dev/shared/project-structure.mdnew file mode 100644index 00000000..7c751a06--- /dev/null+++ b/docs/dev/shared/project-structure.md@@ -0,0 +1,78 @@+# Project Structure++## Directory Structure++### Top-level Directory+- `src`: application source code+- `deploy`: helper scripts and files for deploying and setting up the application+- `package`: extra items that need to be packaged up to support running the application in Docker+- `Makefile`: provides convenience wrappers around commands for building, packaging and running+- `docs`: all documentation suitable to be in markdown files++### The `src` Directory+- `hi`: entry point urls/views and some app-wide helper classes+- `hi/apps/${APPNAME}`: For normal application modules+- `hi/environment`: Environment definitions for client (Javascript) and server (Python)+- `hi/integrations`: Code for dealing with integration not related to a specific integration+- `hi/services/${SERVICENAME}`: Code for a particular integration+- `hi/simulator`: The code for the separate simulator helper app+- `hi/settings`: Django settings, including runtime population from environment variables+- `hi/static`: Static files for Javascript, CSS, IMG, etc.+- `hi/templates`: For top-level views and app-wide common base templates+- `hi/testing`: Test-specific code not used in production+- `hi/requirements`: Python package dependencies+- `custom`: Custom user model and other general customizations+- `bin`: Helper scripts needed with the code to run inside a Docker container++## Module Structure++All new files should adhere to these naming and directory organization conventions.++### Application Module Structure++**Filenames: Django Conventions**:+- `admin.py` : Django standard for Django admin models+- `apps.py` : Django standard for app metadata and initializations+- `migrations.py` : Django standard for migrations+- `models.py` : Django standard for database ORM models+- `urls.py` : Django standard for urls+- `views.py` : Django standard for views++**Filenames: App Conventions**:+- `constants.py` : For shared constants+- `context_processors.py` : For new Django context processors+- `decorators.py` : For Django decorators+- `enums.py` : For all enums relevant to this module+- `forms.py` : For Django forms+- `middleware.py` : Django standard for middleware+- `signals.py` : For new Django signal definitions+- `transient_models.py` : For non-DB, in-memory container models with little business logic in them+- `view_mixins.py` : For view helpers that use HttpRequest/HttpResponse++**Filenames: Reserved for Auto-discovery Mechanisms**:+- `monitors.py` : For auto-discovered background monitor tasks+- `services/{app_name}/integration.py` : For auto-discovered integrations (only in `hi.services`)+- `settings.py` : For auto-discovered user-configuration options++**Filename Patterns**:+- `*_data.py` : For larger in-memory data classes needing their own module+- `*_helpers.py` : For general helpers with micellaneous responsibilities+- `*_manager.py` : For central control module, usually extending Singleton++**Directories: Django Conventions**:+- `management/commands` : Django standard for managemtn commands+- `templates` : Django standard for templates+- `templatetags` : Django standard for defining template tags++**Directories: App Conventions**:+- `assets` : For non-code files and data that business logic depends on.+- `edit` : For views and features that only apply to the apps editing mode+- `templates/tests/ui` : Templates supporting the UI testing and devtools views+- `templates/{app_name}/modals` : Templates for modal dialogs+- `templates/{app_name}/pages` : Templates representing and entire HTML page or sub-page+- `templates/{app_name}/panes` : Templates representing an HTML fragment+- `tests/data` : Non-code data supporting tests+- `tests/ui` : For develoment-only UI tests and development tools (urls.py auto-discovered)+- `tests` : All module-specifc tests go here++diff --git a/docs/dev/testing/testing-patterns.md b/docs/dev/testing/testing-patterns.mdindex ec1875a9..c61df463 100644--- a/docs/dev/testing/testing-patterns.md+++ b/docs/dev/testing/testing-patterns.md@@ -1,309 +1,100 @@# Testing Patterns-## Django View Testing--Django views in this application come in five distinct patterns that require different testing approaches:--1. **Synchronous HTML Views** - Traditional Django page views returning HTML responses-2. **Synchronous JSON Views** - API endpoints returning JSON responses-3. **Asynchronous HTML Views** - AJAX views returning HTML snippets for DOM insertion-4. **Asynchronous JSON Views** - AJAX views returning JSON data for JavaScript processing-5. **Dual-Mode Views** - Views (HiModalView/HiGridView) that handle both sync and async requests--### View Testing Base Classes--The framework uses a mixin-based architecture to provide clean separation of concerns:--- `ViewTestBase` - Common utilities and core assertions-- `SyncTestMixin` - Synchronous testing capabilities (regular `client.get()`, `client.post()`)-- `AsyncTestMixin` - Asynchronous testing capabilities (`async_get()`, `async_post()` with AJAX headers)--Use these base classes from `hi.tests.view_test_base`:--```python-from django.urls import reverse-from hi.tests.view_test_base import SyncViewTestCase, AsyncViewTestCase, DualModeViewTestCase--class TestMySyncViews(SyncViewTestCase):- def test_synchronous_html_view(self):- url = reverse('my_view_name')- response = self.client.get(url)- self.assertSuccessResponse(response)- self.assertHtmlResponse(response)- self.assertTemplateRendered(response, 'my_app/template.html')--class TestMyAsyncViews(AsyncViewTestCase):- def test_asynchronous_html_view(self):- url = reverse('my_async_view_name')- response = self.async_get(url) # Automatically includes AJAX headers- self.assertSuccessResponse(response)- self.assertJsonResponse(response)--class TestMyDualModeViews(DualModeViewTestCase):- def test_view_synchronous_mode(self):- url = reverse('my_dual_view_name')- response = self.client.get(url)- self.assertSuccessResponse(response)- self.assertHtmlResponse(response)-- def test_view_asynchronous_mode(self):- url = reverse('my_dual_view_name')- response = self.async_get(url)- self.assertSuccessResponse(response)- self.assertJsonResponse(response)-```--### Helper Methods--**Status Code Assertions:**-- `assertResponseStatusCode(response, expected_code)` - Verifies specific status code-- `assertSuccessResponse(response)` - Verifies 2xx status code-- `assertErrorResponse(response)` - Verifies 4xx status code-- `assertServerErrorResponse(response)` - Verifies 5xx status code--**Response Type Assertions:**-- `assertHtmlResponse(response)` - Verifies HTML content type-- `assertJsonResponse(response)` - Verifies JSON content type--**Template Assertions:**-- `assertTemplateRendered(response, template_name)` - Verifies specific template was used--**Session Assertions:**-- `assertSessionValue(response, key, expected_value)` - Verifies session contains specific key-value-- `assertSessionContains(response, key)` - Verifies session contains specific key--**Session Management:**-- `setSessionViewType(view_type)` - Set ViewType in session-- `setSessionViewMode(view_mode)` - Set ViewMode in session-- `setSessionLocationView(location_view)` - Set location_view_id in session-- `setSessionCollection(collection)` - Set collection_id in session-- `setSessionViewParameters(view_type=None, view_mode=None, location_view=None, collection=None)`--**Redirect Testing:**-- `assertRedirectsToTemplates(initial_url, expected_templates)` - Follow redirects and verify final templates--**AJAX Request Methods:**-- `async_get(url, data=None)` - GET request with AJAX headers-- `async_post(url, data=None)` - POST request with AJAX headers-- `async_put(url, data=None)` - PUT request with AJAX headers-- `async_delete(url, data=None)` - DELETE request with AJAX headers--## Manager Class Async/Sync Testing--Many manager classes in this codebase follow a dual sync/async pattern to support both traditional Django views and async integration services.+## View Testing Architecture++### View Types & Test Classes+Five distinct view patterns requiring different testing approaches:+1. **Synchronous HTML Views** - Traditional Django page views+2. **Synchronous JSON Views** - API endpoints+3. **Asynchronous HTML Views** - AJAX views returning HTML snippets+4. **Asynchronous JSON Views** - AJAX views returning JSON+5. **Dual-Mode Views** - HiModalView/HiGridView handling both sync and async++### Base Test Classes+From `hi.tests.view_test_base`:+- `SyncViewTestCase` - Regular `client.get()`, `client.post()`+- `AsyncViewTestCase` - AJAX requests with `async_get()`, `async_post()`+- `DualModeViewTestCase` - Tests both sync and async modes++### Key Assertion Methods+**Status**: `assertSuccessResponse()`, `assertErrorResponse()`, `assertServerErrorResponse()`+**Response Type**: `assertHtmlResponse()`, `assertJsonResponse()`+**Templates**: `assertTemplateRendered(response, template_name)`+**Session**: `assertSessionValue()`, `assertSessionContains()`+**AJAX Methods**: `async_get()`, `async_post()`, `async_put()`, `async_delete()`++### Session Management Helpers+- `setSessionViewType()`, `setSessionViewMode()`+- `setSessionLocationView()`, `setSessionCollection()`+- `setSessionViewParameters()` - Set multiple session values++## Manager Async/Sync Testing### Manager Pattern Characteristics- Singleton pattern with `__init_singleton__()`-- Both sync `ensure_initialized()` and async initialization methods-- Mix of sync methods for Django ORM access and async methods for integration services-- Thread safety considerations and shared state management+- Dual sync/async methods for Django views and integration services+- Thread safety and shared state management-### Async Testing Infrastructure+### Async Testing Requirements+**Use `AsyncManagerTestCase(TransactionTestCase)`** for async manager tests:+- Shared event loop prevents SQLite concurrency issues+- Reset singleton state between tests: `ManagerClass._instances = {}`+- Use `run_async(coroutine)` helper method+- Wrap database operations with `sync_to_async()`+### Critical ORM Pattern```python-class AsyncManagerTestCase(TransactionTestCase):- """Base class for async manager tests with proper infrastructure."""-- @classmethod- def setUpClass(cls):- super().setUpClass()- # Create a single shared event loop for all tests in this class- cls._test_loop = asyncio.new_event_loop()- asyncio.set_event_loop(cls._test_loop)-- @classmethod- def tearDownClass(cls):- if hasattr(cls, '_test_loop'):- cls._test_loop.close()- super().tearDownClass()-- def run_async(self, coro):- """Helper method to run async coroutines using the shared event loop."""- return self._test_loop.run_until_complete(coro)-- def setUp(self):- super().setUp()- # Reset singleton state for each test- ManagerClass._instances = {}- self.manager = ManagerClass()- # Clear any cached state- if hasattr(self.manager, '_recent_transitions'):- self.manager._recent_transitions.clear()-- def test_async_method(self):- """Example async test using wrapper pattern."""- async def async_test_logic():- # Use sync_to_async for database operations- entity = await sync_to_async(Entity.objects.create)(name='Test Entity')- result = await self.manager.async_method(entity)- self.assertIsNotNone(result)-- self.run_async(async_test_logic())-```--**Key Requirements:**-- **Use `TransactionTestCase`** instead of `BaseTestCase` to avoid database locking-- **Shared event loop** prevents SQLite concurrency issues with multiple async tests-- **Reset singleton state** between tests to ensure isolation-- **Wrap sync database operations** with `sync_to_async()` in async test code-- **Use `select_related()`** in manager code to prevent lazy loading in async contexts--**Critical ORM Access Pattern:**-```python-# In manager async methods - avoid lazy loading issues-event_clauses = await sync_to_async(list)(- event_definition.event_clauses.select_related('entity_state').all()+# In manager async methods - prevent lazy loading+entities = await sync_to_async(list)(+ Entity.objects.select_related('location').all())# In tests - wrap database operationsentity = await sync_to_async(Entity.objects.create)(name='Test')```-## Django-Specific Testing Patterns+## Django-Specific Patterns### Abstract Model Testing-```python-# Create concrete test class for abstract models-class ConcreteTestModel(AbstractModel):- def required_abstract_method(self):- return "test_implementation"--# Mock Django operations for database-less testing-with patch('django.db.models.Model.save') as mock_save:- instance.save()- mock_save.assert_called_once()-```+Create concrete test classes for abstract models, mock Django operations for database-less testing.-### Integration Key Pattern Testing-```python-def test_integration_key_inheritance(self):- model = TestModel.objects.create(- integration_id='test_id',- integration_name='test_integration'- )- self.assertEqual(model.integration_id, 'test_id')-```+### Integration Key Pattern+Test `IntegrationKeyMixin` inheritance with `integration_id` and `integration_name` fields.### Singleton Manager Testing-```python-def test_manager_singleton_behavior(self):- manager1 = ManagerClass()- manager2 = ManagerClass()- self.assertIs(manager1, manager2)-```--### Background Process and Threading Testing-```python-async def test_async_manager_method(self):- with patch('asyncio.run') as mock_run:- result = await manager.async_method()- mock_run.assert_called()--def test_manager_thread_safety(self):- results = []- def worker():- results.append(manager.thread_safe_operation())-- threads = [threading.Thread(target=worker) for _ in range(5)]- for t in threads:- t.start()- for t in threads:- t.join()-```+Verify singleton behavior: `self.assertIs(manager1, manager2)`-## Authentication and Permission Testing+### Authentication Testing+- Test protected views require authentication (redirect to login)+- Use `self.client.force_login(user)` for authenticated tests-```python-def test_protected_view_requires_authentication(self):- url = reverse('protected_view')- response = self.client.get(url)- login_url = reverse('login')- self.assertRedirects(response, f'{login_url}?next={url}')--def test_protected_view_with_authenticated_user(self):- self.client.force_login(self.user)- url = reverse('protected_view')- response = self.client.get(url)-- self.assertSuccessResponse(response)- self.assertHtmlResponse(response)-```--## Form Validation Testing--```python-def test_form_validation_success(self):- form_data = {'name': 'Test Entity', 'location': self.location.id}- url = reverse('entity_create')- response = self.client.post(url, form_data)-- success_url = reverse('entity_list')- self.assertRedirects(response, success_url)- self.assertTrue(Entity.objects.filter(name='Test Entity').exists())+### Form Validation Testing+- Success: Check redirects and database changes+- Errors: Form errors return 200 status, verify `assertFormError()`-def test_form_validation_errors(self):- form_data = {'name': ''} # Missing required field- url = reverse('entity_create')- response = self.client.post(url, form_data)-- self.assertSuccessResponse(response) # Form errors return 200, not 4xx- self.assertHtmlResponse(response)- self.assertTemplateRendered(response, 'entity/create.html')- self.assertFormError(response, 'form', 'name', 'This field is required.')-```--## Database Setup for Tests+## File Upload Testing-View tests should create real test data to verify complete request/response flows:+### Media Root Isolation+**Individual Tests**: Use `self.isolated_media_root()` context manager+**Test Classes**: Override `MEDIA_ROOT` in setUp/tearDown with temporary directory-```python-def setUp(self):- super().setUp()- self.location = Location.objects.create(name='Test Location')- self.entity = Entity.objects.create(- integration_id='test.entity',- integration_name='test_integration',- location=self.location- )+## Key Test Base Classes-def test_location_view_with_entities(self):- url = reverse('location_detail', kwargs={'location_id': self.location.id})- response = self.client.get(url)-- self.assertSuccessResponse(response)- self.assertHtmlResponse(response)- self.assertTemplateRendered(response, 'location/detail.html')- self.assertEqual(response.context['location'], self.location)- self.assertIn(self.entity, response.context['entities'])-```+### View Testing+- `hi.tests.view_test_base.SyncViewTestCase`+- `hi.tests.view_test_base.AsyncViewTestCase`+- `hi.tests.view_test_base.DualModeViewTestCase`-## Testing Code needing MEDIA_ROOT+### Manager Testing+- `hi.tests.view_test_base.AsyncManagerTestCase` (extends TransactionTestCase)+- Custom event loop management for async tests-```python-# Use context manager for individual test methods-def test_file_upload(self):- with self.isolated_media_root() as temp_media_root:- # File operations here- test_file = self.create_test_text_file("test.txt", "content")- # ... test logic--# OR use class-level isolation for test classes with many file operations-class TestFileOperations(BaseTestCase):- def setUp(self):- super().setUp()- self._temp_media_dir = tempfile.mkdtemp()- self._settings_patcher = override_settings(MEDIA_ROOT=self._temp_media_dir)- self._settings_patcher.enable()-- def tearDown(self):- if hasattr(self, '_settings_patcher'):- self._settings_patcher.disable()- if hasattr(self, '_temp_media_dir'):- shutil.rmtree(self._temp_media_dir, ignore_errors=True)- super().tearDown()-```+### Utilities+- `hi.tests.view_test_base.ViewTestBase` - Common utilities and assertions+- Session management helpers+- File operation helpers with media root isolation## Related Documentation-- Testing guidelines: [Testing Guidelines](testing-guidelines.md)-- UI testing: [UI Testing](../frontend/ui-testing.md)-- Backend testing: [Backend Guidelines](../backend/backend-guidelines.md#testing)+- [Testing Guidelines](testing-guidelines.md)+- [UI Testing](../frontend/ui-testing.md)+- [Backend Guidelines](../backend/backend-guidelines.md)diff --git a/docs/dev/workflow/release-process.md b/docs/dev/workflow/release-process.mdindex 1501bc1c..cc63935d 100644--- a/docs/dev/workflow/release-process.md+++ b/docs/dev/workflow/release-process.md@@ -97,10 +97,22 @@ This is where the automated release process ends.## Post-Release Tasks (Manual)+### Refine Release++- Read and refine the release notes on the github page.+- Attach an image to the release+### Validate Install Script Works+Check github actions for completion of Docke rimage building.+Test the single-command installation script (this must be done manually):```+DATE=`date '+%Y-%m-%d'`+mkdir ~/testing+cd ~/testing+mv ~/.hi ~/.hi-$DATE+curl -fsSL https://raw.githubusercontent.com/cassandra/home-information/master/install.sh | bash```diff --git a/docs/dev/workflow/workflow-guidelines.md b/docs/dev/workflow/workflow-guidelines.mdindex 0158180e..a96ed620 100644--- a/docs/dev/workflow/workflow-guidelines.md+++ b/docs/dev/workflow/workflow-guidelines.md@@ -35,13 +35,17 @@ git checkout -b feature/42-entity-icons- Make logical commits with clear messages- Focus on **what** changed and **why**, not implementation details- Keep commits focused and atomic+- Do not add any extra attributions.+- Do not uses marketing-like language-### 4. Push Branch+### 4. Push Branch (at checkpoints and when done)```bashgit push -u origin feature/42-entity-icons```### 5. Create Pull Request+Use pull request template: `.github/PULL_REQUEST_TEMPLATE.md`:+Use GitHub CLI or web interface:```bashgh pr create --title "Add entity icon system" --body "$(cat <<'EOF'@@ -111,48 +115,21 @@ Remove invalid AlertUrgency.PAST enum value for weather alerts**SHOULD NOT:**- Generic messages like "update code" or "fix bug"+- Flowery or marketing-like boasts about the changes## Pre-PR Requirements**MANDATORY checks before creating any PR:**```bash-# 1. Run full test suite (must pass)-make test-# 2. Run code quality check (must pass with no output)-make lint+# 1. Run code quality check (must pass with no output)+cd $PROJ_ROOT ; make lint+# 2. Run full test suite (must pass)+cd $PROJ_ROOT ; make test```-Both checks must pass before PR creation. Fix all issues first.--## Pull Request Guidelines--### PR Description Structure--Follow `.github/PULL_REQUEST_TEMPLATE.md`:--```markdown-## Pull Request: [Short Title]--### Issue Link-Closes #123--### Summary-- Brief overview of changes-- Key components modified-- Business impact--### Testing-- [ ] Tests pass-- [ ] Integration tests pass-- [ ] Manual testing completed--### Documentation-- [ ] Code comments updated-- [ ] Documentation files updated-- [ ] Breaking changes documented-```+Both checks must pass before PR creation. Fix all issues first. Run `make lint` first because it is faster and any lint changes will also require re-running `make test`.### PR Review Process@@ -175,5 +152,6 @@ See [Release Process](release-process.md) for detailed release procedures.## Related Documentation- Release procedures: [Release Process](release-process.md)+- Rollback procedures: [Rollback Process](rollback-process.md)- Documentation standards: [Documentation Standards](documentation-standards.md)-- Coding standards: [Coding Standards](../shared/coding-standards.md)+- Design procedures: [Design Workflow](design-workflow.md)