GitHub Copilot for Diagrams, Humans for Architectural Decisions 🗺��

[nikhil-thampi]

Diagrams are one of those things every team agrees are valuable—until it is time to create or update them.

In reality, most diagrams are built late, updated inconsistently, and trusted only cautiously. The problem is not that teams do not care. The problem is that the context needed to build a useful diagram is usually scattered across code, requirements, APIs, infrastructure, documentation, and tribal knowledge. Copilot can help with the mechanical part by drafting Mermaid markup, while GitHub can render that markup in the same places where teams already discuss and document their work. (docs.github.com)

I’m writing this because many of the banking customers I work with operate in complex, multi-stack environments where diagrams are essential but hard to create and maintain. This article builds on the official GitHub guidance, but with a different objective: not just how to generate Mermaid syntax, but how teams across different personas can use GitHub Copilot more practically without confusing acceleration with architectural authority.

That is where GitHub Copilot can help.

Not as an architect.
Not as the source of truth.
But as a diagram accelerator.

Used well, GitHub Copilot can help teams turn project context into first-pass visual documentation much faster. Ask mode helps when the raw material already exists and the team needs a draft. Plan mode helps when the real question is scope, audience, and level of detail. Agent mode helps when that draft needs to become maintained documentation in the repository rather than a one-off chat output. GitHub’s product guidance maps well to that workflow. (docs.github.com)

Why teams struggle with diagrams

Most teams do not struggle because diagrams are unimportant. They struggle because diagrams are hard to keep current.

The context needed to create them is often spread across too many places. By the time someone gathers enough information to create a meaningful system view, the implementation may already have changed.

And even when teams agree that a diagram is needed, they are often not looking for the same thing. Developers may want sequence diagrams or component-level views to understand implementation flow. Architects may want higher-level system boundaries and dependencies. Business analysts may need process or workflow diagrams that connect technical behavior to business intent. Operations and support teams may care more about runtime dependencies and failure paths.

The challenge is not just generating a diagram—it is generating the right kind of diagram for the right persona. That is why the planning step matters so much: before anyone asks Copilot to draw anything, the team still needs to decide what view would actually be useful. (docs.github.com)

Where GitHub Copilot helps most

GitHub Copilot is most useful when teams need a usable first draft. Instead of translating source files, requirements, or schemas into a diagram manually, teams can use Copilot to get to a workable starting point quickly. The value is not just speed. A draft in the repo is easier to review, challenge, and improve than a diagram that only exists in someone’s head. (docs.github.com)

A simple way to think about the workflow

flowchart LR
    A[Project Context] --> B[Ask Mode<br/>Generate first draft]
    B --> C[Plan Mode<br/>Clarify scope and audience]
    C --> D[Agent Mode<br/>Update docs in repo]
    D --> E[Human Review<br/>Validate accuracy and intent]

    classDef input fill:#EAF3FF,stroke:#4A90E2,color:#1F2D3D,stroke-width:1px;
    classDef copilot fill:#EAFBF0,stroke:#2DA44E,color:#1F2D3D,stroke-width:1px;
    classDef human fill:#FFF4E5,stroke:#FB8C00,color:#1F2D3D,stroke-width:1px;

    class A input;
    class B,C,D copilot;
    class E human;

Loading

The point is simple: Copilot can accelerate the workflow, but people still need to validate the result.

Types of diagrams Copilot can accelerate

Copilot is especially useful when the source material is reasonably structured.

For example:

• architecture diagrams for digital banking platforms, payment services, fraud engines, and customer notification flows
• sequence diagrams for journeys such as login, payment initiation, transaction screening, or exception handling
• flowcharts for business processes such as onboarding, approval routing, or dispute handling
• entity relationship diagrams from account, customer, transaction, and ledger schemas
• integration diagrams for connections to payment rails, identity providers, core banking systems, and compliance services
• deployment diagrams from environment configuration, platform boundaries, and operational dependencies

GitHub’s modernization tutorial shows the same broader pattern: the better the source context, the more useful the first-pass diagram. (docs.github.com)

Here is a simple example of the kind of high-level architecture view a banking team could generate and refine:

