Diagrams as code vs conversation-led diagrams: which source of truth should win?

Diagrams as code and Slack-native diagrams are often presented as competing approaches. They solve different failure modes.

Direct answer: Use diagrams as code when the architecture artifact belongs with a repository, should change in pull requests, and benefits from diffing or generation. Use conversation-led diagrams when the main challenge is capturing review, alternatives, and decisions where the team discusses them. Combine them by keeping one stable source identity and synchronizing accepted versions deliberately.

What diagrams as code does well

Mermaid, PlantUML, Graphviz, and related formats make diagrams text-based. They can live beside code, pass through review, be versioned, and render in documentation systems. This is strong for engineer-owned artifacts tied to a repository.

The repository also provides a natural permission and audit model.

What it does not automatically solve

A source file in Git does not capture the full architecture conversation. Product managers, operations teams, and adjacent engineers may review in Slack rather than the pull request. The accepted reason for a change can remain scattered even when the file is perfectly versioned.

The artifact is maintained, but the decision provenance may still be weak.

What conversation-led diagrams do well

A Slack-native flow lowers the distance between feedback and revision. Reviewers can say "move fraud before authorization" in the existing thread, compare versions, and preserve the message that caused the change.

This is useful during design, incident follow-up, and cross-team coordination.

What it does not automatically solve

Slack should not be assumed to replace repository controls, code-linked automation, or long-term artifact portability. Teams may need exports, synchronization, and explicit authority rules.

A practical hybrid model

Use one board identity across surfaces:

1. Create and review the diagram in Slack.

1. Accept a version and record the decision.

1. Export or synchronize the Mermaid source to the relevant repository.

1. Link the pull request back to the accepted Slack version.

1. Define whether later edits begin in Slack, Git, or either with reconciliation.

Avoid independent copies that can diverge silently.

Choose authority by stage

During exploration, Slack may be the active review surface. During implementation, the repository may become authoritative for the source. The rendered current diagram can remain visible in Slack.

State this transition explicitly so contributors know where to edit.

Where Arialine fits

Arialine provides the conversation-led creation, revision, and decision history. Its source and export controls can support a repository workflow rather than compete with it.

The strongest positioning is not "replace Git." It is "capture the architecture conversation and deliver a versioned, portable diagram artifact."

FAQ

Can both Slack and Git accept edits?

Yes, but you need conflict detection and a clear merge policy. Simpler teams should choose one edit path at a time.

Which is better for compliance?

It depends on controls, retention, and audit requirements. Repository workflows are mature; Slack artifacts may still be useful review evidence.

Should non-engineers edit Mermaid source?

They can propose changes in plain language while the system or an engineer maintains valid source.