One of the biggest challenges in maintaining a large codebase is not writing
functions—it is understanding how everything fits together.
During the Knowledge Presentation Architecture migration, the project evolved
from a collection of loosely connected templates into a layered presentation
system with clearly defined responsibilities.
This article serves as the architectural map for that system.
The Overall Pipeline
Portal
│
▼
knowledge/data.php
│
▼
kp_collect_knowledge()
│
Knowledge Collector
│
▼
Build taxonomy relationships
│
▼
Execute WP_Query
│
▼
kp_build_card() for every post
│
▼
Normalized Card Objects
│
▼
kp_build_knowledge()
│
▼
Normalized Knowledge Structure
│
▼
kp_render_knowledge_sections()
│
▼
Presentation Templates
│
▼
Final HTML Output
Each layer performs exactly one responsibility before handing control to the
next layer.
Directory Structure
inc/ ├── collectors/ │ knowledge-collector.php │ ├── presentation/ │ │ knowledge-builder.php │ knowledge-renderer.php │ knowledge-sections.php │ card/ │ │ artist.php │ book.php │ concept.php │ element.php │ excerpt.php │ fragment.php │ game.php │ image.php │ lyric.php │ movie.php │ profile.php │ quote.php │ show.php │ song.php │ template-parts/ │ ├── search/ │ ├── grids/ │ ├── lists/ │ └── views/
Notice that collectors, builders, renderers and templates now occupy distinct
layers rather than sharing responsibilities.
The Knowledge Collector
Portal │ ├── Read attached taxonomy │ ├── Build tax_query │ ├── Query matching content │ ├── Organize by CPT │ └── Produce normalized sections
The collector never generates HTML.
It simply produces structured data.
The Card Builder Layer
Post │ ├── Title ├── URL ├── Image ├── Icon ├── Excerpt ├── Metadata │ ▼ Normalized Card
Every content type is translated into the same public interface regardless of
its internal ACF fields.
This abstraction allows presentation templates to become generic.
The Knowledge Builder
Cards │ ├── grouped by CPT │ ├── labels │ ├── ordering │ ├── metadata │ ▼ Knowledge Object
The builder packages all collected information into a single object that can be
rendered anywhere.
The Renderer
Knowledge Object
│
▼
Renderer
│
▼
Loop Sections
│
▼
Locate Template
│
▼
Render HTML
The renderer has no knowledge of portals, taxonomy archives or search pages.
Its only job is to render the data it receives.
Template Responsibilities
Template Receives ↓ items[] ↓ Loop Cards ↓ Output HTML
Templates should never perform business logic.
Their responsibility is presentation only.
The Legacy Compatibility Layer
Old Caller ↓ WP_Query ↓ Convert Query ↓ Normalized Cards ↓ Shared Template ↓ HTML
This compatibility bridge allowed the migration to proceed incrementally while
keeping older pages operational.
Responsibility Matrix
| Layer | Responsibility |
|---|---|
| Collector | Gather data |
| Card Builder | Normalize individual objects |
| Knowledge Builder | Create complete knowledge structure |
| Renderer | Select presentation templates |
| Template | Generate HTML |
Why This Architecture Matters
The migration deliberately separates concerns into independent layers.
- Collectors understand WordPress.
- Card builders understand content types.
- Knowledge builders understand presentation structure.
- Renderers understand template selection.
- Templates understand HTML.
Because each layer has one responsibility, future changes become localized.
Adding a new CPT requires only a card builder and metadata registration.
Changing the HTML affects templates only.
Introducing a new presentation surface requires a renderer rather than changes
to every content type.
Conclusion
The greatest achievement of this unification project was not simply migrating
templates—it was introducing a layered architecture where every component has a
clear responsibility.
This diagram should serve as the reference map for understanding how the
Knowledge Presentation Architecture operates as a complete system.