Skip to Content
📚 MyStoryFlow Docs — Your guide to preserving family stories
Use Cases & TestingReference Data System Flow

Reference Data System Flow - Business Rules & Test Cases

Flow Overview

The Reference Data System provides centralized management of all dropdown options, status values, and multi-option data across MyStoryFlow applications. This system ensures consistency, maintainability, and scalability for reference data management.

Flow Types

  • API-based: All reference data served via REST API endpoints
  • Cached: Client-side caching with configurable TTL
  • Versioned: All collections include version control and timestamps
  • Validated: Strict validation of collection structure and content

Core Principles

  • Single Source of Truth: All reference data centralized in JSON collections
  • Type Safety: Full TypeScript integration with generated types
  • Performance Optimized: Efficient caching and minimal API calls
  • Developer Friendly: React hooks for easy consumption

Step-by-Step Business Rules

Step 1: Collection Definition & Storage

BR-RDS-001: Collection Structure Requirements

  • Rule: All reference collections MUST follow standardized JSON structure
  • Implementation: Validated against ReferenceCollection type with required fields
  • Test: Unit tests verify validateCollection() function accepts valid structure
  • Rationale: Ensures consistency and enables automated processing
{
  "version": "1.0.0",
  "lastUpdated": "2025-01-21T00:00:00.000Z",
  "items": [
    {
      "code": "unique-code",
      "label": "Display Label", 
      "description": "Optional description",
      "category": "grouping-category",
      "sortOrder": 1,
      "isActive": true,
      "metadata": {}
    }
  ]
}

BR-RDS-002: Collection Naming Standards

  • Rule: Collection names MUST use kebab-case and be descriptive
  • Implementation: Enforced in API route validation and file naming
  • Test: Integration tests verify API rejects invalid collection names
  • Rationale: Prevents naming conflicts and enables predictable URL patterns

BR-RDS-003: Code Uniqueness Within Collections

  • Rule: Item codes MUST be unique within each collection
  • Implementation: Integration tests verify no duplicate codes
  • Test: Collection validation fails if duplicate codes found
  • Rationale: Ensures reliable item lookup and prevents data conflicts

BR-RDS-004: Active Item Requirement

  • Rule: Each collection MUST have at least one active item (isActive: true)
  • Implementation: Integration tests verify activeItems.length >= 1
  • Test: Collection validation fails if no active items present
  • Rationale: Ensures dropdowns always have selectable options

Step 2: API Service Layer

BR-RDS-005: API Endpoint Security

  • Rule: API MUST validate collection names against whitelist
  • Implementation: VALID_COLLECTIONS array in route handler
  • Test: API returns 400 for invalid collection names
  • Rationale: Prevents directory traversal and unauthorized file access

BR-RDS-006: Error Handling Standards

  • Rule: API MUST return structured error responses with appropriate HTTP codes
  • Implementation: Consistent error format: { error: string }
  • Test: Unit tests verify correct status codes (400, 404, 500)
  • Rationale: Enables proper client-side error handling

BR-RDS-007: Performance Caching

  • Rule: API responses MUST include cache headers for optimization
  • Implementation: Cache-Control: public, max-age=3600, stale-while-revalidate=86400
  • Test: Integration tests verify cache headers present
  • Rationale: Reduces server load and improves client performance

BR-RDS-008: Collection Metadata Headers

  • Rule: API responses MUST include collection metadata in headers
  • Implementation: X-Collection-Version and X-Collection-Items headers
  • Test: Integration tests verify metadata headers present
  • Rationale: Enables client-side cache validation and debugging

Step 3: Client-Side Integration

BR-RDS-009: React Hook Standards

  • Rule: All reference data access MUST use provided React hooks
  • Implementation: useReferenceData, useBookTypes, etc.
  • Test: Component tests verify hooks return correct data structure
  • Rationale: Ensures consistent data access patterns and caching

BR-RDS-010: Loading State Management

  • Rule: UI MUST handle loading states gracefully
  • Implementation: Hooks return loading boolean, UI shows loading indicators
  • Test: E2E tests verify loading states displayed correctly
  • Rationale: Provides good user experience during data fetching

BR-RDS-011: Error Recovery

  • Rule: UI MUST handle API failures gracefully without breaking
  • Implementation: Error states handled in hooks, fallback UI provided
  • Test: E2E tests verify error scenarios don’t break functionality
  • Rationale: Maintains application stability in failure scenarios

BR-RDS-012: Item Selection Validation

  • Rule: Only active items (isActive: true) MUST be selectable in UI
  • Implementation: toSelectOptions() marks inactive items as disabled
  • Test: Component tests verify inactive items are disabled
  • Rationale: Prevents selection of deprecated or invalid options

Step 4: Data Consistency & Validation

BR-RDS-013: Sort Order Enforcement

  • Rule: Items MUST be sorted by sortOrder first, then by label
  • Implementation: sortItems() utility function in hooks
  • Test: Unit tests verify correct sorting behavior
  • Rationale: Ensures predictable and user-friendly option ordering

BR-RDS-014: Category Grouping

  • Rule: Items with categories MUST be properly grouped for display
  • Implementation: groupByCategory() utility function available
  • Test: Unit tests verify correct grouping behavior
  • Rationale: Enables organized display of large option sets

BR-RDS-015: Search Functionality

  • Rule: Search MUST work across code, label, and description fields
  • Implementation: searchItems() utility with case-insensitive matching
  • Test: Unit tests verify search finds items in all fields
  • Rationale: Provides comprehensive search capability for large collections

