README - jonasyr/gitray GitHub Wiki

   ██████╗ ██╗████████╗██████╗  █████╗ ██╗   ██╗
  ██╔════╝ ██║╚══██╔══╝██╔══██╗██╔══██╗╚██╗ ██╔╝
  ██║  ███╗██║   ██║   ██████╔╝███████║ ╚████╔╝ 
  ██║   ██║██║   ██║   ██╔══██╗██╔══██║  ╚██╔╝  
  ╚██████╔╝██║   ██║   ██║  ██║██║  ██║   ██║   
   ╚═════╝ ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   
    Official Wiki of the GitRay Repository!

Table of Contents

Description

This is the official wiki for the GitRay repository, featuring comprehensive PlantUML integration for documentation.

PlantUML Integration for GitRay Wiki

This wiki uses a simple local script approach to render PlantUML diagrams with enhanced features and colorful output.

Quick Start

  1. Create your PlantUML diagrams in the diagrams/ folder with .puml extension
  2. Run the render script: ./render-diagrams.sh
  3. Follow interactive prompts to install missing dependencies (Java/Graphviz)
  4. Commit and push the generated images
  5. Reference images in your wiki pages

Directory Structure

gitray.wiki/
├── diagrams/           # Your PlantUML source files (.puml)
├── images/            # Generated image files
│   ├── png/          # PNG format images
│   └── svg/          # SVG format images
├── render-diagrams.sh # Enhanced script with colorful output
└── README.md         # This file

Prerequisites

The script will automatically check for and offer to install missing dependencies:

  • Java Runtime Environment (for PlantUML)
  • Graphviz (for advanced UML diagram rendering)

Manual installation (if needed):

# Java
sudo apt install default-jre

# Graphviz
sudo apt update && sudo apt install -y graphviz

Usage

Step 1: Create PlantUML Files

Create your diagrams in the diagrams/ folder following the naming convention:

Example: diagrams/UserLoginSequenceDiagram.puml

@startuml User Login Sequence Diagram
!theme plain
title User Login Process

Alice -> Bob: Authentication Request
Bob -> Database: Validate Credentials
Database -> Bob: Credentials Valid
Bob -> Alice: Authentication Success
@enduml

This will generate:

  • images/png/User Login Sequence Diagram.png
  • images/svg/User Login Sequence Diagram.svg

Step 2: Render Diagrams

Run the render script:

./render-diagrams.sh

Smart Rendering Options:

./render-diagrams.sh         # Only render changed/missing files (recommended)
./render-diagrams.sh --force # Force render all files regardless of status
./render-diagrams.sh -f      # Short form of --force

What the script does:

  • Display the GitRay logo with colorful output
  • Check for required dependencies (Java & Graphviz)
  • Offer interactive installation if dependencies are missing
  • Download PlantUML jar (first time only)
  • Smart Detection: Find all .puml and .plantuml files in diagrams/
  • Intelligent Rendering: Only process files that need updates:
    • Files with missing PNG/SVG outputs
    • Files newer than their generated images
    • Files with uncommitted git changes
  • Generate PNG versions in images/png/
  • Generate SVG versions in images/svg/
  • Progress Reports: Show rendering summary and skip notifications

Step 3: Commit Images

git add images/
git commit -m "Update PlantUML diagrams"
git push

Step 4: Use in Wiki Pages

Reference the generated images in your markdown using the new organized structure:

Examples:

# For PNG images (better for screenshots/exports)
![Filename](images/png/Filename.png)

# For SVG images (better for web, scalable)
![Filename](images/svg/Filename.svg)

