Developer Glossary
This glossary defines the ubiquitous language used throughout the CO2 Asset Management Platform domain. Terms are organized by bounded contexts and cross-cutting concepts to maintain consistency across the entire system.
Looking for user-friendly term definitions? See the User Glossary.
Cross-Cutting Concepts
Section titled “Cross-Cutting Concepts”Accountability
Section titled “Accountability”Definition: The state of being responsible for specific obligations or outcomes. Usage: Every domain action creates accountability through responsibilities. Example: “The asset installation creates accountability for documentation verification.”
Responsibility
Section titled “Responsibility”Definition: A contract between the system and a user, representing an obligation that must be fulfilled. Usage: The semantic heart of the platform - bridges identity and action. Example: “A responsibility is created when an asset needs maintenance.”
Definition: A fact that has occurred in the domain, representing a change in state. Usage: Used for communication between bounded contexts. Example: “AssetInstalled event triggers responsibility creation.”
Entity
Section titled “Entity”Definition: An object with a distinct identity that persists over time. Usage: Core business objects that have lifecycle and state. Example: “User, Site, and Asset are entities.”
Value Object
Section titled “Value Object”Definition: An immutable object defined by its attributes rather than identity. Usage: Represents business values with validation and behavior. Example: “Coordinate, Email, and DueDate are value objects.”
Definition: An immutable value object representing a monetary amount with its associated currency, stored internally as integer minor units (e.g., cents) to avoid floating-point precision issues.
Usage: Used for pricing in listings, estimated costs in proposals, and as a custom field type.
Example: Money.gbp(199.99) represents £199.99.
Aggregate
Section titled “Aggregate”Definition: A cluster of domain objects treated as a single unit for data changes. Usage: Ensures consistency boundaries in the domain. Example: “Site aggregate includes Site entity and related Zone entities.”
Intent
Section titled “Intent”Definition: A user-facing command that expresses what the user wants to do.
Usage: The unit of rollback and unit of audit in the Nomos framework.
Example: CreateAssetIntent(name: 'HVAC-001') creates a new asset.
Co2Workspace
Section titled “Co2Workspace”Definition: A type-safe sealed class representing a workspace in the CO2 domain.
Usage: Use UserWorkspace, EstateWorkspace, or CatalogueWorkspace instead of raw NomosWorkspaceId.
Example: EstateWorkspace(estateId).toNomos instead of NomosWorkspaceId(estateId.value).
Identity Context
Section titled “Identity Context”Definition: A person who interacts with the system, with authentication and profile data. Usage: Represents human users of the platform.
Organization
Section titled “Organization”Definition: A business entity that owns or manages assets and sites. Usage: Groups users and defines organizational boundaries.
Definition: A collection of permissions that define what actions a user can perform. Usage: Groups related permissions for easier management.
Site User
Section titled “Site User”Definition: A user’s relationship to a specific site, including role and granular permissions. Usage: Manages site-specific access control and permissions.
Layer Permission
Section titled “Layer Permission”Definition: Granular permission for a user to access a specific layer within a site. Usage: Allows fine-tuned control over which users can view or modify specific layers.
Permissions Context
Section titled “Permissions Context”Permission
Section titled “Permission”Definition: A specific right to perform an action on a resource. Usage: Granular access control for security.
Definition: The boundary within which a permission applies. Usage: Limits permission to specific resources or areas.
ResourceType
Section titled “ResourceType”Definition: Strongly-typed classification of permission resource kinds (estate, site, layer, feature).
Usage: Use ResourceType.<kind>.name where APIs expect string resourceType.
Permission Inheritance
Section titled “Permission Inheritance”Definition: Automatic granting of permissions based on higher-level roles or relationships. Usage: Simplifies permission management by cascading access from site roles.
Estate Structures Context
Section titled “Estate Structures Context”Estate
Section titled “Estate”Definition: The highest level of spatial organization representing a company’s entire property portfolio. Usage: Groups sites under common ownership and manages estate-wide business invariants.
Definition: A specific physical location where assets are installed and managed.
Usage: Managed by SiteRootAggregate with geographic coordinates and spatial boundaries.
Building
Section titled “Building”Definition: A physical structure within a Site that may contain one or more floors.
Usage: Identified by BuildingId; can have an optional footprint polygon.
Definition: A contained space on a Floor with a name, type, and optional area.
Usage: Created with CreateRoomDirective; spatial geometry lives in topology features.
SiteTopologyAggregate
Section titled “SiteTopologyAggregate”Definition: The domain aggregate that manages a site’s spatial model (boundaries, footprints, rooms, tiles). Usage: Central point for all spatial data within a site.
GeoFeature
Section titled “GeoFeature”Definition: A spatial feature within SiteTopology describing geometry and semantics.
Usage: Stores featureId, kind, optional level, typed geometry.
MapTile
Section titled “MapTile”Definition: A first-class, typed value object representing a placed tile image in map space. Usage: Contains MapTileId, siteId, optional buildingId/level, geometry, attachmentId.
Catalogues Context
Section titled “Catalogues Context”Catalogue
Section titled “Catalogue”Definition: A collection of listings with associated metadata, ownership, and an optional link to a taxonomy. Usage: Groups related listings under a common organizational structure.
Listing
Section titled “Listing”Definition: A standardized, specification-driven definition of an asset offering. Usage: Serves as a template for creating trackable assets.
Taxonomy
Section titled “Taxonomy”Definition: A hierarchical classification system that organizes listings into categories and subcategories. Usage: Provides consistent categorization and drives category-specific specifications.
Custom Field Definition
Section titled “Custom Field Definition”Definition: A configurable metadata field that defines a specific data point to be collected. Usage: Enables flexible, taxonomy-driven data collection with type-safe field definitions.
Trackable Asset Context
Section titled “Trackable Asset Context”TrackableAssetAggregate
Section titled “TrackableAssetAggregate”Definition: The root domain aggregate for individual trackable assets. Usage: Manages the asset’s identity, metadata, status, custom fields, and structural assignment.
Asset Status
Section titled “Asset Status”Definition: The current operational state of an asset. Usage: Tracks whether an asset is live, draft, decommissioned, or in another lifecycle state.
StructuralAssignment
Section titled “StructuralAssignment”Definition: A value object linking a TrackableAsset to its placement within the estate structure hierarchy. Usage: Stored on the asset aggregate to define its physical context.
AssetComment
Section titled “AssetComment”Definition: A textual or media-based note attached to a trackable asset. Usage: Stores commentary from users along with optional voice note, photo, or video attachments.
Responsibilities Context
Section titled “Responsibilities Context”ResponsibilityAggregate
Section titled “ResponsibilityAggregate”Definition: The domain aggregate that manages a single responsibility (obligation). Usage: Tracks assignments, status, due dates, and checklist progress.
ChecklistItemStatus
Section titled “ChecklistItemStatus”Definition: A value object representing the completion state of a checklist item. Usage: Stores whether an item is done, who did it, when, and any associated notes.
Due Date
Section titled “Due Date”Definition: The date by which a responsibility must be completed. Usage: Creates urgency and tracks deadlines.
Proposals Context
Section titled “Proposals Context”ProposalAggregate
Section titled “ProposalAggregate”Definition: The root domain aggregate for change requests and approval workflows. Usage: Manages the proposal’s lifecycle, impact assessments, and proposed modifications.
ImpactAssessment
Section titled “ImpactAssessment”Definition: A value object representing a technical, financial, or carbon impact analysis. Usage: Provides data-driven justification for proposed changes.
ReplacementEdge
Section titled “ReplacementEdge”Definition: A value object defining the replacement link between retiring assets and new listings. Usage: Used in asset replacement proposals.
Attachments Context
Section titled “Attachments Context”Attachment
Section titled “Attachment”Definition: A content-addressed file entity with metadata and associations to domain targets. Usage: Identified by the SHA256 hash of its content (AttachmentId).
BlobRef
Section titled “BlobRef”Definition: A reference to content-addressed blob storage (managed by Nomos). Usage: Populated by Nomos upon ingest; includes uri, sha256, mediaType, and lengthBytes.
AttachmentTarget
Section titled “AttachmentTarget”Definition: A strongly-typed union describing where an attachment is linked. Usage: Encapsulates kind and the typed ID (EstateId, SiteId, TrackableAssetId, etc.).
Voice Note
Section titled “Voice Note”Definition: An audio recording attached to an asset for field observations or quick documentation. Usage: Created via CreateAttachmentIntent with AttachmentRole.voiceNote.
Insights Context
Section titled “Insights Context”InsightAggregate
Section titled “InsightAggregate”Definition: The root aggregate for analytical findings and data-driven observations. Usage: Manages the state of KPIs, reports, and automated compliance checks.
KPI (Key Performance Indicator)
Section titled “KPI (Key Performance Indicator)”Definition: A measurable metric that indicates performance or progress. Usage: Tracks important business metrics.
Dashboard
Section titled “Dashboard”Definition: A visual display of KPIs and insights for monitoring. Usage: Provides overview of system performance.
Drawing Export
Section titled “Drawing Export”Definition: The process of exporting a drawing’s contents in a specified format. Usage: Allows users to download drawing data as CSV, GeoJSON, PNG, or PDF.
Feedback Context
Section titled “Feedback Context”FeedbackAggregate
Section titled “FeedbackAggregate”Definition: The root aggregate for user-submitted feedback, bug reports, and feature suggestions. Usage: Captures and manages user sentiment and system issues.
Funding Programs Context
Section titled “Funding Programs Context”FundingApplicationAggregate
Section titled “FundingApplicationAggregate”Definition: The root aggregate for managing applications to funding grants. Usage: Tracks progress of funding requests including eligibility checks and approval status.
Licensing Context
Section titled “Licensing Context”Licence
Section titled “Licence”Definition: A formal permission or authorization granted to use system resources or features. Usage: Controls access to system capabilities and tracks usage rights.
Testing Terms
Section titled “Testing Terms”Unit Test
Section titled “Unit Test”Definition: A test that verifies individual components in isolation. Usage: Ensures pure domain logic works correctly.
Integration Test
Section titled “Integration Test”Definition: A test that verifies interaction between components. Usage: Ensures components work together correctly.
Documentation Terms
Section titled “Documentation Terms”Bounded Context
Section titled “Bounded Context”Definition: A boundary within which a particular model applies and terminology has specific meaning. Usage: Organizes domain into manageable, cohesive areas.
Ubiquitous Language
Section titled “Ubiquitous Language”Definition: A common language shared by domain experts and developers within a bounded context. Usage: Ensures consistent terminology and understanding.
This glossary serves as the foundation for ubiquitous language across the entire CO2 Asset Management Platform. All code, documentation, and conversations should use these terms consistently.
For the complete glossary with all terms, see dart_packages/co2/GLOSSARY.md in the source repository.