Skip to main content

Visual Enhancement Plan: Mermaid Diagrams

Overview​

This document outlines comprehensive visual enhancements using Mermaid diagrams to strengthen the Ohpen case study presentation. Based on Mermaid's capabilities, we can add multiple diagram types that provide different perspectives on the project.

Current State: Flowcharts, Gantt charts, basic sequence diagrams
Enhancement Goal: Add 15+ new diagram types for comprehensive visual storytelling

Last Updated: January 2026

Table of Contents​

  1. High Priority Enhancements
  2. Medium Priority Enhancements
  3. Low Priority Enhancements
  4. Implementation Guide
  5. Styling Guidelines

High Priority Enhancements​

1. Timeline Diagrams​

Purpose: Show project milestones and key events chronologically (complements Gantt charts which focus on tasks)

Use Cases:

  • Executive summary
  • Stakeholder presentations
  • Project kickoff materials

Example Implementation:

Where to Add:

  • tasks/05_communication_documentation/appendix/modules/02_timeline.md - Add timeline diagram alongside Gantt
  • docs/submission/EXECUTIVE_SUMMARY.md - High-level timeline
  • tasks/05_communication_documentation/PROJECT_GANTT_CHART.md - Milestone timeline

Priority: ⭐⭐⭐ High - Quick win, complements existing Gantt charts

2. State Diagrams​

Purpose: Visualize data lifecycle states and transitions (Bronze → Silver → Gold)

Use Cases:

  • Architecture documentation
  • Data governance documentation
  • Training materials

Example Implementation:

Where to Add:

  • tasks/02_data_lake_architecture_design/ARCHITECTURE.md - Data lifecycle section
  • tasks/01_data_ingestion_transformation/ETL_FLOW.md - State transitions
  • docs/submission/EXECUTIVE_SUMMARY.md - Data flow states

Priority: ⭐⭐⭐ High - Critical for understanding data lifecycle

3. Sankey Diagrams​

Purpose: Show data flow volumes and transformations

Use Cases:

  • ETL documentation
  • Data quality metrics
  • Cost analysis

Example Implementation:

Option 1: Sankey Diagram (if supported by your renderer):

Option 2: Flowchart Alternative (More Reliable):

Option 3: Table with Visual Indicators:

SourceDestinationVolumePercentageStatus
CSV FilesSilver Layer950,00095%✅ Valid
CSV FilesQuarantine40,0004%⚠️ Invalid
CSV FilesCondemned10,0001%❌ No Retry
Silver LayerGold Aggregation900,00090%✅ Business Ready
Silver LayerAnalytics Queries50,0005%📊 Ad-hoc
QuarantineSilver Layer (Retry)35,00087.5%✅ Retry Success
QuarantineCondemned5,00012.5%❌ Max Attempts

Where to Add:

  • tasks/01_data_ingestion_transformation/ETL_FLOW.md - Data volumes section
  • docs/submission/BUSINESS_CASE_SUMMARY.md - Data flow visualization
  • tasks/05_communication_documentation/appendix/modules/03_budget_roi.md - Data volume analysis

Priority: ⭐⭐⭐ High - Great visual for data flow understanding

Note: If sankey-beta doesn't render properly in your documentation platform, use Option 2 (Flowchart) which provides the same visual information with better compatibility.

4. Pie Charts​

Purpose: Show cost breakdown, data distribution, or resource allocation

Use Cases:

  • Budget documentation
  • Cost analysis
  • Data distribution

Example Implementation:

Alternative - Data Quality Distribution:

Where to Add:

  • tasks/05_communication_documentation/appendix/modules/03_budget_roi.md - Cost breakdown
  • tasks/FINAL_IMPLEMENTATION_PLAN.md - Cost analysis section
  • tasks/01_data_ingestion_transformation/ETL_FLOW.md - Data quality metrics

Priority: ⭐⭐⭐ High - Quick visual for costs and metrics

5. Enhanced Sequence Diagrams​

Purpose: Show detailed interactions between components (enhance existing basic ones)

Use Cases:

  • ETL flow documentation
  • CI/CD workflow
  • Error handling flows

Example Implementation:

Where to Add:

  • tasks/01_data_ingestion_transformation/ETL_FLOW.md - Enhanced sequence (replace basic one)
  • tasks/04_devops_cicd/CI_CD_WORKFLOW.md - CI/CD interactions
  • appendix/APPENDIX_A_ETL_DIAGRAMS.md - Detailed component interaction

Priority: ⭐⭐⭐ High - Improves existing diagrams significantly

