Technical Reference
This reference describes what users can do with Architecture Diagrams in Nodinite.
It is intentionally focused on available features and supported workflows, not internal implementation details.
Scope of This Reference
Use this page when you need:
- a capability overview of View mode vs Designer mode
- a practical guide to Import/Export options
- a quick map of Web API endpoint families for automation and integration
- lifecycle guidance for Draft and Active diagrams
Capability Matrix - View Mode vs Designer Mode
The matrix below compares what is available in each mode.
Legend:
- ✅ Yes: available
- ❌ No: not available
- ✅ Draft only: requires diagram state = Draft
| Capability | View mode | Designer mode |
|---|---|---|
| Interactive canvas (pan, zoom, fit) | ✅ Yes | ✅ Yes |
| Node, connector, and boundary inspectors | ✅ Yes | ✅ Yes |
| Drill-through navigation and linked diagram actions | ✅ Yes | ✅ Yes |
| Collapse/expand and focus boundaries | ✅ Yes | ✅ Yes |
| Monitoring overlays and status refresh | ✅ Yes | ✅ Yes |
| Open Mermaid companion view/modal | ✅ Yes | ✅ Yes |
| Export diagram artifacts | ✅ Yes | ✅ Yes |
| Print diagram (Export dropdown) | ✅ Yes | ✅ Yes |
| Generate runtime Dynamic diagram from log activity | ✅ Yes | ❌ No |
| Edit diagram metadata (properties) | ✅ Yes | ✅ Yes |
| Sync related diagrams and links | ✅ Yes | ❌ No |
| Create/clone/promote diagram versions | ❌ No | ✅ Yes |
| Toolbox (add new elements) | ❌ No | ✅ Draft only |
| Move and resize elements | ❌ No | ✅ Draft only |
| Create connectors from ports/handles | ❌ No | ✅ Draft only |
| Edit node, connector, and boundary properties | ❌ No | ✅ Draft only |
| Reparent elements across boundaries | ❌ No | ✅ Draft only |
| Delete elements | ❌ No | ✅ Draft only |
| Auto-arrange layout | ❌ No | ✅ Yes |
Lifecycle Matrix - Draft vs Active
Diagram lifecycle controls editing behavior.
| Lifecycle state | Intended use | Editing behavior | Typical actions |
|---|---|---|---|
| Draft | Authoring and change iteration | Full editing enabled | Add/move/resize elements, update metadata, adjust connectors, run auto-arrange |
| Active | Published reference and operational consumption | Read-only canvas behavior | Navigate, inspect, export, print, monitor, analyze runtime behavior |
| Archived | Retired diagram kept for reference | Read-only | View for historical reference |
The Diagram Lifecycle guide covers every lifecycle action in detail.
Guidance:
- Use Draft while building or revising diagrams.
- Promote to Active when the diagram should be consumed as the trusted reference.
Import Support
Import brings existing architecture definitions into a Diagram Set with preview and conflict handling.
Import workflow
- Validate source content.
- Review inferred matches and unresolved items.
- Apply with conflict resolution choices.
- Open the resulting diagram in View or Designer mode.
Import capabilities
| Capability | Support |
|---|---|
| Validation before apply | ✅ Supported |
| Conflict review and resolution | ✅ Supported |
| Entity matching and override options | ✅ Supported |
| Apply into an existing diagram set | ✅ Supported |
| Link synchronization after import | ✅ Supported |
Export Support
Export supports both visual sharing and source-oriented interchange.
A single diagram and a whole Diagram Set offer the same six formats. Export and Sharing is the one home for the format details, endpoints, and embedding options.
| Format | Single diagram | Diagram set |
|---|---|---|
SVG (.svg) |
✅ Yes | ✅ Yes, as a ZIP (state filter modal first) |
PNG (.png) |
✅ Yes | ✅ Yes, as a ZIP (state filter modal first) |
Mermaid (.md) |
✅ Yes | ✅ Yes, as a ZIP |
Structurizr DSL (.dsl) |
✅ Yes | ✅ Yes, as a ZIP (labelled DSL) |
PlantUML (.puml) |
✅ Yes | ✅ Yes, as a ZIP |
Draw.io (.drawio) |
✅ Yes | ✅ Yes, as a ZIP |
The Designer and the diagram Detail page add a Print diagram item above the formats. Import accepts four of these as source markup: Mermaid, PlantUML, Structurizr DSL, and Draw.io XML.
Web API Reference (User-Facing Families)
The Architecture Diagram APIs in the Nodinite Web API are organized into endpoint families. Use the Web API's OpenAPI documentation in your environment for complete request/response contracts.
Core families
| Endpoint family | Purpose |
|---|---|
/api/C4Diagrams |
Diagram CRUD, lifecycle actions, view-mode data, dynamic generation, export, links, tags, metadata |
/api/C4DiagramSets |
Diagram set CRUD, set-level operations, batch exports |
/api/c4diagrams/import |
Import validation and apply |
/api/C4Diagrams/{diagramId}/nodes/{nodeId}/articles |
Node-to-article linking and candidate discovery |
Common automation scenarios
| Scenario | Typical API path |
|---|---|
| Create and maintain diagrams | C4Diagrams + C4DiagramSets |
| Promote draft to active | C4Diagrams lifecycle endpoints |
| Validate and apply import content | c4diagrams/import/validate and c4diagrams/import/apply |
| Export single diagrams or full sets | C4Diagrams export endpoints and C4DiagramSets ZIP export endpoints |
| Synchronize and maintain cross-diagram links | C4Diagrams link endpoints |
Practical Recommendations
- Use View mode for analysis, sharing, and operations-facing usage.
- Use Designer mode for controlled authoring in Draft state.
- Use Import Validate before Apply to reduce correction cycles.
- Standardize on one export format per audience:
- SVG for technical documentation
- PNG for quick sharing
- Mermaid, Structurizr DSL, PlantUML, or Draw.io for interchange workflows
- Treat Active diagrams as the canonical reference for stakeholders.