BR-RDS-016: Version Consistency

  • Rule: All collections MUST use consistent versioning scheme
  • Implementation: Integration tests verify version format (semver)
  • Test: All collections use “1.0.0” format in initial release
  • Rationale: Enables version-aware caching and compatibility checking

Critical Collection Requirements

Book Types Collection (book-types.json)

BR-RDS-017: Required Book Type Coverage

  • Rule: MUST include standard memoir, autobiography, family-history, cookbook types
  • Implementation: Integration tests verify required types present
  • Test: Collection contains memoir, autobiography, family-history, cookbook codes
  • Rationale: Supports core book creation workflows

BR-RDS-018: Book Type Metadata Standards

  • Rule: Book types MUST include targetAudience and averagePageCount metadata
  • Implementation: BookType interface extends ReferenceItem with typed metadata
  • Test: Integration tests verify metadata fields present for book types
  • Rationale: Enables template filtering and user guidance

User Roles Collection (user-roles.json)

BR-RDS-019: Role Hierarchy Requirements

  • Rule: MUST include user, admin, family_member roles at minimum
  • Implementation: Integration tests verify required roles present
  • Test: Collection contains user, admin, family_member codes
  • Rationale: Supports authentication and authorization systems

BR-RDS-020: Permission Metadata Standards

  • Rule: User roles MUST include permissions and features arrays in metadata
  • Implementation: UserRole interface with typed metadata
  • Test: Unit tests verify permission metadata structure
  • Rationale: Enables role-based access control

Status Collections (various)

BR-RDS-021: Status Transition Rules

  • Rule: Status items MUST include allowedTransitions in metadata
  • Implementation: Status interface with transition metadata
  • Test: Integration tests verify transition metadata for status collections
  • Rationale: Enables state machine validation and UI flow control

BR-RDS-022: Terminal Status Identification

  • Rule: Status items MUST indicate if they are terminal states
  • Implementation: isTerminal boolean in metadata
  • Test: Unit tests verify terminal status identification
  • Rationale: Prevents invalid state transitions in workflows

Performance & Scalability Rules

BR-RDS-023: Collection Size Limits

  • Rule: Individual collections SHOULD NOT exceed 50KB file size
  • Implementation: Integration tests warn for large collections
  • Test: Performance tests verify load time < 1 second for all collections
  • Rationale: Maintains fast API response times

BR-RDS-024: Concurrent Access Safety

  • Rule: API MUST handle concurrent requests safely
  • Implementation: Stateless API design, file system read-only access
  • Test: Integration tests verify concurrent request handling
  • Rationale: Prevents data corruption and ensures reliability

BR-RDS-025: Client-Side Caching Strategy

  • Rule: Clients MUST implement caching to minimize API calls
  • Implementation: React hooks use singleton pattern for collection storage
  • Test: E2E tests verify API calls minimized through caching
  • Rationale: Reduces server load and improves user experience

Security Requirements

BR-RDS-026: Path Traversal Prevention

  • Rule: API MUST prevent directory traversal attacks
  • Implementation: Strict whitelist validation of collection names
  • Test: Security tests verify malicious paths rejected
  • Rationale: Prevents unauthorized file system access

BR-RDS-027: Input Sanitization

  • Rule: Collection names MUST be sanitized and validated
  • Implementation: Regex validation for kebab-case names only
  • Test: API tests verify special characters rejected
  • Rationale: Prevents injection attacks and system compromise

Testing Requirements

Test Case Categories

Critical Path Testing

  • TC-RDS-001: Verify API returns valid JSON for all 53 collections
  • TC-RDS-002: Verify React hooks load data and provide helper functions
  • TC-RDS-003: Verify UI components display reference data correctly
  • TC-RDS-004: Verify form submissions use reference data values

Integration Testing

  • TC-RDS-005: Verify API error handling for various failure scenarios
  • TC-RDS-006: Verify client-side error recovery and fallback behavior
  • TC-RDS-007: Verify caching behavior across page navigation
  • TC-RDS-008: Verify collection validation catches data quality issues

Error Scenarios

  • TC-RDS-009: API returns 500 - verify graceful degradation
  • TC-RDS-010: Network timeout - verify retry behavior
  • TC-RDS-011: Invalid JSON response - verify error handling
  • TC-RDS-012: Empty collection - verify fallback options

Edge Cases

  • TC-RDS-013: Large collection (100+ items) - verify performance
  • TC-RDS-014: Collection with all inactive items - verify behavior
  • TC-RDS-015: Malformed collection structure - verify validation
  • TC-RDS-016: Concurrent API requests - verify data consistency

Maintenance & Operations

BR-RDS-028: Collection Updates

  • Rule: Collection updates MUST increment version and update timestamp
  • Implementation: Manual process with version validation
  • Test: Integration tests verify version consistency
  • Rationale: Enables cache invalidation and change tracking

BR-RDS-029: Backward Compatibility

  • Rule: Collection updates MUST maintain backward compatibility
  • Implementation: Additive changes only, deprecation process for removals
  • Test: API tests verify existing codes remain functional
  • Rationale: Prevents breaking existing implementations

BR-RDS-030: Monitoring Requirements

  • Rule: API performance and error rates MUST be monitored
  • Implementation: Logging and metrics collection in production
  • Test: Performance tests establish baseline metrics
  • Rationale: Enables proactive identification of issues

This reference data system ensures consistent, maintainable, and scalable management of all application reference data while providing excellent developer experience and system reliability.

Timeline System FlowTools App Overview