Medium Priority Enhancements​

6. User Journey Diagrams​

Purpose: Map stakeholder interactions and decision points throughout the project

Use Cases:

  • Stakeholder communication module
  • Training materials
  • Process documentation

Example Implementation:

Where to Add:

  • tasks/05_communication_documentation/appendix/modules/01_project_overview.md
  • tasks/05_communication_documentation/STAKEHOLDER_EMAIL.md
  • docs/submission/EXECUTIVE_SUMMARY.md - Stakeholder experience

Priority: ⭐⭐ Medium - Great for stakeholder communication

7. Entity Relationship Diagrams​

Purpose: Model data relationships and schema structure

Use Cases:

  • SQL documentation
  • Data modeling
  • Schema evolution documentation

Example Implementation:

Where to Add:

  • tasks/03_sql/SQL_BREAKDOWN.md - Data model section
  • tasks/02_data_lake_architecture_design/ARCHITECTURE.md - Schema design
  • appendix/APPENDIX_E_SQL_CODE.md - Data relationships

Priority: ⭐⭐ Medium - Useful for data modeling documentation

8. Quadrant Charts​

Purpose: Prioritize features, risks, or tasks

Use Cases:

  • Risk assessment
  • Feature prioritization
  • Task planning

Example Implementation:

Where to Add:

  • tasks/05_communication_documentation/appendix/modules/05_risks_mitigation.md
  • tasks/FINAL_IMPLEMENTATION_PLAN.md - Risk assessment
  • docs/submission/EXECUTIVE_SUMMARY.md - Risk visualization

Priority: ⭐⭐ Medium - Great for risk management visualization

9. C4 Diagrams​

Purpose: Show architecture at different levels (Context, Container, Component)

Use Cases:

  • Architecture documentation
  • System design
  • Stakeholder communication

Example Implementation:

Where to Add:

  • tasks/02_data_lake_architecture_design/ARCHITECTURE.md - System context section
  • docs/submission/EXECUTIVE_SUMMARY.md - High-level architecture
  • tasks/05_communication_documentation/appendix/modules/04_architecture_summary.md

Priority: ⭐⭐ Medium - Excellent for architecture communication

10. Mindmaps​

Purpose: Organize project structure, concepts, or documentation

Use Cases:

  • Project overview
  • Documentation navigation
  • Concept mapping

Example Implementation:

Where to Add:

  • README.md - Project structure overview
  • docs/README.md - Documentation navigation
  • tasks/05_communication_documentation/appendix/modules/01_project_overview.md

Priority: ⭐⭐ Medium - Good for navigation and overview

Low Priority Enhancements​

11. Class Diagrams​

Purpose: Model data structures, validation rules, or component relationships

Use Cases:

  • Code documentation
  • Data structure design
  • API design

Example Implementation:

Where to Add:

  • tasks/01_data_ingestion_transformation/ETL_FLOW.md - Data structures section
  • appendix/APPENDIX_B_ETL_PSEUDOCODE.md - Code structure
  • docs/technical/PYSPARK_IMPLEMENTATION_SUMMARY.md - Implementation details

Priority: ⭐ Low - More useful for code documentation

12. GitGraph Diagrams​

Purpose: Show version control workflow and branching strategy

Use Cases:

  • CI/CD documentation
  • Development workflow
  • Code management

Example Implementation:

Where to Add:

  • tasks/04_devops_cicd/CI_CD_WORKFLOW.md - Version control strategy
  • docs/development/ - Development workflow (if exists)

Priority: ⭐ Low - Nice to have for development docs

13. XY Charts​

Purpose: Show metrics over time, performance comparisons, or trends

Use Cases:

  • Performance metrics
  • Cost trends
  • Data quality metrics

Example Implementation:

Alternative - Quarantine Rate Trend:

Where to Add:

  • docs/technical/TEST_RESULTS_OVERVIEW.md - Performance trends
  • tasks/01_data_ingestion_transformation/reports/ - Performance reports
  • tasks/05_communication_documentation/appendix/modules/03_budget_roi.md - Cost trends

Priority: ⭐ Low - Useful for reporting but requires data

14. Block Diagrams​

Purpose: Show system components and their relationships

Use Cases:

  • Infrastructure documentation
  • System architecture
  • Component relationships

Example Implementation:

Where to Add:

  • tasks/02_data_lake_architecture_design/ARCHITECTURE.md - Component view
  • docs/submission/EXECUTIVE_SUMMARY.md - System overview

Priority: ⭐ Low - Similar to existing flowcharts

15. Requirement Diagrams​

