Feat: Add C4 PlantUML architecture document derivation

HISTORY.org

@@ -2,6 +2,7 @@
 * Release history
 
 ** Main branch change
+- Feat: Add C4 PlantUML architecture document derivation
 - Chore: Support optional editor context in GitHub issue investigation
 - Feat: improve gptel sync request timeout, truncation, and retry
 

README.org

@@ -157,7 +157,7 @@ Enable installation of packages from MELPA by adding an entry to package-archive
   - When a visible AI session buffer already exists, prompts can be routed to that session directly instead of opening a new one.
 - *Agile Development Workflows*: Use the refactoring navigator (`r`), the guided TDD cycle (`t`), and the pull/review diff helper (`v`) to keep AI-assisted work aligned with agile best practices. Prompt authoring is first-class through quick access to the prompt file (`p`), build/test helper (`b`), and AI-assisted shell/file execution (`!`). In prompt files, send the current block with `C-c C-c`.
 - *Productivity & Debugging Utilities*: Initialize project navigation assets (`.`), investigate exceptions (`e`), debug Emacs runtime issues (`d`), auto-fix Flycheck issues in scope (`f`), copy or open file paths formatted for prompts (`k`, `o`), generate MCP inspector commands (`m`), capture session notes straight into Org (`n`), search notes with AI (`/`), dictate prompts with speech-to-text (`:`), and toggle desktop notifications (`N`) to get alerted when AI responses are ready in background sessions.
-- *Repo Guardrails Capture*: Derive a concise architecture guardrails file for the current repository with `C-c a A`. The command creates or updates `.ai.code.files/architecture/guardrails.org` so future AI coding sessions can reuse practical module boundaries, dependency rules, and validation expectations.
+- *Architecture Document Generation*: Derive practical architecture documents for the current repository with `C-c a A` (`ai-code-derive-architecture-document`). The command can generate architecture guardrails, a C4 PlantUML overview, a lightweight DDD context, or a test context document under `.ai.code.files/architecture/` so future AI coding sessions can reuse module boundaries, dependency rules, runtime flows, and validation expectations. See [[./docs/architecture/c4-overview.org][the C4 architecture overview for this repository]] for an example C4 diagram guide.
 - *Seamless Prompt Management*: Open the prompt file via `ai-code-open-prompt-file` (stored under `.ai.code.files/.ai.code.prompt.org` by default), send regions with `ai-code-prompt-send-block`, and reuse prompt snippets via `yasnippet` to keep conversations organized.
 - *Interactive Chat & Context Tools*: Dedicated buffers hold long-running chats, automatically enriched with file paths, diffs, and history from Magit or Git commands for richer AI responses.
 - *AI-Assisted Bash Commands*: From Dired, shell, eshell, or vterm, run `C-c a !` and type natural-language commands prefixed with `:` (e.g., `:count lines of python code recursively`); the tool generates the shell command for review and executes it in a compile buffer.

ai-code-doc.el

@@ -22,9 +22,10 @@
 
 (defconst ai-code--architecture-document-choices
   '(("Derive Architecture Guardrails" . ai-code-derive-architecture-guardrails)
+    ("Derive C4 PlantUML Architecture Document" . ai-code-derive-c4-plantuml)
     ("Derive DDD Context for Repo" . ai-code-derive-ddd-context)
     ("Derive Test Context Document" . ai-code-derive-test-context))
-  "Choices for `ai-code-derive-architecture-document`.")
+  "Choices for `ai-code-derive-architecture-document'.")
 
 ;;;###autoload
 (defun ai-code-derive-architecture-document ()
@@ -56,6 +57,10 @@ Default value is English."
   ".ai.code.files/architecture/test-context.org"
   "Repository-relative path for the derived Test Context document.")
 
+(defconst ai-code-c4-plantuml-output-relative-path
+  ".ai.code.files/architecture/c4-overview.org"
+  "Repository-relative path for the derived C4 PlantUML architecture document.")
+
 (defconst ai-code-file--architecture-guardrails-file-name
   "guardrails.org"
   "File name for derived architecture guardrails.")
