Terminology
Consistent language is part of the module boundary. These terms apply to Go packages, types, API documentation, events, database changes, tests, and architecture discussions.
Device terminology
Device
A catalog definition of a kind of medical equipment. It describes shared classification or product information and is not a uniquely tracked physical item.
Examples of related catalog concepts include manufacturer, brand, model, category, type, function, regulatory class, and application risk.
Device record
A uniquely tracked physical device managed by an organization or facility. A device record can have a serial number, location, department, operational status, acquisition information, utilization data, images, maintenance history, and lifecycle state.
Use DeviceRecord when code operates on the physical item. Do not shorten it to Device when doing so makes it ambiguous with the catalog definition.
Devices module
The module that owns device catalog definitions, device records, images, imports, utilization, and lifecycle behaviour.
Use the directory and package name devices for this module.
Device lifecycle and device retirement
Use DeviceLifecycle and DeviceRetirement for lifecycle behaviour involving a physical device record.
Asset
Do not use asset as an internal synonym for device or device record.
The word may appear at an external integration boundary when an external standard or provider requires it. Translate it to the canonical Ovahol term at that boundary. Existing identifiers containing asset are legacy names to be handled deliberately during module extraction; Slice 0 does not rename public API or database contracts.
Architecture terminology
Module
A business-owned vertical slice containing the behaviour and adapters for a cohesive capability. A module is an in-process boundary, not an independently deployed microservice.
Application
An executable composition and process boundary, such as the API, worker, or scheduler. Applications assemble modules and platform implementations.
Service
An application or domain component that implements a business use case. A service is not automatically a deployable network service.
Public module API
The deliberately small set of interfaces and contract types through which other modules interact with a module. It does not include HTTP DTOs, repositories, generated database types, or concrete service implementations.
Port
An interface representing a capability required by a module. Prefer defining the interface in the consuming module so it contains only the operations the consumer needs.
Adapter
A concrete implementation that connects a port to a technology or another module, such as PostgreSQL, Valkey, object storage, email, or Kafka.
Platform
Shared technical infrastructure with no Ovahol business policy, such as database lifecycle, caching, messaging, storage, mail, payment-provider clients, and observability.
Shared
A deliberately small area for stable technical or value types that have no clear business owner. shared must not become a new global common or utils directory.
Domain event
A versioned statement that a meaningful business fact has occurred, for example work-order.completed.v1. It is not a generic notification that a row was inserted or updated.
Transactional outbox
A PostgreSQL-backed mechanism that stores a business change and its event in the same transaction. A worker later delivers the event reliably.
Naming conventions
- Module directories use clear business nouns:
devices,maintenance,billing. - Go types use the most precise business name:
DeviceRecord, notAssetor an ambiguousItem. - Event names use past-tense business facts and a version suffix:
device-record.retired.v1. - Valkey keys begin with application and environment and include tenant scope for tenant-owned data:
ovahol:production:idempotency:{tenantID}:fault-report:{requestID}. - Avoid new packages named
common,utils,core, ormisc. Give code an owner or a specific technical purpose.