Learn how to connect your diagrams to GitHub repositories and Figma designs for living documentation
Integration nodes let you bridge the gap between your architecture diagrams and the real-world resources they represent. Link services to their GitHub repositories, connect UI components to their Figma designs, and create documentation that stays in sync with reality.
What integration nodes are and why they matter
How to add GitHub and Figma integrations
Best practices for connecting external resources
Creating living, clickable documentation
Integration nodes transform static diagrams into interactive documentation hubs. When code or design files change, your team can click directly from the diagram to view the latest version.
Integration nodes are special node types that link to external resources. They come in two flavors:
Link to repositories, specific files, pull requests, or issues. Great for connecting architecture components to their source code.
Connect to design files, frames, or components. Perfect for linking UI components to their design specifications.
GitHub Integration Uses:
Repository overview links • Direct file navigation • Pull request references • Issue tracking connections
Figma Integration Uses:
Design file links • Specific frame references • Component library connections • Design system documentation
Integration nodes solve a critical problem in technical documentation: the gap between diagrams and reality. Here's why they're powerful:
Single Source of Truth - Diagrams link directly to actual code and designs
Faster Navigation - Click from architecture overview to implementation
Better Onboarding - New developers can explore codebase visually
Living Documentation - Links stay current as repositories evolve
Team Collaboration - Designers and developers share common reference
GitHub integrations let you link architecture components to their source code. Here's how to add them:
Click "Add Integration" in the sidenav
Choose GitHub from the integration options
Paste the GitHub URL (repository, file, PR, or issue)
Place the integration node near related components
Draw connections to show relationships
Repository: https://github.com/username/repo
File: https://github.com/username/repo/blob/main/path/to/file.ts
Pull Request: https://github.com/username/repo/pull/123
Issue: https://github.com/username/repo/issues/456
// Example: Linking a service to its repository
// 1. Create a service node labeled "User Authentication Service"
// 2. Add GitHub integration with URL:
// https://github.com/mycompany/auth-service
// 3. Connect with edge labeled "implemented in"
// Result: Clicking the GitHub node opens the repo
// Team members can jump from architecture to code instantlyFigma integrations connect your architecture to design files, perfect for frontend components and design systems.
Click "Add Integration" in sidenav
Choose Figma from integration options
Paste Figma file or frame URL
Use design file name or component name
Link UI components to their designs
Design File: https://figma.com/file/abc123/Design-System
Specific Frame: https://figma.com/file/abc123/Design-System?node-id=123:456
Prototype: https://figma.com/proto/abc123/Mobile-App
Integration nodes become powerful when connected to your architecture. Use edges to show meaningful relationships:
Connect services/components to their GitHub repos
Link UI components to Figma designs
Reference documentation files
Link features to GitHub issues
Connect changes to pull requests
// Connection Pattern Examples:
// Backend Service → GitHub Repository
[User Service] --"implemented in"--> [GitHub: auth-service]
// Frontend Component → Figma Design
[Button Component] --"designed in"--> [Figma: Design System]
// Feature → GitHub Issue
[Payment Flow] --"tracked in"--> [GitHub: Issue #234]
// Architecture Change → Pull Request
[New API Gateway] --"reviewed in"--> [GitHub: PR #456]Use consistent edge labels across your diagrams. This creates a predictable navigation experience for your team.
Link every major service to its repository
Connect frontend components to Figma designs
Use descriptive edge labels ("implemented in", "designed in")
Keep URLs up-to-date as repositories evolve
Group related integrations visually
Don't create integration nodes without connecting them
Don't use vague edge labels like 'related to'
Don't link to outdated or archived resources
Don't overcrowd diagrams with too many integrations
Link each service to its repository • Connect API Gateway to API documentation • Reference deployment configs in infrastructure repos
Connect components to Figma design specs • Link style guides to design files • Reference component library documentation
Track features to GitHub issues • Link implementations to pull requests • Reference design mockups for new features
Create overview diagrams with repo links • Connect system components to their code • Link design components to Figma library
Press I to open integration panel
Click to select integration node
Select integration node, then click "Open" in control panel
Select integration node, then press Backspace
Located in sidenav, opens integration creation panel
Choose between GitHub and Figma
Paste GitHub or Figma URL
Opens linked resource in new tab (appears in control panel)
Visual indicator showing GitHub/Figma icon
You've mastered integration nodes! You can now:
✅ Connect diagrams to GitHub repositories and Figma designs
✅ Create living documentation that links to real resources
✅ Build clickable architecture diagrams
✅ Help teams navigate from overview to implementation
Ready to level up? Try these advanced features next:
Link strategically - Connect high-level services to repos, not every tiny component
Update regularly - Review integration links quarterly to ensure they're current
Use conventions - Establish team standards for edge labels and URL formats
Combine with templates - Create templates with pre-configured integration patterns