Skip to content

Diagram Management Policy

🎯 PlantUML Diagram Standards

📋 Diagram Creation Process

  1. Source files: All diagrams MUST be created as .puml files in docs/diagrams/ directory
  2. PNG generation: Run java -jar plantuml.jar -tpng docs/diagrams/*.puml to generate PNG files
  3. Documentation references: Markdown files MUST reference PNG files, not PUML source
  4. Version control: Both .puml source and .png output files are tracked in git

🗂️ Directory Structure

docs/
├── diagrams/                   # CANONICAL DIAGRAM DIRECTORY
│   ├── *.puml                  # PlantUML source files
│   └── *.png                   # Generated PNG images (auto-generated)
├── architecture/               # References: diagrams/name.png  
├── design/                     # References: diagrams/name.png
└── developer-guides/           # References: diagrams/name.png

models/
└── bss/design-intent/          # References: ../../../docs/diagrams/name.png

📝 Documentation Reference Pattern

When referencing diagrams from documentation in docs/ directory:

![Diagram Title](diagrams/diagram-name.png)

*Figure: Description of the diagram and its purpose.*

When referencing diagrams from business model documentation in models/ directory:

![Diagram Title](../../../docs/diagrams/diagram-name.png)

*Figure: Description of the diagram and its purpose.*

🔄 Regeneration Command

To regenerate all PNG files from PlantUML sources:

# From repository root
java -jar plantuml.jar -tpng docs/diagrams/*.puml

🚫 Prohibited Diagram Formats

  • ❌ Mermaid charts - All Mermaid must be converted to PlantUML
  • ❌ Inline SVG - Use PNG files for better compatibility
  • ❌ External diagram tools - Use PlantUML for consistency

✅ Required PlantUML Structure

All PlantUML files MUST include:

@startuml diagram-name

' Your diagram content here

@enduml

📊 Quality Standards

  • Clear titles: Each diagram must have a descriptive title
  • Proper naming: Use kebab-case for file names (e.g., bss-signal-flow.puml)
  • Consistent styling: Follow existing color and styling patterns
  • Documentation: Include diagram purpose in referencing markdown

🛠️ Maintenance Workflow

Adding New Diagrams

  1. Create .puml file in docs/diagrams/ directory
  2. Generate PNG: java -jar plantuml.jar -tpng docs/diagrams/new-diagram.puml
  3. Reference PNG in documentation
  4. Commit both .puml and .png files

Updating Existing Diagrams

  1. Modify the .puml source file
  2. Regenerate PNG: java -jar plantuml.jar -tpng docs/diagrams/updated-diagram.puml
  3. Verify documentation references are correct
  4. Commit updated files

Removing Diagrams

  1. Remove references from documentation first
  2. Delete both .puml and .png files
  3. Commit changes

📋 Current Diagram Inventory

Architecture Diagrams

  • abs-hub-ecosystem.puml - ABS platform ecosystem overview
  • dirac-framework.puml - DIRAC framework architecture
  • entities-erd.puml - Entity relationship diagram

Business Model Diagrams

  • bss-signal-flow.puml - Battery Swap Service signal flow

State Diagrams

  • customer-state.puml - Customer state machine
  • asset-owner-state.puml - Asset owner state machine
  • iot-asset-state.puml - IoT asset state machine

Integration Diagrams

  • messaging-platform.puml - Messaging platform architecture
  • inter-platform.puml - Inter-platform communication

🔄 Migration Status

✅ Completed

  • Consolidated all diagrams in docs/diagrams/ directory
  • Converted Mermaid sequence diagram to PlantUML (bss-signal-flow.puml)
  • Updated documentation to reference PNG files
  • Established diagram management workflow

📋 Future Tasks

  • Generate missing PNG files for all PlantUML diagrams
  • Validate all diagram references in documentation
  • Establish automated PNG generation in CI/CD

Last Updated: January 2025 Maintained By: Documentation Team