Skip to content

Ubiquitous Language - Audit Trail Platform (ATP)

One language to rule them all — ATP's ubiquitous language ensures domain experts, developers, and stakeholders speak the same language, from conversations to code to documentation.

📋 Documentation Generation Plan

This document will be generated in 6 cycles. Current progress:

Cycle Topics Estimated Lines Status
Cycle 1 Ubiquitous Language Fundamentals & Core Concepts (1-2) ~2,500 ⏳ Not Started
Cycle 2 Aggregates, Entities & Value Objects Terms (3-4) ~3,000 ⏳ Not Started
Cycle 3 Events, Commands & Domain Services (5-6) ~2,500 ⏳ Not Started
Cycle 4 Bounded Contexts & Integration Terms (7-8) ~2,500 ⏳ Not Started
Cycle 5 Technical & Infrastructure Terms (9-10) ~2,500 ⏳ Not Started
Cycle 6 Compliance, Security & Operational Terms (11-12) ~2,500 ⏳ Not Started

Total Estimated Lines: ~15,500

Purpose & Scope

This document establishes the ubiquitous language for the ConnectSoft Audit Trail Platform (ATP), defining a shared vocabulary used consistently across domain models, code, documentation, and conversations to ensure clear communication between domain experts, developers, and all stakeholders without ambiguity or translation errors.

Key Ubiquitous Language Principles - One Language Everywhere: Same terms in conversations, code, documentation, UI, and APIs - Domain-Centric: Language reflects business domain, not technical implementation - Shared Understanding: Domain experts and developers use identical terminology - Living Language: Evolves with domain understanding, never static - No Jargon: Technical terms only when necessary and domain-relevant - Context-Bound: Terms may have different meanings in different bounded contexts - Explicit Disambiguation: Clear definitions prevent misunderstandings

What this document covers

  • Establish ubiquitous language fundamentals: What it is, why it matters, how ATP applies it
  • Define core domain concepts: Central terms that form ATP's business domain
  • Document aggregate terms: Names and definitions for all aggregates and their components
  • Catalog entity and value object terms: All domain objects with precise definitions
  • Specify event and command terminology: Action-based language with past-tense events
  • Define bounded context vocabulary: Context-specific terms and translations
  • Document process and workflow terms: Business processes and their stages
  • Catalog technical domain terms: Domain-relevant technical concepts
  • Define compliance and regulatory terms: GDPR, HIPAA, SOC 2 terminology
  • Specify operational terms: SRE, monitoring, and incident vocabulary
  • Document anti-patterns: Terms to avoid, ambiguous language, jargon
  • Establish language governance: How language evolves, who decides, documentation process

Out of scope (referenced elsewhere)

Readers & ownership

  • Domain Experts/Product (owners): Define and refine business terminology, validate definitions
  • All Developers: Use ubiquitous language in code, ensure consistency
  • Technical Writers: Use ubiquitous language in all documentation
  • Architects: Ensure language consistency across bounded contexts
  • QA/Test Engineers: Use ubiquitous language in test scenarios and specifications
  • Product Managers: Use ubiquitous language in requirements and user stories
  • Customer Success: Use ubiquitous language when communicating with customers

Artifacts produced

  • Ubiquitous Language Glossary: Alphabetical reference of all domain terms
  • Term Definitions: Each term with definition, synonyms, examples, and usage
  • Contextual Translations: Term meanings across different bounded contexts
  • Concept Maps: Visual relationships between related terms
  • Code Examples: How terms appear in code (class names, method names, properties)
  • Anti-Pattern Guide: Terms to avoid, ambiguous language, deprecated terms
  • Language Evolution Log: History of term changes, additions, and deprecations
  • Onboarding Guide: Teaching ubiquitous language to new team members
  • Language Validation Checklist: Ensuring consistency in code and documentation
  • Cross-Reference Index: Links between terms and documentation

Acceptance (done when)

  • All core domain terms are defined with clear, unambiguous definitions
  • Code examples show how each term appears in the codebase (classes, methods, properties)
  • Usage guidelines explain when and how to use each term correctly
  • Synonyms and variations are documented with preferred canonical terms
  • Cross-references link related terms and concepts
  • Bounded context translations show how terms differ across contexts
  • Anti-patterns document what NOT to say and why
  • Evolution process is documented for adding, changing, or deprecating terms
  • Validation tools help enforce language consistency (linters, code reviews)
  • Onboarding materials teach new team members the ubiquitous language
  • Documentation complete with comprehensive glossary, examples, and cross-references

