smoa/docs/standards/DIAGRAM_STANDARDS.md

# SMOA Diagram Standards

**Version:** 1.0  
**Last Updated:** 2024  
**Status:** Active

---

## Purpose

This document establishes standards for creating diagrams in SMOA documentation to ensure consistency, clarity, and maintainability.

---

## Diagram Types

### Architecture Diagrams
- System architecture
- Component architecture
- Module architecture
- Deployment architecture

### Flow Diagrams
- Process flows
- Data flows
- User flows
- Integration flows

### Sequence Diagrams
- API interactions
- Authentication flows
- Transaction flows

### Entity Relationship Diagrams
- Database schema
- Data models

---

## Tools

### Primary Tools
- **PlantUML** - Text-based diagramming (preferred for version control)
- **Mermaid** - Markdown-based diagramming
- **Draw.io** - Visual diagramming (for complex diagrams)

### Tool Selection
- Use PlantUML for architecture and sequence diagrams
- Use Mermaid for simple flow diagrams in Markdown
- Use Draw.io for complex visual diagrams

---

## Diagram Standards

### Naming Conventions
- Use kebab-case for diagram files
- Include diagram type in name (e.g., `system-architecture.puml`)
- Use descriptive names (e.g., `authentication-flow.puml`)

### File Organization
- Store diagrams in `docs/architecture/diagrams/`
- Organize by category (architecture, flows, sequences)
- Include source files (`.puml`, `.mmd`) and rendered images (`.png`, `.svg`)

### Diagram Size
- Keep diagrams readable (max 1920x1080 for screens)
- Break complex diagrams into multiple diagrams
- Use zoom/pan for large diagrams

### Colors and Styling
- Use consistent color scheme
- Follow accessibility guidelines (color contrast)
- Use standard shapes and symbols
- Include legends for complex diagrams

---

## Architecture Diagrams

### System Architecture
- Show high-level system components
- Show external systems
- Show data flows
- Include security boundaries

### Component Architecture
- Show component relationships
- Show interfaces
- Show dependencies
- Include technology stack

### Module Architecture
- Show module structure
- Show module dependencies
- Show module interfaces
- Include module responsibilities

---

## Flow Diagrams

### Process Flows
- Use standard flowchart symbols
- Show decision points clearly
- Include error paths
- Show start and end points

### Data Flows
- Show data sources and destinations
- Show data transformations
- Include data formats
- Show security boundaries

### User Flows
- Show user actions
- Show system responses
- Include decision points
- Show error handling

---

## Sequence Diagrams

### API Interactions
- Show all participants
- Show message flows
- Include timing information
- Show error scenarios

### Authentication Flows
- Show authentication steps
- Show security boundaries
- Include token flows
- Show error handling

---

## Entity Relationship Diagrams

### Database Schema
- Show all entities
- Show relationships
- Include cardinality
- Show primary/foreign keys

### Data Models
- Show data structures
- Show relationships
- Include constraints
- Show inheritance

---

## Diagram Best Practices

### Clarity
- Keep diagrams simple and focused
- Avoid clutter
- Use clear labels
- Include legends

### Consistency
- Use consistent symbols
- Use consistent colors
- Use consistent layout
- Follow naming conventions

### Maintainability
- Use text-based tools when possible
- Version control diagram sources
- Document diagram assumptions
- Update diagrams with code changes

### Accessibility
- Use high contrast colors
- Include text descriptions
- Use alt text for images
- Follow WCAG guidelines

---

## Diagram Templates

### System Architecture Template (PlantUML)
```plantuml
@startuml system-architecture
!include <tupadr3/common>
!include <tupadr3/font-awesome/users>

title System Architecture

package "External Systems" {
  [External System 1]
  [External System 2]
}

package "SMOA Application" {
  [Module 1]
  [Module 2]
  [Module 3]
}

[External System 1] --> [Module 1]
[Module 1] --> [Module 2]
[Module 2] --> [Module 3]
[Module 3] --> [External System 2]

@enduml
```

### Sequence Diagram Template (PlantUML)
```plantuml
@startuml sequence-example
title Example Sequence Diagram

actor User
participant "SMOA App" as App
participant "API Server" as API
database "Database" as DB

User -> App: Action
App -> API: Request
API -> DB: Query
DB --> API: Result
API --> App: Response
App --> User: Display

@enduml
```

---

## Diagram Review Checklist

Before including a diagram in documentation:
- [ ] Diagram follows naming conventions
- [ ] Diagram is clear and readable
- [ ] Diagram uses consistent styling
- [ ] Diagram includes necessary details
- [ ] Diagram is not overly complex
- [ ] Diagram has appropriate size
- [ ] Diagram includes caption/description
- [ ] Diagram is referenced in text
- [ ] Diagram source is version controlled
- [ ] Diagram is accessible (color contrast, alt text)

---

## Resources

### PlantUML
- Documentation: https://plantuml.com/
- Examples: https://real-world-plantuml.com/

### Mermaid
- Documentation: https://mermaid.js.org/
- Live Editor: https://mermaid.live/

### Draw.io
- Website: https://app.diagrams.net/
- Templates: https://www.diagrams.net/blog/templates

---

**Document Owner:** Documentation Lead  
**Last Updated:** 2024  
**Next Review:** Quarterly