flowchart LR
    U[Customer] --> W[Digital Banking App]
    W --> S[Payments Service]
    S --> F[Fraud Decision Engine]
    S --> D[(Accounts and Transactions DB)]
    S --> P[Payment Rail / Gateway]
    S --> N[Notification Service]

    classDef user fill:#EAF3FF,stroke:#4A90E2,color:#1F2D3D,stroke-width:1px;
    classDef app fill:#EAFBF0,stroke:#2DA44E,color:#1F2D3D,stroke-width:1px;
    classDef store fill:#F2F4F7,stroke:#667085,color:#1F2D3D,stroke-width:1px;
    classDef external fill:#FFF4E5,stroke:#FB8C00,color:#1F2D3D,stroke-width:1px;

    class U user;
    class W,S,F app;
    class D store;
    class P,N external;

Loading

That kind of output is often enough to start a design conversation, improve onboarding for a new engineer on a payments team, or document a workflow that previously lived only in people’s heads.

Ask, Plan, and Agent modes: where each fits

One of the easiest ways to get more value from Copilot is to stop treating all diagram work as a single prompt.

Ask mode is the quickest route from source material to a first visual draft. This is where teams can ask Copilot to summarize a flow, sketch Mermaid markup, simplify an existing diagram, or explain a technical interaction in plain English. (docs.github.com)

Plan mode is useful before diagram generation. Instead of jumping straight to Mermaid, teams can use Copilot to think through which diagram type best fits the goal, what belongs in scope, which artifacts deserve the most trust, and which assumptions should be made explicit. (docs.github.com)

Agent mode becomes valuable once the task shifts from “draw something” to “maintain the documentation.” That makes it relevant for creating or updating docs pages, refreshing Mermaid diagrams after code changes, and turning a draft into something a team can review in normal repository workflows. (docs.github.com)

In short: Ask helps you draft, Plan helps you shape, and Agent helps you operationalize.

Tip

A note on model choice: For more complex diagram tasks—especially when you want Copilot to reason across multiple files, handle ambiguity more carefully, or identify assumptions before producing a diagram—it may help to choose a model that is stronger at deeper reasoning. That said, better diagrams usually depend more on strong grounding than on prompt cleverness. In practice, a well-scoped request against the right code, schema, API contract, requirements, or documentation usually matters more than reaching for the most advanced model available. Copilot can also choose a model automatically, which may be enough for many day-to-day cases. (docs.github.com)

Banking prompt examples readers can adapt

Below are three banking-oriented prompts readers can adapt to their own repositories.

High-level architecture diagram

Review this repository and generate a Mermaid component diagram showing the major services involved in customer channels, payments, fraud checks, data storage, and external banking integrations. Keep it high level and suitable for an architecture overview. Clearly label anything that is inferred rather than explicit.

Sequence diagram

Analyze the code involved in this payment journey and generate a Mermaid sequence diagram showing the interaction between the customer channel, application services, fraud or compliance checks, downstream payment integration, and data store. Include visible validation, approval, and error-handling steps where possible.

Business flowchart

Convert these onboarding or dispute-management requirements into a Mermaid flowchart. Show the main flow, decision points, exception paths, manual review steps, and approvals. Keep the result readable for both technical and non-technical stakeholders.

For Plan mode, a useful precursor prompt is:

Before generating the diagram, help me decide which diagram type fits this repository best for onboarding a new engineer joining our payments platform team. Suggest what should be in scope, what should be out of scope, and what artifacts I should use as the source of truth.

For Agent mode, the next step could be:

Create a new documentation page in the docs folder that includes a Mermaid architecture diagram for this project and a short explanation of the main components, payment dependencies, control points, and external systems. Clearly note assumptions that require human validation.

A simple sequence example

Here is a basic example of the kind of sequence view Copilot can help produce from code or workflow context in a banking scenario:

