Initial commit
This commit is contained in:
defiQUG
269
docs/standards/DIAGRAM_STANDARDS.md
Normal file
269
docs/standards/DIAGRAM_STANDARDS.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user