Detailed Cycle Plan

CYCLE 1: Ubiquitous Language Fundamentals & Core Concepts (~2,500 lines)

Topic 1: Ubiquitous Language Fundamentals

What will be covered:

  • What is Ubiquitous Language?
  • Definition from Domain-Driven Design
  • Why it matters in software development
  • Problems it solves (translation errors, ambiguity)

  • Benefits for ATP (clarity, consistency, maintainability)

  • Ubiquitous Language in Practice

  • Same language in conversations, code, documentation, UI
  • No translation between business and technical terms
  • Code reflects domain language exactly

  • Documentation uses domain terms without jargon

  • Language in Code

  • Class names reflect domain terms (AuditEvent, EventStream, Tenant)
  • Method names use domain verbs (Classify, Seal, Archive)
  • Properties use domain attributes (Classification, RetentionPeriod)

  • Avoid technical jargon (Factory, Repository, Service in domain layer)

  • Language in Documentation

  • User stories use ubiquitous language
  • Technical docs use same terms as code
  • API documentation reflects domain language

  • Help text uses familiar domain terms

  • Language Evolution

  • Living language that grows with domain understanding
  • Refactoring code when language changes
  • Updating documentation when terms evolve

  • Deprecating old terms gracefully

  • Language Governance

  • Domain experts are authority on terminology
  • Collaborative refinement in modeling sessions
  • Documentation as single source of truth

  • Code review enforces language consistency

  • ATP Ubiquitous Language Philosophy

  • Audit and compliance terminology takes precedence
  • Business language over technical jargon
  • Legal and regulatory terms preserved exactly
  • Multi-tenant language explicit (Tenant, TenantId)
  • Event-centric language (past-tense event names)

Code Examples: - Good vs bad class naming - Good vs bad method naming - Domain-driven vs technical naming - Ubiquitous language in code comments

Diagrams: - Ubiquitous language in DDD - Language consistency layers - Terminology flow (conversations → code → docs)

Deliverables: - Ubiquitous language guide - Naming conventions - Code review checklist - Documentation standards

Topic 2: Core Domain Concepts

What will be covered:

  • Audit Event
  • Definition: An immutable record of something that happened in a system, captured for compliance, security, or operational purposes
  • Synonyms: Event, Audit Record, Audit Entry, Log Entry (avoid "log")
  • Not to be confused with: Domain Event (internal), Integration Event (cross-context)
  • Usage: "The system ingested 1,000 Audit Events per second"
  • Code: AuditEvent class, IAuditEvent interface

  • Related Terms: Event Stream, Ingestion, Classification, Retention

  • Event Stream

  • Definition: An ordered, immutable sequence of Audit Events related to a specific subject (user, resource, transaction)
  • Synonyms: Stream, Event Sequence, Audit Trail (for a subject)
  • Usage: "The Event Stream for user-123 contains 500 events"
  • Code: EventStream aggregate root

  • Related Terms: Audit Event, Subject, Hash Chain, Seal

  • Tenant

  • Definition: An isolated customer or organization using ATP with dedicated data partition and policies
  • Synonyms: Customer, Organization, Account
  • Usage: "Tenant ABC Corp has 10 million Audit Events"
  • Code: Tenant aggregate, TenantId value object

  • Related Terms: Multi-Tenancy, Tenant Isolation, Tenant Policy

  • Ingestion

  • Definition: The process of receiving, validating, and storing Audit Events from external systems
  • Synonyms: Intake, Reception, Capture
  • Not: Import (implies batch), Load (too generic)
  • Usage: "Ingestion throughput is 10,000 events/sec"
  • Code: IngestionService, IngestAsync() method

  • Related Terms: Audit Event, Validation, Classification

  • Classification

  • Definition: The categorization of an Audit Event's data sensitivity level (Public, Internal, Confidential, Secret)
  • Synonyms: Data Classification, Sensitivity Level
  • Usage: "The event was classified as Confidential"
  • Code: Classification value object, ClassificationLevel enum

  • Related Terms: PII, Sensitivity, Data Classification, Compliance

  • Retention

  • Definition: The period for which an Audit Event must be stored before eligible for deletion, per legal or policy requirements
  • Synonyms: Retention Period, Data Retention
  • Usage: "Events have a 7-year retention requirement"
  • Code: RetentionPolicy entity, RetentionPeriod value object

  • Related Terms: Legal Hold, Deletion, Tombstone, Compliance

  • Subject

  • Definition: The entity (user, resource, system) that an Event Stream is about
  • Synonyms: Stream Subject, Principal (in security context)
  • Usage: "The subject of this stream is user-123"
  • Code: SubjectId value object, Subject property

  • Related Terms: Event Stream, Actor, Resource

  • Actor

  • Definition: The entity (user, service, system) that performed the action recorded in an Audit Event
  • Synonyms: Principal, Performer, Agent
  • Usage: "The actor was user-admin@example.com"
  • Code: Actor value object with UserId, ServiceId, or SystemId
  • Related Terms: Subject, Resource, Action, Authentication

