Skip to content

PlantUML Templates

This directory contains reusable PlantUML templates for creating consistent, professional diagrams across the OVES Odoo Migration documentation.

📋 Available Templates

C4 Architecture Diagrams

File: c4-template.puml

The C4 model provides a hierarchical approach to software architecture diagrams: - Context: System context showing external dependencies - Container: High-level technology choices - Component: Component-level details - Code: Class diagrams (optional)

Usage: 

@startuml
!include <C4/C4_Context>

title My System Context

LAYOUT_WITH_LEGEND()

System(my_system, "My System", "Description")
System_Ext(external, "External System", "Description")

Rel(my_system, external, "Uses", "HTTPS")

@enduml

Sequence Diagrams

File: sequence-diagram.puml

For documenting workflows, API calls, and process flows between actors and systems.

Key Features: - Clear actor/participant definitions with documentation - Inline notes for context - Alt/else branching for conditional flows - Professional styling

Usage Example: 

@startuml
actor User
participant "Odoo" as Odoo
participant "n8n" as Integration

User -> Odoo: Create Contact
Odoo -> Integration: Webhook: contact.created
Integration -> Odoo: Update tags

alt Success
    Integration -> User: Confirmation
else Failure
    Integration -> User: Error notification
end

@enduml

Activity Diagrams

File: activity-diagram.puml

For business process flows and decision trees.

Best For: - Migration workflows - Data transformation processes - Validation procedures - Multi-step operations

Entity Relationship Diagrams

File: entities-erd.puml

For database schema documentation and data model visualization.

Features: - Class-based entity representation - Relationship cardinality - Attribute listing - Inheritance and composition

🎨 Themes and Styling

All templates use the materia-outline theme for modern, clean visuals. You can override with:

!theme materia-outline
' or
!theme plain
!theme sketchy-outline

📖 Best Practices

1. Use C4 for Architecture

  • System Context: External integrations
  • Container: Odoo modules, microservices
  • Component: Module internals

2. Use Sequence for Workflows

  • API interactions
  • Migration steps
  • Integration flows

3. Use Activity for Processes

  • Decision trees
  • Data validation
  • Business logic

4. Use ERD for Data Models

  • Database schema
  • Odoo model relationships
  • Data migration mapping

🔧 Common Patterns

Include C4 Library

!include <C4/C4_Context>
!include <C4/C4_Container>
!include <C4/C4_Component>

Add Notes

note right of System
  Additional context
  or explanation
end note

Color Coding

' In C4
System(sys, "Label", "Description", $tags="critical")

' In standard diagrams
rectangle "Item" #E3F2FD

Relationships

' C4 style
Rel(from, to, "Label", "Technology")
Rel_U(from, to, "Up")
Rel_D(from, to, "Down")
Rel_L(from, to, "Left")
Rel_R(from, to, "Right")

' Standard style
from -> to : Label
from --> to : Async
from ->> to : Return

📝 Naming Conventions

  • Files: Use kebab-case (e.g., odoo-contact-migration.puml)
  • IDs: Use snake_case (e.g., contact_system)
  • Labels: Use Title Case with clarity
  • Notes: Use complete sentences

🔄 Generating PNG Images

Use the KRR script or generate manually:

# Using KRR (includes diagram generation)
.\krr

# Manual generation
java -jar tools\plantuml.jar docs\diagrams\your-diagram.puml

📚 References

💡 Tips

  1. Keep it simple: Focus on clarity over detail
  2. Use layers: Separate concerns into different diagrams
  3. Document inline: Add notes and comments
  4. Version control: Include both .puml and .png
  5. Consistent style: Use templates for uniformity