Skip to content

Feat: Add C4 PlantUML architecture document derivation#412

Merged
tninja merged 4 commits into
mainfrom
derive-c4-plantuml-doc
Jun 27, 2026
Merged

Feat: Add C4 PlantUML architecture document derivation#412
tninja merged 4 commits into
mainfrom
derive-c4-plantuml-doc

Conversation

@tninja

@tninja tninja commented Jun 27, 2026

Copy link
Copy Markdown
Owner

Summary

Add a new architecture document type that asks the current AI backend to derive a C4-style architecture overview document for an existing repository.

The generated document is intended to be an architecture reading guide rather than just a collection of diagrams.

What's Included

  • New command: ai-code-derive-c4-plantuml
  • New menu entry under ai-code-derive-architecture-document
  • Creates .ai.code.files/architecture/c4-overview.org
  • Generates prompts for:
    • System Context diagram
    • Container diagram
    • Component diagram
    • Important runtime flows (sequence diagrams when helpful)
    • Repository summary and glossary
    • Key architectural decisions
    • Open questions and source evidence

The prompt explicitly instructs the AI to:

  • Use Org-mode with PlantUML Babel blocks.
  • Use PlantUML C4 includes when appropriate.
  • Avoid inventing architecture that is not supported by the repository.
  • Mark uncertainty explicitly.
  • Include file: Org links back to source evidence.

Refactoring

Introduce ai-code--ensure-architecture-document-file to reduce duplication between DDD, Test Context, and the new C4 document generation flow.

Motivation

As repositories grow, contributors and AI coding agents benefit from having an architecture document that explains:

  1. What the repository does.
  2. How major pieces fit together.
  3. Which assumptions are inferred versus confirmed.
  4. Where to look in the code for evidence.

This feature moves the project toward AI-assisted Architecture-as-Code for existing repositories.

Future Ideas

  • Refresh C4 documents from recent git diffs.
  • Auto-export PlantUML diagrams to SVG.
  • Add commands to open or regenerate architecture documents.

@tninja tninja changed the title Add C4 PlantUML architecture document derivation Feat: Add C4 PlantUML architecture document derivation Jun 27, 2026
@tninja tninja merged commit e671162 into main Jun 27, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant