Module document Architecture

Navigation: Home > Modules

Architecture - Document Module

Overview

The document module composes store, lifecycle, schema, merge, exchange, and snapshot-editing surfaces into a coherent document runtime contract. It centralizes document management behavior while exposing explicit validation and conflict semantics.

Main Execution Planes

1. Store and manager plane

• document CRUD and manager-level orchestration contracts
• collection/id-scoped document persistence semantics

2. Lifecycle and schema plane

• lifecycle callback sequencing around create/update/delete operations
• schema registration, sealing, and validation behavior

3. Diff/merge and exchange plane

• document diff and merge resolution strategies
• XDOMEA import/export and repository exchange flows

4. Round-trip persistence plane

• relay-scoped snapshot write/load/count workflows
• deterministic snapshot ID generation and lookup semantics

Core Contracts

Contract	Behavior
store/manager contract	explicit Result-based document operation behavior
lifecycle/schema contract	deterministic hook/validation semantics
diff/merge contract	bounded conflict-aware merge behavior
exchange/snapshot contract	explicit XDOMEA and round-trip persistence flows

Failure Semantics

• invalid schema or merge conflict paths return structured Result errors.
• not-found document paths return explicit absent/error states.
• invalid round-trip persistence operations fail with explicit store error propagation.

Sourcecode Verification (Module: document/architecture)

• Verified files:
  • include/document/document_store.h
  • include/document/document_manager.h
  • include/document/document_lifecycle.h
  • include/document/document_schema_evolution.h
  • include/document/document_diff_merge.h
  • include/document/xdomea_connector.h
  • src/document/round_trip_editor.cpp
• Verified architecture claims:
  • explicit store/lifecycle/schema and diff/merge planes
  • bounded Result-based failure semantics for document operations
  • module-local ownership of round-trip document snapshot persistence

Module Dependencies

Direct Upstream Dependencies (this module uses)

Module	Interface / File	Purpose
storage	include/storage/	Persists document objects and snapshot state
metadata	include/metadata/	Schema evolution and versioning checks for document schemas
utils	include/utils/	Logging, audit, and serialisation helpers

Direct Downstream Consumers (modules that use this module)

Module	Via	Notes
server	include/document/	Server exposes document store, lifecycle, and schema APIs

Integration Points

Critical Integration: Storage Document Persistence

Files: src/document/round_trip_editor.cpp, include/document/document_store.h ↔ storage/ Contract: Document store delegates all persistence to storage interfaces; round-trip snapshot IDs are generated deterministically and must be stable within a session. Thread Safety: Document CRUD operations use Result-based error propagation; concurrent access to the same document ID is serialised by the storage layer.

Critical Integration: Metadata Schema Evolution

Files: include/document/document_schema_evolution.h ↔ metadata/ Contract: Schema evolution checks query metadata for registered schema versions before allowing structural mutations; schema seal is enforced by metadata module. Thread Safety: Schema reads are concurrent-safe; schema mutations require the metadata write lock.

---

ThemisDB 1.9.0-beta · Home · Module-Index · GitHub · Issues