Enhanced Features

  • Colorful Output: GitRay logo and color-coded messages
  • Interactive Setup: Automatic dependency checking and installation
  • Organized Structure: PNG and SVG files in separate directories
  • Smart Detection: Finds all .puml and .plantuml files
  • Intelligent Rendering: Only renders files when needed:
    • Missing output files (PNG/SVG don't exist)
    • Source files newer than outputs (timestamp comparison)
    • Files with git changes (modified, added, untracked)
  • Force Mode: --force flag to render all files regardless of status
  • Progress Indicators: Clear status messages and rendering summaries
  • Smart Filename Detection: Handles PlantUML @startuml titles correctly
  • Skip Notifications: Shows which files are up-to-date and skipped
  • Git Integration: Checks repository status for change detection

PlantUML Tips

  • Use !theme plain for consistent styling
  • Keep diagrams reasonably sized for web display
  • Use descriptive filenames
  • Comment complex diagrams in the source
  • PlantUML Naming: The script automatically detects output filenames from @startuml Title directives

AI-Friendly Diagram Best Practices

This section provides systematic templates and guidelines to help AI systems generate consistent, high-quality PlantUML diagrams on the first try for any component or feature.

General Diagram Standards

Required Header Pattern:

@startuml [ComponentName] [DiagramType] Diagram
!theme plain
skinparam defaultFontSize 11
skinparam backgroundColor white
' ... specific styling parameters

Consistent Color Schemes:

  • Primary Elements: #LightBlue, #LightGreen, #LightYellow
  • Secondary Elements: #LightCyan, #Wheat, #Lavender
  • Error/Critical: #LightPink, #MistyRose
  • Utilities/External: #LightGray, #Gainsboro

Package Diagram Best Practices

Purpose: Show high-level architecture and dependencies between modules, applications, and external systems.

Template Structure:

@startuml [ComponentName] Package Diagram
!theme plain
skinparam packageStyle rectangle
skinparam linetype ortho
skinparam defaultFontSize 12
skinparam packageFontSize 14
skinparam componentFontSize 11

package "Main System" #LightBlue {
    package "Core Logic" #LightGreen {
        component [Primary Component] #White
        component [Secondary Component] #White
    }
    
    package "Services" #LightCyan {
        component [Service A] #White
        component [Service B] #White
    }
    
    package "Data Layer" #LightYellow {
        component [Data Access] #White
        component [Cache] #White
    }
}

package "External Dependencies" #LightGray {
    component [External API] #White
    component [Database] #White
}

' Relationships
[Primary Component] --> [Service A] : uses
[Service A] --> [External API] : calls
@enduml

Key Principles:

  • Group related components in logical packages
  • Use consistent colors for similar layer types
  • Show dependencies with clear arrow directions
  • Include external dependencies as separate packages
  • Add notes for complex relationships

Class Diagram Best Practices

Purpose: Define object-oriented structure, inheritance, and relationships between classes.

Template Structure:

@startuml [ComponentName] Class Diagram
!theme plain
skinparam linetype ortho
skinparam defaultFontSize 10
skinparam classFontSize 11
skinparam backgroundColor white
skinparam classBackgroundColor #F8F9FA
skinparam classBorderColor #6C757D

' Abstract base classes
abstract class BaseClass #LightGray {
    # protectedField: type
    + publicMethod(): returnType
    {abstract} + abstractMethod(): returnType
}

package "Core Classes" #LightBlue {
    class MainClass #White {
        - privateField: type
        + publicField: type
        --
        + constructor(params)
        + publicMethod(): returnType
        - privateMethod(): returnType
    }
}

package "Data Interfaces" #LightCyan {
    interface DataInterface #White {
        + field: type
        + method(): returnType
    }
}

package "Types & Enums" #LightYellow {
    enum StatusEnum #White {
        ACTIVE = "active"
        INACTIVE = "inactive"
    }
}

' Relationships
BaseClass <|-- MainClass
MainClass --> DataInterface : implements
MainClass --> StatusEnum : uses
@enduml

Key Principles:

  • Group classes by logical packages/namespaces
  • Use inheritance arrows (<|--) for extends/implements
  • Use composition arrows (*--, o--) for ownership
  • Use dependency arrows (-->, ..>) for usage
  • Include method signatures and important fields
  • Color-code by responsibility (entities, services, utilities)

Activity Diagram Best Practices

Purpose: Show workflow, business processes, and user interactions step-by-step.

Template Structure:

@startuml [ComponentName] Activity Diagram
!theme plain
skinparam defaultFontSize 11
skinparam activityFontSize 10
skinparam backgroundColor white
skinparam activityBackgroundColor #E6F3FF
skinparam activityBorderColor #4A90E2
skinparam activityStartColor #5CB85C
skinparam activityEndColor #D9534F