For Each Core Concept: - Precise definition (2-3 sentences) - Synonyms and variations - What it's NOT (disambiguation) - Usage examples (in sentences) - Code representation (classes, properties) - Related terms (cross-references) - Common mistakes to avoid

Code Examples: - Core concept class definitions - Value object implementations - Method signatures using terms - Property naming

Diagrams: - Core concepts relationship map - Terminology hierarchy - Concept connections

Deliverables: - Core concepts glossary - Code naming guide - Concept relationship map - Usage examples

CYCLE 2: Aggregates, Entities & Value Objects Terms (~3,000 lines)

Topic 3: Aggregate and Entity Terms

What will be covered:

  • Aggregate Terms
  • AuditEvent Aggregate
  • EventStream Aggregate
  • Tenant Aggregate
  • Policy Aggregate
  • ClassificationRule Aggregate
  • RetentionPolicy Aggregate
  • ExportRequest Aggregate

  • IntegrityProof Aggregate

  • Entity Terms

  • Classification Entity
  • Retention Entity
  • Policy Rule Entity
  • Export Destination Entity
  • Legal Hold Entity

  • Snapshot Entity

  • Aggregate Lifecycle Terms

  • Create, Update, Delete (soft/hard)
  • Seal (make immutable)
  • Archive (move to cold storage)
  • Tombstone (soft delete marker)
  • Restore, Replay, Rebuild

Detailed definitions for each aggregate/entity term similar to Topic 2

Deliverables: - Aggregate glossary - Entity glossary - Lifecycle terms guide - Code examples

Topic 4: Value Object Terms

What will be covered:

  • Identity Value Objects

  • TenantId, EventId (ULID), StreamId, CorrelationId, CausationId

  • Time Value Objects

  • Timestamp, TimeRange, RetentionPeriod, ExpiresAt

  • Classification Value Objects

  • Classification, Sensitivity, DataCategory, PIIType

  • Security Value Objects

  • Hash, Signature, EncryptionKey, Certificate

  • Actor/Resource Value Objects

  • Actor, Resource, Action, Context

  • Metadata Value Objects

  • EventMetadata, StreamMetadata, TenantMetadata

Detailed definitions for each value object with immutability, equality, validation

Deliverables: - Value object glossary - Immutability patterns - Validation rules - Code examples

CYCLE 3: Events, Commands & Domain Services (~2,500 lines)

Topic 5: Event and Command Terms

What will be covered:

  • Event Naming Conventions
  • Past tense (Received, Created, Classified, Sealed)
  • Subject + Action pattern

  • Domain events vs Integration events

  • Ingestion Events

  • AuditEventReceived, BatchIngested, ValidationFailed

  • Storage Events

  • EventStreamCreated, EventStreamSealed, EventArchived

  • Classification Events

  • EventClassified, PIIDetected, EventRedacted

  • Retention Events

  • RetentionApplied, LegalHoldApplied, EventTombstoned

  • Policy Events

  • PolicyCreated, PolicyUpdated, PolicyDeleted

  • Tenant Events

  • TenantOnboarded, TenantSuspended, TenantDeleted

  • Export Events

  • ExportRequested, ExportCompleted, ExportFailed

  • Integrity Events

  • HashChainValidated, SignatureVerified

  • Command Terms

  • IngestAuditEvent, CreateEventStream, ApplyClassification
  • Commands are imperative (requests to do something)
  • Commands can be rejected
  • Commands have single handler

Detailed definitions for all events and commands

Deliverables: - Events catalog (names only, full specs in events-catalog.md) - Command glossary - Naming conventions guide - Event/command distinction guide

