Skip to content

Collector Architecture Phase 1: Establishing the Reference Context System

Published on June 30, 2026

This week marked the beginning of a major architectural refactor of the Knowledge Platform’s Reference subsystem. Rather than allowing individual footnote modules and reverse lookup functions to query ACF relationship fields independently, the project introduced a dedicated collector architecture that separates data collection from presentation.

The overall goal is to establish a consistent pattern throughout the platform:

Collectors
    ↓
Context Arrays
    ↓
Renderers
    ↓
Templates

With this foundation in place, renderers no longer need to understand where data originates. Instead, they simply consume a fully assembled context generated by the appropriate collector. This significantly reduces duplicated querying logic while creating a reusable architecture for future inheritance, relationship, and attribution systems.

Reference Context Collector

The first collector, kp_build_reference_context(), was moved into its own dedicated file inside the new inc/collectors/ directory.

The collector now performs several responsibilities:

  • Collects directly attached Chapter and Fragment relationship fields.
  • Expands attached Elements automatically.
  • Traverses each Element’s related_content field.
  • Prevents recursion into Chapters, Fragments, and Elements.
  • Deduplicates related CPTs automatically using post IDs.
  • Returns grouped context arrays keyed by CPT.

Instead of every renderer querying ACF directly, renderers now receive a completed context and simply display the relevant content.

Shared Relationship Expansion

While expanding the collector, duplicated traversal logic became apparent. A new helper function, kp_add_related_items_to_context(), was introduced to centralize the logic responsible for adding related CPTs into a context.

This helper now:

  • Filters out narrative containers.
  • Automatically deduplicates entries.
  • Provides a single location for future traversal changes.

Moving this logic into a shared helper reduces maintenance overhead while ensuring every traversal path behaves consistently.

Element Compatibility

One important architectural improvement was recognizing that Elements store relationships differently from Chapters and Fragments.

Rather than maintaining separate traversal logic throughout the project, the collector now detects Element posts and builds context directly from the Element’s related_content field before returning the completed context.

This allows the same collector to be reused regardless of whether the starting object is a Chapter, Fragment, or Element.

Featured In Integration

The reverse lookup system used by the “Featured In” sections across CPT pages was also migrated to the collector architecture.

A new collector, kp_build_featured_context(), was introduced to centralize reverse relationship discovery.

This collector searches:

  • Chapter relationship fields.
  • Fragment relationship fields.
  • Element related_content relationships.

Existing Featured In renderers now consume the collector instead of performing relationship queries internally.

This migration successfully restored inherited relationships after duplicate CPT relationships were removed from Chapters, proving that reverse lookups now correctly recognize inherited Element relationships.

Orphan Finder Improvements

The orphan detection tool was also updated to consume the new reference collector rather than manually inspecting every relationship field.

During testing several issues were identified and corrected:

  • The collector was updated to recognize the correct books_cited field.
  • Element relationships are now recognized when determining referenced content.
  • Several previously reported orphaned items were correctly removed from the orphan list.

The orphan count dropped significantly after these corrections, confirming that inherited Element relationships are now treated as valid references throughout the site.

Documentation Improvements

Alongside implementation work, a new documentation workflow was explored.

The experiment treats development conversations themselves as the source for project documentation rather than requiring documentation to be written separately after coding is complete.

Each implementation session can now naturally generate:

  • Git commit messages.
  • Engineering Notes.
  • Architecture documentation.
  • Weekly development updates.
  • Learning PHP explanations.
  • Future engineering tasks.

This reinforces the goal of making documentation a natural byproduct of development instead of a separate maintenance task.

Architectural Outcome

Phase 1 successfully established the collector pattern as a reusable architectural foundation for the Knowledge Platform.

The completed work demonstrates that relationship traversal can be centralized inside collectors, allowing renderers to focus solely on presentation while remaining completely unaware of where the underlying data originated.

This architecture now provides a solid foundation for future collectors, including Source Context, Related Context, inheritance systems, attribution frameworks, and additional relationship-based subsystems throughout the platform.