Parchment Programming: What is the best visual language to use for Parchment Programming? What I’m using now? …ArchiMate? …UML? …something else?

Create your own magic with Web 7.0 DIDLibOS™ / TDW AgenticOS™. Imagine the possibilities.

Copyright © 2026 Michael Herman (Bindloss, Alberta, Canada) – Creative Commons Attribution-ShareAlike 4.0 International Public License
Web 7.0™, Web 7.0 DILibOS™, TDW AgenticOS™, TDW™, Trusted Digital Web™ and Hyperonomy™ are trademarks of the Web 7.0 Foundation. All Rights Reserved.

Parchment Programming is an architecture-first software development methodology where a richly annotated visual diagram — the “parchment” — serves as the primary design document and intermediate representation (IR) that an AI coding assistant (like Claude) reads directly to generate correct, idiomatic code.

Rather than translating requirements through layers of prose specifications, the diagram itself encodes stereotypes, interface contracts, project boundaries, data models, and protocol annotations in a form that is simultaneously human-readable and AI-actionable — invented by Michael Herman, Chief Digital Officer, Web 7.0 Foundation. April 2026.

What folows is a structured comparison grounded in what Parchment Programming actually requires from a visual language.

What Parchment Programming Demands from a Visual Language

A PP visual language must do five things simultaneously:

1. Encode stereotypes that map to C# constructs («HostedService», «Repository», «Middleware»)
2. Express layered bounded contexts (project/namespace boundaries)
3. Annotate arrows with interface contracts and protocols
4. Be readable by Claude without a dedicated parser
5. Be authorable by a human architect without excessive tool friction

The Candidates

What You’re Using Now — Custom Annotated Box Diagrams

Verdict: Best starting point, needs formalization

Your DSA 0.16 diagram is already doing most things right. The color-coded regions, nested containment, labeled arrows, and protocol annotations are all PP-native. The gap is the absence of a formal stereotype vocabulary — Claude has to infer too much. A thin layer of formalization on top of your current style would make it the strongest option.

• ✅ Human-readable and visually expressive
• ✅ Claude can read it directly from an image
• ✅ Nested containment naturally maps to project boundaries
• ✅ No tool lock-in
• ❌ No enforced stereotype vocabulary (yet)
• ❌ Not machine-parseable without a defined grammar

ArchiMate

Verdict: Strong for enterprise/governance layers, wrong grain for C# code generation

ArchiMate excels at the motivation, strategy, and technology layers — it’s designed to show why a system exists and how it relates to business capabilities. Its stereotype vocabulary («ApplicationComponent», «ApplicationService», «DataObject») is too coarse and business-oriented to drive C# interface/class generation directly.

• ✅ Formal, standardized stereotype vocabulary
• ✅ Excellent layering (Business / Application / Technology)
• ✅ You already know Archi 5.8.0
• ❌ No concept of IHostedService, «Middleware», DI registration
• ❌ Stereotypes don’t map cleanly to .NET constructs
• ❌ Claude reads ArchiMate OEF XML, not the visual — loses the PP directness
• ❌ Too ceremonial for rapid iteration

UML (Component + Class Diagrams)

Verdict: Closest formal precedent, but too verbose for PP

UML Component Diagrams handle bounded contexts and interfaces well. Class diagrams handle stereotypes («interface», «abstract», «service») and are the closest existing formal language to what PP needs. The problem is UML requires two diagram types to do what PP does in one, and the tooling (Enterprise Architect, Lucidchart) adds friction.

• ✅ «stereotype» notation is native and Claude knows it well
• ✅ Interface contracts expressible formally
• ✅ Claude has deep UML training — reads it very accurately
• ❌ Component + Class diagrams needed together — no single PP view
• ❌ No built-in protocol/messaging annotation
• ❌ Verbose; loses the architecture-at-a-glance quality
• ❌ Doesn’t naturally express runtime topology (runspace pools, agent meshes)

C4 Model (Structurizr / diagrams.net)

Verdict: Best structured alternative, but prose-first not diagram-first

C4 has the right levels (Context → Container → Component → Code) and maps well to .NET projects at the Container level. But it’s DSL-authored (Structurizr) or prose-prompted — the diagram is generated, not hand-crafted. That inverts the PP authoring model.

• ✅ Container level maps naturally to .csproj boundaries
• ✅ Component level maps to interfaces/classes
• ✅ Claude knows C4 well
• ❌ Diagram-as-code means the spec is the DSL text, not the visual
• ❌ No stereotype vocabulary for .NET-specific constructs
• ❌ Loses PP’s architecture-first visual authoring

The Recommendation

Define PP-Native Notation as a thin formal layer on top of your current style

Rather than adopting an existing language wholesale, Parchment Programming should define its own visual grammar — lightweight enough to author in any diagramming tool (PowerPoint, draw.io, Visio), rich enough to be unambiguously Claude-actionable. Concretely:

Borrow from UML: the «stereotype» notation — Claude reads it natively and it maps directly to C# constructs:

«HostedService»        → : IHostedService, registered in DI
«Middleware»           → app.Use...() in Program.cs  
«Repository»           → IRepository<T> pattern
«Router»               → internal dispatch, no HTTP
«Gateway»              → external system boundary
«PSModule»             → PowerShell Loadable Brain Extension
«Factory»              → Factory pattern, DI-registered

Borrow from ArchiMate: the nested containment model for bounded contexts — color regions = project boundaries.

Keep your current style: box shapes, color coding, directional arrows with protocol labels.

Add one new convention: every arrow carries [InterfaceName] in small text alongside the protocol label.

Summary Table

Bottom line: Your current visual style is the right foundation — it just needs the «stereotype» convention from UML and the [InterfaceName] arrow annotation added as formal PP conventions. That makes it superior to any existing language for the specific job of AI-driven C#/.NET code generation.