Topic 6: Domain Service Terms

What will be covered:

  • Core Domain Services

  • Classification Service, Retention Service, Integrity Service

  • Cross-Aggregate Operations

  • Event Ordering Service, Stream Sealing Service

  • Saga and Orchestration Terms

  • Export Saga, Tenant Onboarding Saga

  • Repository Terms

  • AuditEvent Repository, EventStream Repository

  • Factory Terms

  • AuditEvent Factory, EventStream Factory

Detailed definitions for all domain services

Deliverables: - Domain services glossary - Service patterns guide - Code examples

CYCLE 4: Bounded Contexts & Integration Terms (~2,500 lines)

Topic 7: Bounded Context Vocabulary

What will be covered:

  • Ingestion Context

  • Terms: Ingestion, Validation, Batch Processing, Rate Limiting

  • Storage Context

  • Terms: Event Store, Stream, Append-Only, Immutability

  • Classification Context

  • Terms: Auto-Classification, PII Detection, Redaction, Sensitivity

  • Query Context

  • Terms: Read Model, Projection, Index, Search, Filter

  • Policy Context

  • Terms: Policy, Rule, Compliance, Configuration

  • Export Context

  • Terms: Export, eDiscovery, Legal Hold, SIEM Integration

  • Integrity Context

  • Terms: Hash Chain, Merkle Tree, Signature, Verification

Context-specific terminology with translations between contexts

Deliverables: - Context vocabulary per bounded context - Context map with translations - Integration terminology guide

Topic 8: Integration and Cross-Context Terms

What will be covered:

  • Integration Event Terms

  • TenantOnboarded, EventExported, IntegrityVerified

  • Anti-Corruption Layer Terms

  • Translation, Adapter, Facade

  • Shared Kernel Terms

  • Common value objects, shared types

  • Published Language Terms

  • Event contracts, message schemas

  • Customer/Supplier Terms

  • Upstream, downstream, dependency relationships

Deliverables: - Integration terminology glossary - Context integration guide - Anti-corruption layer patterns

CYCLE 5: Technical & Infrastructure Terms (~2,500 lines)

Topic 9: Architecture and Design Pattern Terms

What will be covered:

  • Event Sourcing Terms

  • Event Store, Snapshot, Replay, Projection, Read Model

  • CQRS Terms

  • Command, Query, Write Model, Read Model, Eventual Consistency

  • Messaging Terms

  • Event Bus, Topic, Subscription, Queue, Dead-Letter Queue
  • Message, Envelope, Payload, Metadata

  • Publisher, Subscriber, Consumer, Handler

  • Resilience Terms

  • Idempotency, Retry, Circuit Breaker, Timeout, Backoff

  • Outbox, Inbox, Deduplication

  • Persistence Terms

  • Repository, Unit of Work, Aggregate Root, Entity, Value Object
  • Optimistic Concurrency, Pessimistic Locking

Domain-relevant technical terms with precise definitions

Deliverables: - Technical terms glossary - Pattern terminology guide - Architecture vocabulary

Topic 10: Infrastructure and Operations Terms

What will be covered:

  • Azure Infrastructure Terms
  • AKS, ACR, Service Bus, Key Vault, Storage Account

  • Kubernetes, Pod, Service, Ingress, Namespace

  • GitOps Terms

  • FluxCD, Kustomize, Helm, Manifest, Reconciliation

  • Observability Terms

  • Telemetry, Metrics, Traces, Logs, Spans

  • Correlation ID, Causation ID, Distributed Tracing

  • Deployment Terms

  • Rolling Update, Blue-Green, Canary, Rollback

  • Reliability Terms

  • SLA, SLO, SLI, Error Budget, Availability, Latency

Infrastructure terminology used in ATP context

Deliverables: - Infrastructure glossary - Operations terminology - Observability vocabulary

CYCLE 6: Compliance, Security & Operational Terms (~2,500 lines)

Topic 11: Compliance and Regulatory Terms

