Architecture

Asset Intelligence is designed as a structured system that separates sensing, decision-making, state management, and presentation.

This architecture ensures consistency, accuracy, and long-term maintainability.

---

Core Philosophy

Asset Intelligence follows three key principles:

• Separate data collection from decision-making
• Separate decision-making from state changes
• Separate logic from presentation

Each layer has a clearly defined responsibility.

---

System Layers

The system is composed of four primary layers:

1. Environment (Sensing)
2. Evaluation (Decision Engine)
3. Coordinator (Runtime Management)
4. Entities (Presentation)

---

1. Environment Layer (Sensing)

The environment layer is responsible for collecting and structuring environmental data.

It answers:

“What is happening in the room?”

---

Inputs

• Home Assistant sensors
• External environment (sun position, weather)
• System context (HVAC, airflow)

---

Output

A structured room environment model including:

• Temperature
• Humidity
• Light (Lux / UV)
• Air quality
• CO₂
• Particulates
• Mold index
• Leak detection
• Sun position
• Sensor confidence

---

Important Characteristics

• Does not evaluate risk
• Does not store data
• Does not trigger events

It only describes current conditions.

---

2. Evaluation Layer (Decision Engine)

The evaluation layer determines the current risk state for each asset.

It answers:

“Based on current conditions, what should the risk state be?”

---

Inputs

• Asset environment requirements
• Room environment snapshot

---

Output

• Risk state (Green, Amber, Red)
• Candidate state
• Risk reasons
• Signals used
• Debounce action

---

Important Characteristics

• Pure logic (no side effects)
• Does not write to storage
• Does not generate events
• Does not perform advisory logic

It provides a deterministic answer based only on available data.

---

3. Coordinator (Runtime Brain)

The coordinator is the central runtime engine of the system.

It answers:

“What changed, what should be recorded, and what should be shown?”

---

Responsibilities

• Runs evaluation cycles
• Applies debounce rules
• Determines effective risk state
• Detects transitions
• Generates events
• Produces advisory insights
• Maintains runtime projections
• Writes changes to storage

---

Inputs

• Environment layer output
• Evaluation results
• Stored asset data

---

Outputs

• Updated asset state
• Event records (environment, advisory, activity)
• Advisory signals
• Projection data for UI

---

Important Characteristics

• Only layer that creates events
• Only layer that manages state transitions
• Only layer that generates advisory insights

---

4. Entities (Presentation Layer)

Entities expose system state to Home Assistant and the UI.

They answer:

“What is the current state of the system?”

---

Examples

• Risk state sensor
• Candidate state
• Advisory text
• Environment snapshot

---

Important Characteristics

• Read-only
• No logic
• No evaluation
• No state changes

Entities display what the coordinator has already determined.

---

Data Flow

The system follows a strict flow:

Environment → Evaluation → Coordinator → Entities → UI

---

Step-by-Step

1. Sensors update
2. Environment model is built
3. Evaluation computes risk
4. Coordinator processes results
5. State changes and events are recorded
6. Entities reflect updated state
7. UI displays results

---

Separation of Responsibilities

Each layer has strict boundaries:

Layer	Responsibility	Does NOT Do
Environment	Sensing	Evaluation, storage
Evaluation	Decision logic	Events, storage, advisory
Coordinator	State + events + advisory	Sensor reading, rule definition
Entities	Display	Logic, storage

---

Why This Design Matters

This architecture ensures:

• Deterministic risk evaluation
• No duplicated logic
• Clear system behavior
• Consistent UI output
• Easy troubleshooting
• Maintainable long-term structure

---

Advisory Layer (Within Coordinator)

Advisory logic is part of the coordinator but separate from risk evaluation.

---

Risk vs Advisory

• Risk tells you the current condition
• Advisory explains what to understand or consider

---

Examples

Risk:

• RED → humidity too high

Advisory:

• "Reduce humidity to protect sensitive assets"
• "No UV data available"
• "Consider adding a light sensor"

---

Event Model

All changes are recorded as events.

Event types include:

• Environment events
• Risk transitions
• Advisory events
• Activity events
• Document events
• Custody events

These power the Activity and Auditing system.

---

Storage Model

The system stores:

• Asset definitions
• Room configuration
• Event history
• Document references
• Policy data

It does not store:

• Raw sensor data
• Derived UI projections
• Temporary runtime values

---

Relationship to Home Assistant

Asset Intelligence integrates deeply with Home Assistant:

• Assets are devices
• Areas define rooms
• Labels define categorization
• Entities expose state
• Automations perform actions

---

Design Goals

This architecture was designed to:

• Use Home Assistant as the system of record
• Avoid data duplication
• Provide explainable outcomes
• Support advanced advisory logic
• Enable automation without forcing behavior

---

What This Means for Users

You don’t need to understand the code.

But understanding the structure helps explain:

• Why risk behaves consistently
• Why missing sensors affect results
• Why advisory messages appear
• Why automations are external
• Why the system is reliable

---

Summary

• Environment detects conditions
• Evaluation determines risk
• Coordinator manages state and generates insight
• Entities display results
• Home Assistant executes actions

---

Asset Intelligence is designed to be predictable, explainable, and extensible.

It separates knowing from deciding, and deciding from acting. ``