← Back to Documentation Home

User Documentation

User Documentation

This guide helps you use Korgraph to model and visualize your architecture.

🎯 Getting Started

What is Korgraph?

Korgraph is an interactive web-based tool for modeling enterprise architectures. It helps you:

  • Visualize system components and their relationships
  • Model business processes and workflows with narrative stories
  • Collaborate with draft workflow (review, merge, approve)
  • Track scope across products and regions
  • Import/export architecture as YAML for version control
  • Work on mobile devices with responsive UI
  • Export architecture documentation

Key Features

📖 Story Editor

  • Create narrative process flows: "Customer submits Order to Order Management"
  • Visual caption preview as you type
  • Connected objects panel shows interfaces, events, and relationships
  • Edit and manage process stories

📝 Draft Workflow

  • Create isolated drafts for safe experimentation
  • 3-step merge wizard with conflict resolution
  • Review and approval process
  • Full version history and rollback

📦 YAML Import/Export

  • Export entire architecture or specific contexts
  • Version control your architecture in Git
  • Automated backups and restore
  • Command-line import on startup

📱 Mobile Support

  • Responsive design for tablets and phones
  • Touch-friendly interactions
  • Overlay stacking for multiple panels

Quick Start

  1. Open Korgraph in your browser
  2. Choose a perspective: Components, Systems, or Processes
  3. Navigate using the hierarchy breadcrumbs
  4. Switch modes: View (graph) or Editor (list)
  5. Create elements using the + button

📊 Perspectives

Korgraph provides three interconnected perspectives for modeling your architecture:

Components Perspective

Model your domain architecture:

  • Company → Domain → Subdomain → Context hierarchy
  • Bounded contexts and their interactions
  • Interface calls and event flows
  • Actor roles and responsibilities

📖 Read the Components Guide →

Systems Perspective

Visualize your technical landscape:

  • System landscapes and systems
  • System modules and features
  • Technical dependencies
  • Deployment architecture

📖 Read the Systems Guide →

Processes Perspective

Document business workflows:

  • Process landscapes and processes
  • Process steps and orchestration
  • Actor participation
  • Data object usage
  • 🆕 Draft workflow - Safe design and testing before production

📖 Read the Processes Guide →

✨ New: Draft Workflow Guide - Learn how to create, test, and merge draft processes.

📚 Feature Guides

Core Features

Mobile & Responsive

  • Adaptive layout for tablets and phones
  • Touch-friendly drag and drop
  • Overlay management for multiple panels
  • Optimized for various screen sizes

Help & Feedback

🆘 Need Help?

  • Click "Help" in the footer for an interactive guided tour
  • 6-step walkthrough covering all major features
  • Access anytime, skip auto-show with "Don't show again"

💬 Provide Feedback

  • Click "Feedback" in the footer to submit feedback
  • Report issues, suggest features, or share your experience
  • Optional email field for responses
  • Attach screenshots to illustrate issues
  • Feedback helps us improve Korgraph!

� View Feature Requests & Bug Reports

  • See what features are being worked on
  • Track bug fixes and improvements
  • View community feedback
  • Feedback Viewer Guide - Learn how to view existing feedback

�📖 Documentation

  • Click "Documentation" in the footer for quick access
  • Browse all guides, tutorials, and examples
  • Search for specific topics

🏗️ Element Types

Organizational Elements

  • Company - Root organizational entity
  • Domain - Business domain boundaries
  • Subdomain - Domain subdivisions
  • Context - Bounded context in DDD

Technical Elements

  • System - Software application
  • System Module - Application component
  • Feature - System capability
  • Interface - API or service interface
  • Event - Domain event

Process Elements

  • Process - Business workflow
  • Process Step - Workflow stage
  • Actor - Person or system role
  • Data Object - Information artifact
  • Timer - Scheduled trigger

Scope Elements

  • Business Product - Commercial offering
  • Region - Geographic deployment
  • Business - Business unit

See Element Reference for complete field details.

🔗 Relationships

Interface Connections

System-to-system API calls:

  • Create by drawing connections in View mode
  • Specify caller and provider
  • Auto-discovered from process flows

Event Connections

Publish/subscribe patterns:

  • Define event publishers
  • Specify event subscribers
  • Cross-domain communication

Process Orchestration

Chain processes together:

  • Triggers - Start next process
  • Awaits - Wait for completion
  • Timer - Schedule execution

🎨 Working in View Mode

Navigation

  • Pan - Click and drag background
  • Zoom - Mouse wheel or pinch
  • Focus - Click element to drill down
  • Breadcrumbs - Navigate back up

Layouts

Choose from multiple automatic layouts:

  • Fcose - Force-directed (default)
  • Dagre - Hierarchical layout
  • Cola - Constraint-based
  • Circle - Circular arrangement

Interactions

  • Select - Click element to inspect
  • Draw Connection - Enable drawing mode
  • Add Element - Create new child
  • Edit - Double-click to edit

📖 Read the View Mode Guide →

✏️ Working in Editor Mode

List View

  • See all elements in tabular format
  • Quick edit multiple elements
  • Bulk operations
  • Search and filter

Editing Elements

  1. Click element row to expand
  2. Edit fields inline
  3. Changes save automatically
  4. View relationships in Inspector

🔍 Search & Filtering

Universal Search

  • Search across all element types
  • Uses database indexes for speed
  • Results show element hierarchy
  • Click to navigate

Scope Filtering

Filter by:

  • Business Product - Show only specific products
  • Region - Filter by geography
  • Business - Filter by business unit

Filters apply to all perspectives.

📤 Import & Export

Export Options

  • Markdown - Human-readable documentation
  • YAML - Version control friendly
  • Structurizr DSL - Architecture as code
  • BPMN 2.0 - Process modeling format
# Export via UI: Tools → Export
# Creates ZIP with all formats

Import Data

# Import YAML backup
curl -X POST http://app.korgraph.io/api/import/yaml \
  -H "Content-Type: application/x-yaml" \
  --data-binary @backup.yaml

See Import/Export Guide for details.

💡 Best Practices

Modeling Tips

  • Start with high-level domains
  • Use contexts for bounded capabilities
  • Model actual interfaces, not planned ones
  • Document process flows with actors
  • Assign scopes consistently

Organization

  • Group related contexts in subdomains
  • Use clear, descriptive names
  • Add descriptions for clarity
  • Leverage scope filters for multi-tenancy

Collaboration

  • Save layout regularly
  • Use consistent naming conventions
  • Document relationships
  • Review exported documentation

See Best Practices for more tips.

🆘 FAQ

Q: How do I create a connection between systems? A: Switch to View mode, enable drawing mode, then click source and target elements.

Q: Can I import existing architecture? A: Yes, use YAML import or create elements via the API.

Q: How do I model a microservice architecture? A: Use Systems perspective with modules for services and features for endpoints.

Q: What's the difference between Actor and Context? A: Actors are roles (people/systems), Contexts are functional boundaries.

See FAQ for more questions.

📖 Additional Resources