Purpose: Show requirements relationships and dependencies

Use Cases:

  • Requirements documentation
  • Feature dependencies
  • Project planning

Example Implementation:

Where to Add:

  • tasks/01_data_ingestion_transformation/ASSUMPTIONS_AND_EDGE_CASES.md - Requirements section
  • tasks/FINAL_IMPLEMENTATION_PLAN.md - Feature requirements

Priority: ⭐ Low - Nice to have for requirements tracking

Implementation Guide​

Step-by-Step Implementation​

  1. Review and Prioritize: Select which diagrams add most value for your use case
  2. Create Examples: Implement 3-5 high-priority diagrams first
  3. Integrate: Add diagrams to relevant documentation files
  4. Test Rendering: Verify diagrams render correctly in your documentation platform
  5. Iterate: Add more diagrams based on feedback and needs

Quick Start: Top 5 Diagrams to Add First​

  1. Timeline Diagram → tasks/05_communication_documentation/appendix/modules/02_timeline.md
  2. State Diagram → tasks/02_data_lake_architecture_design/ARCHITECTURE.md
  3. Sankey Diagram → tasks/01_data_ingestion_transformation/ETL_FLOW.md
  4. Pie Chart (Costs) → tasks/05_communication_documentation/appendix/modules/03_budget_roi.md
  5. Enhanced Sequence Diagram → tasks/01_data_ingestion_transformation/ETL_FLOW.md

Testing Your Diagrams​

  1. Mermaid Live Editor: Test diagrams at https://mermaid.live before adding to docs
  2. Local Rendering: Use your documentation platform's preview feature
  3. GitHub/GitLab: Push to repository and verify rendering in browser
  4. MkDocs/Docusaurus: Build documentation site and verify

Styling Guidelines​

All new diagrams should follow the existing System 2 (Color + Border Hybrid) styling:

Color Tokens​

  • State colors: Bronze (Orange #f57c00), Silver (Green #388e3c), Gold (Blue #1976d2), Quarantine (Red #d32f2f)
  • Function colors: ETL (Purple #ba68c8), Infrastructure (Gray #424242), CI/CD (Indigo #5c6bc0), Observability (Teal #00897b)
  • Control colors: Decision (Yellow #fbc02d), Testing (Light Green #66bb6a)

Border Rules​

  • State nodes: 2px solid border with function color (when needed)
  • Control nodes: 2px dashed border (always)
  • Light variants: 2px dotted border (always)
  • Meta tokens: 3px solid border (always)
  • Errors: 3px solid border (always)

Diagram-Specific Notes​

  • Timeline: No styling needed, uses default Mermaid styling
  • State Diagrams: Use notes for additional context
  • Sankey: ⚠️ Experimental feature - May not render in all platforms. Use flowchart alternative (Option 2) if sankey-beta fails
  • Pie Charts: Use colors matching data categories
  • Sequence Diagrams: Use participant colors matching component types

Troubleshooting: Sankey Diagrams​

If sankey-beta diagrams don't render properly:

  1. Check Mermaid version: Sankey-beta requires Mermaid v10.0.0+
  2. Use Flowchart Alternative: The flowchart option (Option 2) provides the same information with better compatibility
  3. Test in Mermaid Live Editor: https://mermaid.live - If it works there but not in your docs, it's a renderer issue
  4. Fallback to Table: Option 3 (table format) always works and is accessible

Recommended: Use the Flowchart Alternative (Option 2) for maximum compatibility across all documentation platforms.

See docs/STYLING_SYSTEMS_COMPLETE.md for complete styling guidelines.

References​

Summary​

Priority Breakdown​

  • High Priority (5 diagrams): Timeline, State, Sankey, Pie Charts, Enhanced Sequence
  • Medium Priority (5 diagrams): User Journey, ER Diagrams, Quadrant Charts, C4 Diagrams, Mindmaps
  • Low Priority (5 diagrams): Class Diagrams, GitGraph, XY Charts, Block Diagrams, Requirement Diagrams

Expected Impact​

  • Visual Storytelling: Multiple perspectives on the same project
  • Stakeholder Communication: Different diagrams for different audiences
  • Documentation Quality: Professional, comprehensive visual documentation
  • Interview Presentation: Rich visual materials for discussion

Next Steps​

  1. Start with high-priority diagrams
  2. Test rendering in your documentation platform
  3. Gather feedback
  4. Iterate and expand

Last Updated: January 2026
Status: Enhancement Plan - Ready for Implementation
Owner: Data Platform Team

© 2026 Stephen Adei•CC BY 4.0