Technical: Entities States

Target Audience: Developers, automation creators, dashboard builders Covers: Cross-domain entity architecture, shared state concepts, and where to find canonical contracts

---

Purpose of this page

This page is the cross-domain hub for entity architecture. It intentionally avoids duplicating deep contracts that are owned by domain-specific technical pages.

Use this page to:

• Understand entity families at a system level
• Locate canonical contract docs for each domain
• Apply shared automation and naming stability patterns

---

Canonical technical contracts

Domain	Canonical technical page	Owns
Users and role/capability mapping	Technical: Users	User capability matrix, what gets created by role
Chore lifecycle entities	Technical: Chores	Chore states, actionability flags, chore status/aggregate attributes
Points and transactions	Technical: Points	Point sensor attributes, transaction flows, point-related button patterns
Badge and progression entities	Technical: Badges	Badge sensors, progression status, badge metadata and links
Notifications internals	Technical: Notifications	Notification payloads, routing, and delivery behavior

---

Cross-domain entity families

User-scoped entities

These follow user profile naming:

• sensor.<user>_choreops_*
• button.<user>_choreops_*
• calendar.<user>_choreops

System-scoped entities

These represent global/shared state across users and definitions:

• Shared chore global state entities
• System badge/achievement/challenge entities
• Optional aggregate system sensors (for example pending approvals)

---

Shared state concepts

These concepts appear across domains and are best treated consistently in automations and dashboards:

• Actionability flags: Prefer explicit booleans such as can_claim and can_approve
• Button indirection: Prefer *_button_eid attributes over constructing entity IDs
• Lifecycle states: pending, due, claimed, approved, overdue, missed, and shared-flow variants
• Time-windowed metrics: *_today, *_week, *_month, plus all-time counters

---

Automation-safe guidelines

• Gate actions by boolean capability/availability attributes, not by guessed state text alone
• Resolve runtime entity IDs from pointers or entity registry selections
• Avoid hard-coding assumptions about localized display names
• Use domain technical pages for exact state/attribute contracts before writing production automations

---

Related documentation

• Technical: Users
• Technical: Chores
• Technical: Points
• Technical: Badges
• Technical: Notifications

---

Last Updated: February 2026 (cross-domain hub refactor)