sequenceDiagram
    actor Customer
    participant App as Digital Banking App
    participant PaymentService
    participant FraudService
    participant Database
    participant Gateway as Payment Gateway

    Customer->>App: Initiate payment
    App->>PaymentService: Submit payment request
    PaymentService->>FraudService: Screen transaction
    FraudService->>Database: Retrieve account and risk context
    Database-->>FraudService: Customer and transaction data
    FraudService-->>PaymentService: Decision result
    PaymentService->>Gateway: Send approved payment
    Gateway-->>PaymentService: Payment status
    PaymentService-->>App: Confirmation or failure
    App-->>Customer: Show payment result

Loading

Even a simple sequence like this can be useful for onboarding, troubleshooting, or architecture discussions.

Why Copilot is not a replacement for architectural thinking

This is the most important point.

A generated diagram can look polished and still be wrong.

Copilot works from the context it can access. It does not inherently know business intent, undocumented exceptions, ownership boundaries, operational realities, regulatory constraints, or the trade-offs behind architectural decisions. The official guidance is useful for showing what Copilot can produce, but that is not the same thing as authoritative architecture. (docs.github.com)

It may simplify too much.
It may infer relationships that are not guaranteed.
It may miss the nuance that matters most.

That is why Copilot should be treated as a tool for acceleration, not authority.

Architectural thinking still belongs to humans:

• deciding the right level of abstraction
• validating system boundaries
• separating current state from future state
• checking what is explicit versus inferred
• confirming whether the diagram is actually useful for its audience

Copilot can help produce the diagram. Humans remain responsible for whether the diagram is correct.

A practical workflow for teams

The most effective workflow is usually:

1. start with the right source material
2. use Plan mode to define scope and audience
3. use Ask mode to generate a first-pass Mermaid diagram
4. ask Copilot to identify assumptions and ambiguities
5. use Agent mode to add or update the diagram in repo documentation
6. review the result with the right humans

That workflow fits the platform well: Mermaid can live alongside the rest of the project’s Markdown documentation, Copilot can help draft the markup, and agent workflows can move the result into normal review paths. (docs.github.com)

Final thought

The real value of GitHub Copilot in diagram generation is not perfect visuals. It is faster movement from scattered project context to usable visual documentation. Used well, Copilot can help teams plan, draft, and maintain diagrams, but judgment, validation, trade-offs, and intent still stay where they should: with humans.

Quick links

• Creating diagrams with GitHub Copilot. (docs.github.com)
• Creating Mermaid diagrams in GitHub Markdown. (docs.github.com)
• GitHub Copilot features overview. (docs.github.com)
• Supported AI models in GitHub Copilot. (docs.github.com)
• About Copilot auto model selection. (docs.github.com)

[code-with-kishan]

This is a really good write-up — especially the part about “Copilot as an accelerator, not an architect.”

I think the workflow you described (Ask → Plan → Agent → Human review) is actually the most practical way to use Copilot for diagrams right now.

A couple of thoughts from my side:

1. The biggest value is reducing friction, not replacing thinking
You nailed this. The hardest part of diagrams isn’t drawing boxes — it’s:

• deciding scope
• choosing the right abstraction level
• aligning with the audience

Copilot helps you start, but it doesn’t solve those decisions.

---

2. Plan mode is underrated here
Most people jump straight into “generate diagram,” but your point about using Plan mode first is important.

Even a simple step like:

“What diagram type fits this repo and why?”

can prevent a lot of messy or misleading diagrams later.

---

3. The “first draft in repo” idea is key
Having a rough diagram in the repo (even if imperfect) is way better than:

• no documentation
• or diagrams stuck in someone’s head

It creates something the team can actually review and improve.

---

4. Where things can still go wrong
In practice, I’ve seen Copilot-generated diagrams:

• assume relationships that don’t exist
• miss async flows or edge cases
• oversimplify critical components

So the “human validation” step you mentioned is not optional — it’s essential.

---

5. One small improvement suggestion
You could maybe emphasize this even more:

👉 “Good diagrams depend more on good input context than on the model itself.”

That’s something a lot of people miss — they try better prompts instead of better source material.

---

Overall
This is a very practical and realistic take. It avoids the usual “AI will design everything” hype and focuses on how teams actually work.

Definitely useful for anyone trying to use Copilot in real projects 👍

[nikhil-thampi]

Thanks for sharing your detailed thoughts! It means a lot and special thanks for feedback! ❤️