Entities

The Tech Strategy Tool’s domain model consists of a hierarchy of strategy entities. This page documents each entity type, its fields, behaviors, and relationships.

Entity Hierarchy

All entities live within a single Strategy document held in memory by the event processor. There are no separate database tables for entities — the state is derived entirely from events.

Strategy

The root document containing all teams. There is exactly one Strategy instance in the system.

Field	Type	Description
Teams	List<Team>	Ordered list of all teams

Team

A team represents an engineering group with its own strategy space. Teams are the top-level organizational unit.

Implements INamedEntity.

Field	Type	Description
Id	Guid	Unique identifier
Name	string	Display name
NameSequence	long	Sequence number of the last update_name event for this entity
Color	string	Hex color code (e.g., #3498db) used for UI theming
Principles	List<Principle>	Ordered list of guiding principles
Objectives	List<Objective>	Ordered list of measurable goals
Groups	List<Group>	Ordered list of groups for organizing objectives

Behaviors

• Color validation: The Color field must be a valid 6-digit hex color code (e.g., #3498db). The processor validates this on create and update.
• Cascading delete: Deleting a team removes all of its groups, principles, objectives, and initiatives.
• Admin-only operations: Creating, renaming, recoloring, and deleting teams require admin role.

Group

A grouping mechanism for objectives within a team. Groups provide visual organization in the Objectives view.

Implements INamedEntity, IDescribedEntity, and IOrderableEntity.

Field	Type	Description
Id	Guid	Unique identifier
Name	string	Display name
NameSequence	long	Sequence number of the last update_name event for this entity
Description	string	Optional description
DescriptionSequence	long	Sequence number of the last update_description event for this entity
OrderSequence	long	Sequence number of the last reorder_entity event for this entity

Behaviors

• Cascading ungroup: Deleting a group unassigns all objectives from it (they become ungrouped), but does not delete the objectives.
• Deferred creation: In the UI, clicking “Add Group” creates a local-only placeholder rendered with the name field in edit mode. The create_entity event (with targetType: "Group") is only submitted after the user provides a name. Pressing Escape or leaving the name empty discards the placeholder with no server interaction.
• Reordering: Groups can be reordered within a team via reorder_entity with targetType: "Group".
• Conflict detection: Name and description edits (via update_name and update_description) support lastSeenSequence.

Principle

A guiding belief or standard that a team follows. Principles represent the “why” behind technology decisions.

Implements INamedEntity, IDescribedEntity, and IOrderableEntity.

Field	Type	Description
Id	Guid	Unique identifier
Name	string	Principle name (supports *highlight* syntax)
NameSequence	long	Sequence number of the last update_name event for this entity
Description	string	Detailed description
DescriptionSequence	long	Sequence number of the last update_description event for this entity
OrderSequence	long	Sequence number of the last reorder_entity event for this entity

Behaviors

• Highlight syntax: Principle names support *highlighted text* notation. Text between asterisks is rendered in the team color in the UI.
• Cross-team assignment: Principles can be copied to other teams via assign_principle_to_objective. This creates an independent copy — changes to one do not affect the other.
• Cascading reference removal: Deleting a principle removes it from the PrincipleIds list of all objectives in the same team.
• Deferred creation: In the UI, clicking “Add Principle” creates a local-only placeholder rendered with the name field in edit mode. The create_entity event (with targetType: "Principle") is only submitted after the user provides a name. Pressing Escape or leaving the name empty discards the placeholder with no server interaction.
• Conflict detection: Name and description edits (via update_name and update_description) support lastSeenSequence for concurrent edit detection.

Objective

A measurable goal aligned to one or more principles. Objectives track progress through their initiatives.

Implements INamedEntity and IOrderableEntity.

Field	Type	Description
Id	Guid	Unique identifier
Name	string	Objective name
NameSequence	long	Sequence number of the last update_name event for this entity
GroupId	Guid?	Optional group assignment
OrderSequence	long	Sequence number of the last reorder_entity event for this entity
PrincipleIds	List<Guid>	IDs of linked principles
Initiatives	List<Initiative>	Ordered list of initiatives

Behaviors

• Group assignment: Objectives can be assigned to a group. Unassigned objectives appear in an “Ungrouped” section.
• Principle links: Objectives link to principles by reference (not copies).
• Progress aggregation: Total progress is computed from the average of all initiative progress values.
• Reordering: Objectives can be reordered within a group via reorder_entity with targetType: "Objective". The index is group-slice-relative (0 = first within the group).
• Cascading delete: Deleting an objective removes all of its initiatives.
• Deferred creation: In the UI, clicking “Add Objective” creates a local-only placeholder rendered with the name field in edit mode. The create_entity event (with targetType: "Objective") is only submitted after the user provides a name. Pressing Escape or leaving the name empty discards the placeholder with no server interaction.
• Conflict detection: Name edits (via update_name) support lastSeenSequence.

Initiative

A concrete project or work item that drives progress on an objective.

Implements INamedEntity and IOrderableEntity.

Field	Type	Description
Id	Guid	Unique identifier
Name	string	Initiative name
NameSequence	long	Sequence number of the last update_name event for this entity
Progress	int	Completion percentage (0-100)
OrderSequence	long	Sequence number of the last reorder_entity event for this entity
JiraKey	string?	Optional Jira issue key

Behaviors

• Progress range: Progress must be between 0 and 100 inclusive.
• Deferred creation: In the UI, initiatives are created in a “pending” state — the create_entity event (with targetType: "Initiative") is only submitted after the user provides a name.
• Reordering: Initiatives can be reordered within their objective via reorder_entity with targetType: "Initiative".
• Conflict detection: Name edits (via update_name) support lastSeenSequence.

Collections and Ordering

All collections in the domain model use List<T>, which preserves insertion order and supports insert-at-index operations. This is important for:

• Display order: Entities are displayed in their list order in the UI
• Reorder events: reorder_entity specifies a target index; the entity type determines which list is reordered
• Drag-and-drop: The UI allows users to reorder entities via drag-and-drop, which maps to reorder_entity events

Field Limits

The processor enforces maximum lengths on all text fields. See Event Types for the complete list.

Model Classes

Domain model classes and interfaces live in src/TechStrat.Core/Model/. The classes are plain C# classes with { get; set; } properties — mutable, since the event processor modifies them in-place during event processing.

src/TechStrat.Core/Model/
  INamedEntity.cs      — interface: Id, Name, NameSequence
  IDescribedEntity.cs  — interface: Description, DescriptionSequence
  IOrderableEntity.cs  — interface: OrderSequence
  Strategy.cs
  Team.cs              — implements INamedEntity
  Group.cs             — implements INamedEntity, IDescribedEntity, IOrderableEntity
  Principle.cs         — implements INamedEntity, IDescribedEntity, IOrderableEntity
  Objective.cs         — implements INamedEntity, IOrderableEntity
  Initiative.cs        — implements INamedEntity, IOrderableEntity

These classes have no external dependencies and no behavior — they are pure data containers. All business logic lives in the EventProcessor. The INamedEntity, IDescribedEntity, and IOrderableEntity interfaces enable the generic update_name, update_description, and reorder_entity handlers to operate across entity types without per-type dispatch.