@@ -85,6 +90,16 @@ Default value is English."
              "\n")
   "Initial Org template for architecture guardrails.")
 
+(defun ai-code--ensure-architecture-document-file (file-name)
+  "Ensure an architecture document named FILE-NAME exists and return its path."
+  (let* ((files-dir (ai-code--ensure-files-directory))
+         (architecture-dir (expand-file-name "architecture" files-dir))
+         (target-file (expand-file-name file-name architecture-dir)))
+    (make-directory architecture-dir t)
+    (unless (file-exists-p target-file)
+      (write-region "" nil target-file nil 'silent))
+    target-file))
+
 (defun ai-code--derive-ddd-context-prompt (git-root)
   "Build and return a formatted DDD context derivation prompt string for GIT-ROOT."
   (concat
@@ -131,6 +146,51 @@ Default value is English."
    "** Coverage Gaps & Actionable Testing Ideas\n"
    "** Notes and Uncertainties"))
 
+(defun ai-code--derive-c4-plantuml-prompt (git-root)
+  "Build and return a C4 PlantUML architecture document prompt for GIT-ROOT."
+  (concat
+   "Derive a C4-style architecture overview document for this existing repository.\n"
+   "Generate the document as Org mode and embed PlantUML C4 diagrams in Org Babel source blocks.\n"
+   "Create or update the document as an architecture reading guide, not just a collection of diagrams.\n"
+   "Infer architecture from actual source files, tests, README files, package metadata, scripts, and configuration.\n"
+   "Do not invent external systems, deployment topology, runtime dependencies, users, or protocols that are not supported by code or documentation.\n"
+   "Mark uncertain boundaries, relationships, and naming choices explicitly.\n"
+   "Prefer fewer boxes and clearer relationships over large, noisy diagrams.\n"
+   "Use C4 only as an architectural draft for human review.\n"
+   "When referencing any code file, folder, module, function, variable, or type, you MUST provide a relative Org-mode link in the format [[file:../../path/to/file::symbol_or_line][description_text]] pointing to its definition in the codebase (relative to the .ai.code.files/architecture/ output directory).\n"
+   "For every diagram, include explanatory notes after the PlantUML block that summarize what the diagram shows and what remains uncertain.\n"
+   "Use Org Babel blocks like #+begin_src plantuml :file c4-context.svg :exports both and include @startuml / @enduml inside each block.\n"
+   "Use PlantUML C4 includes such as !include <C4/C4_Context>, !include <C4/C4_Container>, and !include <C4/C4_Component> when appropriate.\n"
+   (format "Repository root: %s\n" git-root)
+   (format "Create or update the Org file at %s.\n\n"
+            ai-code-c4-plantuml-output-relative-path)
+   "Use this Org structure:\n"
+   "#+TITLE: C4 Architecture Overview\n\n"
+   "* Purpose\n"
+   "Explain what this generated architecture guide is for and what it does not prove.\n"
+   "* Confidence and Assumptions\n"
+   "List confidence level, source inputs, assumptions, and unverified areas.\n"
+   "* Repository Summary\n"
+   "Summarize the repository responsibilities in a few practical bullets.\n"
+   "* Glossary\n"
+   "Define terms used in the diagrams.\n"
+   "* How to Read These Diagrams\n"
+   "Explain the intended reading order: System Context, Container, Component, then runtime flows.\n"
+   "* System Context\n"
+   "Include a C4 System Context PlantUML Babel block and notes.\n"
+   "* Container View\n"
+   "Include a C4 Container PlantUML Babel block and notes. Treat containers as major deployable or logical units, not necessarily Docker containers.\n"
+   "* Component View\n"
+   "Include one focused C4 Component PlantUML Babel block for the most important container or module, and notes.\n"
+   "* Important Runtime Flows\n"
+   "Describe 1-3 important flows. Include a PlantUML sequence diagram when it helps.\n"
+   "* Key Architectural Decisions\n"
+   "List practical design choices inferred from the code and docs.\n"
+   "* Open Questions\n"
+   "List areas that need human confirmation.\n"
+   "* Source Evidence\n"
+   "Provide a table mapping important claims to Org links pointing at source evidence."))
+
 (defun ai-code--architecture-guardrails-relative-path ()
   "Return the repo-relative path for the architecture guardrails file."
   (concat ai-code-files-dir-name "/"
@@ -207,17 +267,12 @@ Default value is English."
 ;;;###autoload
 (defun ai-code-derive-ddd-context ()
   "Ask AI to derive a lightweight DDD context document for the current repo.
-The target Org file under `.ai.code.files/architecture/` is created if it does
+The target Org file under `.ai.code.files/architecture/' is created if it does
 not already exist, so the backend has a concrete document to create or update."
   (interactive)
   (let* ((git-root (or (ai-code--git-root)
-                       (user-error "Not inside a Git repository")))
-         (files-dir (ai-code--ensure-files-directory))
-         (architecture-dir (expand-file-name "architecture" files-dir))
-         (target-file (expand-file-name "domain-context.org" architecture-dir)))
-    (make-directory architecture-dir t)
-    (unless (file-exists-p target-file)
-      (write-region "" nil target-file nil 'silent))
+                       (user-error "Not inside a Git repository"))))
+    (ai-code--ensure-architecture-document-file "domain-context.org")
     (let* ((base-prompt
             (concat (ai-code--derive-ddd-context-prompt git-root)
                     (or (ai-code--format-repo-context-info) "")))
@@ -230,17 +285,12 @@ not already exist, so the backend has a concrete document to create or update."
 ;;;###autoload
 (defun ai-code-derive-test-context ()
   "Ask AI to derive a lightweight Test Context document for the current repo.
-The target Org file under `.ai.code.files/architecture/` is created if it does
+The target Org file under `.ai.code.files/architecture/' is created if it does
 not already exist, so the backend has a concrete document to create or update."
   (interactive)
   (let* ((git-root (or (ai-code--git-root)
-                       (user-error "Not inside a Git repository")))
-         (files-dir (ai-code--ensure-files-directory))
-         (architecture-dir (expand-file-name "architecture" files-dir))
-         (target-file (expand-file-name "test-context.org" architecture-dir)))
-    (make-directory architecture-dir t)
-    (unless (file-exists-p target-file)
-      (write-region "" nil target-file nil 'silent))
+                       (user-error "Not inside a Git repository"))))
+    (ai-code--ensure-architecture-document-file "test-context.org")
     (let* ((base-prompt
             (concat (ai-code--derive-test-context-prompt git-root)
                     (or (ai-code--format-repo-context-info) "")))
@@ -250,5 +300,23 @@ not already exist, so the backend has a concrete document to create or update."
       (when final-prompt
         (ai-code--insert-prompt final-prompt)))))
 
+;;;###autoload
+(defun ai-code-derive-c4-plantuml ()
+  "Ask AI to derive a C4 PlantUML architecture document for the current repo.
+The target Org file under `.ai.code.files/architecture/' is created if it does
+not already exist, so the backend has a concrete document to create or update."
+  (interactive)
+  (let* ((git-root (or (ai-code--git-root)
+                       (user-error "Not inside a Git repository"))))
+    (ai-code--ensure-architecture-document-file "c4-overview.org")
+    (let* ((base-prompt
+            (concat (ai-code--derive-c4-plantuml-prompt git-root)
+                    (or (ai-code--format-repo-context-info) "")))
+           (initial-prompt (ai-code--append-document-language base-prompt))
+           (final-prompt (ai-code-plain-read-string "Derive C4 PlantUML prompt: "
+                                                    initial-prompt)))
+      (when final-prompt
+        (ai-code--insert-prompt final-prompt)))))
+
 (provide 'ai-code-doc)
 ;;; ai-code-doc.el ends here