Mapping & Visualization Scaffolds

Purpose
When to Use
What Is It
Workflow
Common Patterns
Guardrails
Quick Reference

Purpose

Create visual maps that make implicit relationships, dependencies, and structures explicit through diagrams, concept maps, and architectural blueprints.

When to Use

Use mapping-visualization-scaffolds when you need to:

System Understanding:

Document complex system architectures (microservices, infrastructure, data flows)
Map component dependencies and relationships
Visualize API endpoints and integration points
Understand legacy system structure

Knowledge Organization:

Create concept maps for learning or teaching
Build taxonomies and hierarchies
Organize research literature or domain knowledge
Structure information architecture

Process & Flow Documentation:

Map user journeys and workflows
Create decision trees and flowcharts
Document approval chains or escalation paths
Visualize project dependencies and timelines

Strategic Visualization:

Map stakeholder relationships and influence
Visualize organizational structures
Create competitive landscape maps
Document value chains or business models

What Is It

A mapping scaffold is a structured approach to creating visual representations that show:

Nodes (components, concepts, people, steps)
Relationships (connections, dependencies, hierarchies, flows)
Attributes (properties, states, metadata)
Groupings (clusters, categories, layers)

Quick Example:

For a microservices architecture:

Nodes: API Gateway, Auth Service, User Service, Payment Service, Database
Relationships:
  - API Gateway → calls → Auth Service
  - Auth Service → validates → User Service
  - Payment Service → reads/writes → Database
Groupings: Frontend Layer, Business Logic Layer, Data Layer

This creates a visual map showing how services connect and depend on each other.

Workflow

Copy this checklist and track your progress:

Mapping Visualization Progress:
- [ ] Step 1: Clarify mapping purpose
- [ ] Step 2: Identify nodes and relationships
- [ ] Step 3: Choose visualization approach
- [ ] Step 4: Create the map
- [ ] Step 5: Validate and refine

Step 1: Clarify mapping purpose

Ask user about their goal: What system/concept needs mapping? Who's the audience? What decisions will this inform? What level of detail is needed? See Common Patterns for typical use cases.

Step 2: Identify nodes and relationships

List all key elements (nodes) and their connections (relationships). Identify hierarchy levels, dependency types, and grouping criteria. For simple cases (< 20 nodes), use resources/template.md. For complex systems (50+ nodes) or collaborative sessions, see resources/methodology.md for advanced strategies.

Step 3: Choose visualization approach

Select format based on complexity: Simple lists for < 10 nodes, tree diagrams for hierarchies, network graphs for complex relationships, or layered diagrams for systems. For large-scale systems or multi-map hierarchies, consult resources/methodology.md for mapping strategies and tool selection. See Common Patterns for guidance.

Step 4: Create the map

Build the visualization using markdown, ASCII diagrams, or structured text. Start with high-level structure, then add details. Include legend if needed. Use resources/template.md as your scaffold.

Step 5: Validate and refine

Check completeness, clarity, and accuracy using resources/evaluators/rubric_mapping_visualization_scaffolds.json. Ensure all critical nodes and relationships are present. Minimum standard: Score ≥ 3.5 average.

Common Patterns

Architecture Diagrams:

System components as nodes
Service calls/data flows as relationships
Layers as groupings (frontend, backend, data)
Use for: Technical documentation, system design reviews

Concept Maps:

Concepts/ideas as nodes
"is-a", "has-a", "leads-to" as relationships
Themes as groupings
Use for: Learning, knowledge organization, research synthesis

Dependency Graphs:

Tasks/features/modules as nodes
"depends-on", "blocks", "requires" as relationships
Phases/sprints as groupings
Use for: Project planning, risk assessment, parallel work identification

Hierarchies & Taxonomies:

Categories/classes as nodes
Parent-child relationships
Levels as groupings (L1, L2, L3)
Use for: Information architecture, org charts, skill trees

Flow Diagrams:

Steps/states as nodes
Transitions/decisions as relationships
Swim lanes as groupings (roles, systems)
Use for: Process documentation, user journeys, decision trees

Guardrails

Scope Management:

Focus on relationships that matter for the specific purpose
Don't map everything—map what's decision-relevant
Stop at appropriate detail level (usually 3-4 layers deep)
For systems with > 50 nodes, create multiple focused maps

Clarity Over Completeness:

Prioritize understandability over exhaustiveness
Use consistent notation and naming
Add legend if > 3 relationship types
Group related nodes to reduce visual complexity

Validation:

Verify accuracy with subject matter experts
Test if someone unfamiliar can understand the map
Check for missing critical relationships
Ensure directionality is clear (A → B vs A ← B)

Common Pitfalls:

❌ Creating "hairball" diagrams with too many connections
❌ Mixing abstraction levels (strategic + implementation details)
❌ Using inconsistent node/relationship representations
❌ Forgetting to state the map's purpose and scope

Quick Reference

Resources:

resources/template.md - Structured scaffold for creating maps
resources/evaluators/rubric_mapping_visualization_scaffolds.json - Quality criteria

Output:

File: mapping-visualization-scaffolds.md in current directory
Contains: Nodes, relationships, groupings, legend (if needed)
Format: Markdown with ASCII diagrams or structured lists

Success Criteria:

All critical nodes identified
Relationships clearly labeled with directionality
Appropriate grouping/layering applied
Understandable by target audience without explanation
Validated against quality rubric (score ≥ 3.5)

mapping-visualization-scaffolds