What will be covered:

  • GDPR Terms
  • Personal Data, Data Subject, Data Controller, Data Processor
  • Right to Access, Right to Be Forgotten, Data Portability

  • Pseudonymization, Anonymization, Consent

  • HIPAA Terms

  • Protected Health Information (PHI), Covered Entity

  • Business Associate, Breach Notification

  • SOC 2 Terms

  • Security, Availability, Processing Integrity

  • Confidentiality, Privacy, Trust Services Criteria

  • Audit and Evidence Terms

  • Audit Trail, Evidence, Tamper-Evidence, Non-Repudiation

  • Chain of Custody, Attestation, Verification

  • Data Classification Terms

  • Public, Internal, Confidential, Secret
  • PII (Personally Identifiable Information)
  • PHI (Protected Health Information)
  • Sensitive Data, Restricted Data

Precise legal and regulatory terminology

Deliverables: - Compliance glossary - Regulatory terminology guide - Legal terms with definitions

Topic 12: Security and Operational Terms

What will be covered:

  • Security Terms
  • Authentication, Authorization, Identity
  • Encryption (at-rest, in-transit), Key Management
  • Zero-Trust, Least Privilege, RBAC, ABAC

  • Threat, Vulnerability, Risk, Attack Surface

  • Multi-Tenancy Terms

  • Tenant Isolation, Resource Isolation, Data Isolation

  • Tenant Context, Tenant Boundary, Cross-Tenant Access

  • Incident Response Terms

  • Incident, Alert, Page, On-Call, Runbook
  • MTTR (Mean Time To Recovery), MTTD (Mean Time To Detect)

  • Postmortem, Root Cause Analysis (RCA)

  • Performance Terms

  • Throughput, Latency, P50, P95, P99
  • Concurrency, Parallelism, Scalability

  • Hot Path, Cold Path, Warm Storage

  • Cost Terms

  • CapEx, OpEx, TCO (Total Cost of Ownership)
  • Resource Optimization, Right-Sizing, Reserved Instances

Operational and security vocabulary

Deliverables: - Security glossary - Operational terminology - Incident response vocabulary - Performance metrics guide

Anti-Patterns and Terms to Avoid

What will be documented:

  • Ambiguous Terms
  • "Log" → Use "Audit Event" (more specific)
  • "Data" → Use specific type (Event, Stream, Tenant)

  • "Process" → Use specific action (Ingest, Classify, Export)

  • Technical Jargon in Domain Layer

  • Avoid: "Factory", "Repository", "Service" in domain model

  • Use: Domain-specific terms

  • Overloaded Terms

  • "Event" can mean Domain Event, Integration Event, Audit Event

  • Always specify which type

  • Deprecated Terms

  • Old terms that should no longer be used
  • Migration guide to new terms

Language Governance Process

What will be documented:

  • Adding New Terms
  • Proposed by domain experts or developers
  • Discussed in modeling sessions
  • Documented in glossary

  • Updated in code and docs

  • Changing Terms

  • Reason for change documented
  • Refactoring plan for code
  • Documentation update plan

  • Communication to team

  • Deprecating Terms

  • Mark as deprecated with replacement
  • Gradual migration period

  • Remove from active vocabulary

  • Validation and Enforcement

  • Code review checklist
  • Automated linters (naming conventions)
  • Documentation review
  • Regular language audits

Summary & Implementation Plan

Implementation Phases

Phase 1: Foundations (Cycle 1) - 2 weeks - Ubiquitous language fundamentals - Core domain concepts

Phase 2: Domain Model (Cycles 2-3) - 3 weeks - Aggregates, entities, value objects - Events, commands, domain services

Phase 3: Contexts (Cycle 4) - 2 weeks - Bounded context vocabulary - Integration terminology

Phase 4: Technical (Cycle 5) - 2 weeks - Architecture and design patterns - Infrastructure and operations

Phase 5: Compliance (Cycle 6) - 2 weeks - Regulatory and compliance terms - Security and operational vocabulary

Success Metrics

  • Glossary Completeness: 200+ terms documented
  • Code Consistency: 100% of domain classes use ubiquitous language
  • Documentation Coverage: All docs use consistent terminology
  • Team Understanding: 100% of team trained on ubiquitous language
  • Validation: Automated checks for naming conventions

Ownership & Maintenance

  • Domain Experts: Define and validate all business terms
  • Architects: Ensure cross-context consistency
  • Developers: Apply in code, propose refinements
  • Technical Writers: Use in all documentation
  • Product Managers: Use in requirements and stories

Document Status: ✅ Plan Approved - Ready for Content Generation

Target Start Date: Q2 2025

Expected Completion: Q3 2025 (3 months)

Owner: Domain Modeling Team

Last Updated: 2024-10-30