start

:User initiates action;
#LightBlue:System receives request;

if (Validation successful?) then (yes)
    #LightGreen:Process request;
    #LightYellow:Update data;
    
    fork
        #LightCyan:Send notification;
    fork again
        #Wheat:Log activity;
    end fork
    
else (no)
    #LightPink:Display error message;
    #MistyRose:Log error;
endif

:Return response;
stop
@enduml

Key Principles:

  • Use consistent color coding for different action types:
    • #LightBlue: User actions
    • #LightGreen: Successful system operations
    • #LightYellow: Data operations
    • #LightPink/#MistyRose: Error handling
  • Include decision points with clear yes/no paths
  • Use fork/end fork for parallel processes
  • Add notes for complex business rules
  • Show both happy path and error scenarios

Object Diagram Best Practices

Purpose: Show runtime instances and their relationships at a specific moment in time.

Template Structure:

@startuml [ComponentName] Object Diagram
!theme plain
skinparam linetype ortho
skinparam objectBorderThickness 2
skinparam defaultFontSize 10
skinparam objectFontSize 9
skinparam backgroundColor white
skinparam objectBackgroundColor #F8F9FA

object "mainInstance : MainClass" as main #LightBlue {
    id: "abc123"
    status: "active"
    timestamp: "2025-06-19T10:30:00Z"
}

object "dataInstance : DataClass" as data #LightCyan {
    value: "sample data"
    isValid: true
    lastModified: "2025-06-19T10:25:00Z"
}

object "configInstance : ConfigClass" as config #LightYellow {
    setting1: "value1"
    setting2: 42
    enabled: true
}

' Relationships
main ||--o data : contains
main ||..o config : uses

note top of main #E8F5E8
  **Runtime State Example**
  Shows actual values during
  typical system operation
end note
@enduml

Key Principles:

  • Use realistic sample data that represents typical usage
  • Show object state at meaningful moments (after initialization, during processing, etc.)
  • Include timestamps and IDs to show temporal relationships
  • Use different line styles for different relationship types
  • Add notes explaining the context or significance of the state

Component-Specific Guidelines

For React Components:

  • Package Diagram: Show component hierarchy, hooks, and external libraries
  • Class Diagram: Include props interfaces, state management, and lifecycle
  • Activity Diagram: Focus on user interactions and state changes
  • Object Diagram: Show component instances with actual prop values

For Backend Services:

  • Package Diagram: Show service layers, data access, and external APIs
  • Class Diagram: Include service classes, DTOs, and repository patterns
  • Activity Diagram: Focus on request processing and business logic flow
  • Object Diagram: Show service instances with configuration and dependencies

For Testing Frameworks:

  • Package Diagram: Show test organization and configuration files
  • Class Diagram: Include test classes, mocks, and assertion utilities
  • Activity Diagram: Focus on test execution flow and setup/teardown
  • Object Diagram: Show test instances with actual test data and configurations

AI Prompt Templates

For Package Diagrams:

Create a PlantUML package diagram for [ComponentName] showing:
- Main system packages and their components
- External dependencies and integrations
- Service layers and data flow
- Use the GitRay wiki color scheme and styling
- Follow the package diagram best practices template

For Class Diagrams:

Create a PlantUML class diagram for [ComponentName] showing:
- Main classes with key methods and properties
- Interfaces and abstract classes
- Inheritance and composition relationships
- Group related classes in packages
- Use GitRay wiki styling and color conventions

For Activity Diagrams:

Create a PlantUML activity diagram for [ComponentName] showing:
- User workflow from start to finish
- Decision points and error handling
- Parallel processes where applicable
- Use color coding: blue for user actions, green for success, pink for errors
- Include relevant notes for business logic

For Object Diagrams:

Create a PlantUML object diagram for [ComponentName] showing:
- Runtime instances with realistic sample data
- Object relationships and dependencies
- State at a meaningful moment in execution
- Include explanatory notes about the context
- Use GitRay wiki object styling