Purpose
This page explains how Civic Topology is currently implemented in WordPress.
Civic Topology is conceptually a network of conditions, relationships, and guided traversals. WordPress is not a graph database or a purpose-built causal mapping system, so the current implementation is a practical publishing layer rather than a perfect structural match.
That is acceptable at this stage.
The goal is not to simulate a full graph engine inside WordPress. The goal is to make Civic Topology legible, navigable, and maintainable using the tools already in use on the site.
Current Implementation Model
Civic Topology is currently implemented using standard WordPress pages and hardcoded internal links.
The main content types are represented as pages:
- Issue pages represent civic conditions or states.
- Causal-link pages represent directional or feedback relationships between conditions.
- Walkthrough pages represent guided traversals through part of the network.
- Articles may link into the network as extended explanations and may also help generate new issue pages, causal-link pages, or walkthroughs, but are not themselves part of the atomic CivTop structure.
The links between pages are manually maintained.
This is intentional. At the current scale, hardcoded links provide enough navigability without adding the maintenance burden or conceptual overhead of more elaborate WordPress structures.
Why This Approach Is Good Enough for Now
The current CivTop network is still small enough that manual linking is practical.
Using standard pages with explicit internal links has several advantages:
- it keeps the structure visible and understandable
- it avoids unnecessary WordPress complexity
- it preserves editorial control over what is linked and how
- it keeps the implementation aligned with the text-first nature of the project
Civic Topology is meant to be read and traversed by humans. It does not currently need a more automated or systematized publishing structure to do useful work.
Conceptual Structure vs. Publishing Structure
The conceptual model of Civic Topology is closer to a knowledge graph:
- issue pages function like nodes
- causal-link pages function like typed edges
- walkthrough pages function like named paths
- articles function as explanatory and generative layers around the graph
WordPress is simply the current rendering layer for that model.
This distinction matters. The implementation should not be mistaken for the conceptual architecture. WordPress pages and links are the current way the system is published, not the final or only possible representation of the underlying structure.
Page Types in Practice
Issue Pages
Issue pages define a condition in the system.
They answer questions such as:
- What is this condition?
- How does it manifest?
- Why does it matter?
- What does it commonly lead to?
- What commonly contributes to it?
Issue pages should remain focused on the condition itself. They may briefly summarize major contributing causes or downstream effects, but deeper mechanism belongs on causal-link pages.
Causal-Link Pages
Causal-link pages explain why one condition tends to produce, intensify, or sustain another.
They are the mechanism layer of Civic Topology.
These pages should clarify:
- why the relationship exists
- under what conditions it holds
- what kind of relationship it is
- how strong, direct, delayed, or conditional it tends to be
- what examples or evidence support it
Causal-link pages carry most of the explanatory work in the network.
Walkthrough Pages
Walkthrough pages are reader-facing guided traversals through part of the network.
They are not the same thing as the network itself.
A walkthrough selects a path through the topology in order to answer a specific question or show a specific mechanism clearly. As the network grows denser, walkthroughs become more important because they let readers follow a meaningful route without needing to absorb the whole map at once.
Articles
Articles are related to Civic Topology, but they operate differently.
An article may:
- explain a structural problem in plain language
- synthesize several CivTop paths into a broader argument
- discover new conditions or relationships during exploration
- later link back into issue pages, causal-link pages, or walkthrough pages
In that sense, articles are not just explanatory. They are also one of the ways new CivTop structure gets discovered.
Linking Strategy
Links are currently added manually.
This is acceptable because:
- the current number of pages is manageable
- not every possible connection needs to be shown on every page
- selective linking improves clarity
- manual linking allows the strongest and most relevant relationships to be emphasized
The aim is not maximum link density. The aim is meaningful navigability.
In practice:
- issue pages should link to major contributing causes, major downstream effects, and closely related issues
- causal-link pages should link back to both endpoint issue pages and, where useful, to adjacent or reinforcing relationships
- walkthrough pages should link all major pages used in the traversal
- articles may link into the network where doing so adds structural clarity
Naming and URL Discipline
At the WordPress level, page titles and slugs should remain clear, descriptive, and stable.
For fuller guidance on condition naming, see the Civic Topology Issue Writing Guidelines.
This does not require rigid uniformity across every issue name. It does require enough consistency that pages remain understandable and maintainable.
In practice:
- issue pages should use clear condition-state phrasing
- causal-link pages should use the formal X causes Y page-title pattern
- shorthand arrow notation may be used in notes, chain planning, or walkthrough drafting, but is not the formal title format
- existing page names do not need to be retroactively normalized unless there is a strong reason to do so
The goal is clarity first, not artificial naming perfection.
Known Limitations
This implementation has obvious limits.
WordPress does not natively provide:
- graph-native visualization
- typed relationship querying
- automatic path discovery
- node centrality analysis
- cluster detection
- dynamic map rendering
Manual linking also means:
- consistency depends on editorial discipline
- network growth may eventually make flat lists harder to navigate
- hubs may require tighter maintenance over time
- structure must be managed intentionally rather than inferred automatically
These are acceptable limitations at the current scale.
Forward Compatibility
Nothing in the current implementation prevents later migration to a richer representation.
Because Civic Topology is being built around clear issue pages, explicit causal-link pages, and named walkthroughs, the structure is already compatible with more graph-native tools if they are ever needed.
For now, WordPress is sufficient.
The priority is to develop the topology itself, not to over-engineer the platform that renders it.
Editorial Principle
Civic Topology should be implemented in a way that supports clarity, not technical purity.
The current WordPress model is deliberately simple:
- define conditions clearly
- define relationships clearly
- link them directly
- create walkthroughs where needed
- let the network grow in readable, maintainable pieces
That is enough for this stage.