Glossary

This document provides standardized definitions for terminology used throughout the ReX (RemedyX) project documentation and codebase. Using consistent terminology enhances communication clarity and maintains conceptual integrity across all components.

Core Concepts

Content System

• Content: The fundamental unit of data in the system, represented by a standardized interface combining data, contentType, and metadata.
• URI: The unique identifier used to address content within the system (not “path” or “id”). Used consistently for all content addressing.
• Content Store: The high-level API facade that provides content operations and abstracts underlying storage mechanisms.
• Content Registry: Central registry that manages content store instances and their relationships.
• Content Adapter: Implementation abstraction that connects to specific storage backends.

Content Structure

• Content Data: The actual content payload (text, binary, or structured data).
• Content Type: MIME-type identifier for the content format (e.g., text/markdown).
• Metadata: Structured data about content, including title, description, timestamps, and custom attributes.
• Frontmatter: Metadata embedded within content files (typically YAML between triple-dashes in Markdown).

Architecture

• Layer: Distinct responsibility boundary in the system architecture:

  • Integration Layer: React hooks, components, API surface
  • Content Facade Layer: ContentStore, Registry interfaces
  • Enhancement Layer: Middleware, composition functions
  • Storage Adapter Layer: Environment-specific storage implementations
  • Foundation Layer: Types, errors, utilities

• Composition: The architectural pattern of building complex behavior through function composition rather than inheritance.

• Plugin: Extension module that provides additional functionality to the system through standardized interfaces.

URI System

• URI Format: The structure used for content addressing: scheme:[//authority]/path[?query][#fragment]
• URI Scheme: Identifier specifying the URI type (e.g., content:, file:, memory:, http:)
• Path Component: The hierarchical portion of a URI that identifies the resource location
• Query Component: Optional parameters passed in a URI using ?key=value
• Fragment Component: Optional portion of a URI after the # character
• ContentURI: Utility for parsing, formatting, and validating content URIs

Operations

• Read: Operation to retrieve content by URI.
• Write: Operation to create or update content at a specific URI.
• Delete: Operation to remove content from the store.
• List: Operation to retrieve URIs matching a pattern.
• Exists: Operation to check if content exists at a specific URI.
• Observe: Register a callback to be notified of content changes (preferred over “onChange”).

Events

• Event Type: Identifier for what occurred (e.g., “created”, “updated”, “deleted”, “moved”).
• Observer: Function that receives notifications about events (preferred over “listener” or “handler”).
• Unsubscribe: Function returned from observe() that removes the observer when called.
• Change Type: Enumeration specifying the type of content change (CREATED, UPDATED, DELETED, MOVED).
• ContentChangeObserver: Function type for content observation callbacks.
• ContentObserver: Alias for ContentChangeObserver (preferred term is ContentChangeObserver).
• ObserveOptions: Configuration options for content observation.

Middleware

• Middleware: Function that enhances operations by executing logic before/after the core operation.
• Middleware Chain: Sequence of middleware functions composed together.
• Middleware Context: Data shared between middleware functions in a chain.
• Pipe: Function that composes multiple middleware functions or enhanced stores.
• Middleware Factory: Function that creates configured middleware (e.g., withValidation).
• Next: The function passed to middleware for continuation of the operation chain.
• Enhancement: The result of applying middleware (enhanced function).

Environment

• Environment: Runtime context where the code executes (Node.js, browser, service worker).
• Isomorphic: Code that can run in multiple environments without modification.
• Capability Detection: Runtime checking for environment-specific features.

Event Ordering

• Lifecycle Hooks: Functions that intercept operations at specific points (beforeOperation, afterOperation, onError).
• System Events: Notifications about internal state changes (ready, error, connecting, connected, disconnected).
• Event Order Guarantees: Defined sequence for event and hook execution.

Technical Terms

Type System

• Content<T>: Generic interface for content where T represents the data type.
• ContentMetadata: Interface for standardized and custom metadata fields.
• ContentOptions: Configuration options for content operations.
• ContentReadOptions: Options specific to read operations.
• ContentWriteOptions: Options specific to write operations.
• ContentDeleteOptions: Options specific to delete operations.
• ContentListOptions: Options specific to list operations.
• ContentExistsOptions: Options specific to exists operations.
• AdapterOptions: Configuration options for adapter initialization.

Function Patterns

• Factory Function: Function that creates and returns instances (e.g., createContentStore()).
• Higher-Order Function: Function that returns an enhanced function (e.g., withValidation()).
• Pure Function: Function with no side effects that returns the same output for the same input.

Error Handling

• ContentError: Base error class for all content-related errors.
• ContentNotFoundError: Error indicating requested content doesn’t exist.
• ContentAccessError: Error indicating permission issues accessing content.
• ContentFormatError: Error indicating invalid content format or structure.
• ContentValidationError: Error indicating content failed validation rules.
• ContentErrorRecoveryOptions: Options for recovering from content errors.

Temporal Fields

• createdAt: Timestamp indicating when content was first created.
• updatedAt: Timestamp indicating when content was last modified (preferred over “modifiedAt”).
• accessedAt: Timestamp indicating when content was last accessed.
• publishedAt: Timestamp indicating when content was made publicly available.
• scheduledAt: Timestamp indicating when content is scheduled to be published.
• expiresAt: Timestamp indicating when content expires.
• deletedAt: Timestamp indicating when content was soft-deleted.

Implementation-Specific Terms

Storage Adapters

• FileSystemAdapter: Adapter for Node.js filesystem operations.
• MemoryAdapter: Adapter for in-memory content storage.
• IndexedDBAdapter: Adapter for browser persistent storage.
• HttpAdapter: Adapter for remote content via fetch API.
• ServiceWorkerAdapter: Adapter for offline-capable storage.
• LocalStorageAdapter: Adapter for browser localStorage API.

Content Types

• MARKDOWN: MIME type for Markdown content (text/markdown).
• MDX: MIME type for MDX content (text/mdx).
• HTML: MIME type for HTML content (text/html).
• TEXT: MIME type for plain text content (text/plain).
• JSON: MIME type for JSON data (application/json).
• Binary Content: Non-text content represented by application/octet-stream or specific MIME types.

React Integration

• ContentProvider: React context provider for content store access.
• useContent: React hook for reading content with automatic updates.
• useContentWrite: React hook for writing content to the store.

MDX Processing

• MDX Compilation: Process of converting MDX content to executable React components.
• Component Mapping: Association between MDX component names and React components.
• Frontmatter Extraction: Process of separating metadata from MDX content.

File Organization

• Project Structure: The organization of files into modules and directories.
• Module Resolution: The system for resolving import paths to actual files.
• Path Alias: Short identifier that maps to a specific directory (e.g., @lib).

Testing Concepts

• Unit Test: Test for individual functions or components in isolation.
• Integration Test: Test for interactions between multiple components.
• Mock: Simulated implementation used for testing.
• Test Fixture: Predefined data used consistently across tests.

Development Lifecycle

• Development Environment: Local setup for active development.
• Build Process: Compilation and bundling of source code for production.
• Type Checking: Static analysis to ensure type safety.
• Linting: Static analysis to ensure code style and quality.