One of the most significant architectural decisions made during the Knowledge Presentation migration was introducing a dedicated Knowledge Collector layer. Although the implementation began as a refactoring of Portal pages, it quickly became clear that the underlying problem extended far beyond portals themselves.
The original architecture tightly coupled three separate responsibilities:
- Discovering relevant content.
- Organizing that content into logical sections.
- Rendering HTML for the user.
Because these responsibilities lived together, every new presentation layer required rebuilding the same logic. Search, taxonomy archives, portals, and future pages all had to answer essentially the same questions independently:
- Which content belongs here?
- How should it be grouped?
- Which post types should be included?
- What order should sections appear?
- What metadata accompanies each section?
The Knowledge Collector exists to answer those questions exactly once.
The Core Idea
A Knowledge Collector has one responsibility:
Collect knowledge and return a normalized data structure.
It does not generate HTML.
It does not choose templates.
It does not know whether the data will eventually appear inside a Portal, Search Results page, Taxonomy Archive, API response, or any future interface.
Its only job is to gather information.
User Request
│
▼
Knowledge Collector
│
▼
Normalized Knowledge Object
Responsibilities
The collector became responsible for tasks such as:
- Determining which taxonomies apply.
- Building the WP_Query.
- Selecting participating post types.
- Grouping results by content type.
- Building normalized cards.
- Attaching presentation metadata.
- Returning a consistent knowledge structure.
Notice that rendering is intentionally absent from this list.
Architecture
Portal
Search
Taxonomy Archive
Future Systems
│
▼
kp_collect_knowledge()
│
▼
WP_Query
│
▼
Group Results
│
▼
kp_build_card()
│
▼
kp_build_knowledge()
│
▼
Knowledge Object
At this point the collector’s work is finished.
Collector vs Renderer
| Collector | Renderer |
|---|---|
| Queries WordPress | Outputs HTML |
| Groups content | Selects templates |
| Creates normalized cards | Loops over sections |
| Returns structured data | Displays structured data |
| Contains business logic | Contains presentation logic |
Separating these responsibilities dramatically reduced coupling across the project.
The Collector Output
Rather than returning raw WordPress queries, the collector produces a complete knowledge object.
[
'sections' => [...],
'active_sections' => [...],
'section_order' => [...],
'section_labels' => [...],
'metadata' => [...],
'context' => [...],
]
Every presentation layer consumes the same structure regardless of where the data originated.
Why Normalize Cards?
Each content type stores information differently.
Books use one set of custom fields.
Songs use another.
Artists use portraits.
Games use cover images.
Quotes often have no image at all.
Without normalization, every template would need to understand every content type.
Instead, each post is converted into a standard card before it reaches the presentation layer.
Book
Song
Movie
Game
Artist
Quote
Element
Fragment
│
▼
kp_build_card()
│
▼
Normalized Card
Once normalized, templates no longer care what content type produced the card.
Benefits
- One source of truth for knowledge collection.
- Presentation layers become reusable.
- Business logic is centralized.
- Adding new post types requires minimal changes.
- Search, Portals, and Taxonomy Archives share the same pipeline.
- Future APIs can reuse the exact same collector.
A Foundation for Future Features
Although the collector was introduced during the Portal migration, it was intentionally designed to outlive that implementation.
Any future system capable of presenting knowledge can consume the same normalized object without knowing how the underlying queries were constructed.
This makes the collector a foundational architectural layer rather than a Portal-specific utility.
Key Design Principle
Collect knowledge once. Present it anywhere.
That single principle drove much of the subsequent architecture, including the Knowledge Builder, the Presentation Engine, bilingual templates, and the standardized card system. By separating collection from presentation, the project shifted away from page-specific implementations toward a reusable knowledge platform capable of supporting multiple presentation layers with a shared foundation.