Architecture Decisions

This section consolidates all Architecture Decision Records.

Summary Table

ADR	Decision	Status
ADR-001	Bash Tool with Help System vs. Always-On MCP	✅ Accepted
ADR-002	Agent Self-Iteration vs. Parent LLM Control	✅ Accepted
ADR-003	Local-First with Opt-In Remote	✅ Accepted
ADR-004	URL References for Rendered Diagrams	✅ Accepted (V2)
ADR-005	LiteLLM for Provider Abstraction	✅ Accepted
ADR-006	Docker-Bundled Kroki vs. Separate Service	✅ Accepted
ADR-007	Source File Direct Write	📋 Planned (V2)
ADR-008	Click as CLI Framework	✅ Accepted

ADR

Decision

Status

ADR-001

Bash Tool with Help System vs. Always-On MCP

✅ Accepted

ADR-002

Agent Self-Iteration vs. Parent LLM Control

✅ Accepted

ADR-003

Local-First with Opt-In Remote

✅ Accepted

ADR-004

URL References for Rendered Diagrams

✅ Accepted (V2)

ADR-005

LiteLLM for Provider Abstraction

✅ Accepted

ADR-006

Docker-Bundled Kroki vs. Separate Service

✅ Accepted

ADR-007

Source File Direct Write

📋 Planned (V2)

ADR-008

Click as CLI Framework

✅ Accepted

Details:

ADR-001: Bash Tool with Help System vs. Always-On MCP

Status: Accepted

Context: LLMs with computer use need diagram generation, but MCP descriptions consume context even when unused.

Decision: Primary interface is bash tool with --help. MCP mode is optional and explicitly started.

Consequences: * ✅ Context efficient: help text only loaded when needed * ✅ Works with any LLM that has bash access * ✅ MCP still available for LLMs without bash * ⚠️ Two deployment modes to maintain

Related Quality Goals: 1 Context Efficiency, 4 Autonomy

Pugh Matrix

Criterion	Always-on MCP	Bash + MCP opt-in (chosen)
Context Efficiency	- (constant context footprint)	+ (only when needed)
User Control	0	+ (user decides mode)
Implementation Effort	- (server upkeep)	0
LLM Compatibility	+ (LLM-native integration)	+ (works for bash + MCP)

Criterion

Bash tool (baseline)

Always-on MCP

Bash + MCP opt-in (chosen)

Context Efficiency

- (constant context footprint)

+ (only when needed)

User Control

+ (user decides mode)

Implementation Effort

- (server upkeep)

LLM Compatibility

+ (LLM-native integration)

+ (works for bash + MCP)

ADR-002: Agent Self-Iteration vs. Parent LLM Control

Status: Accepted

Context: Feedback loop requires multiple LLM calls. Who controls the iteration?

Decision: Agent iterates autonomously with its own LLM client.

Consequences: * ✅ Minimal context in parent conversation * ✅ Agent can optimize prompts for diagram generation * ✅ Parallel processing possible * ⚠️ Requires separate LLM API access * ⚠️ User sees less of the process (mitigated by progress output)

Related Quality Goals: 1 Context Efficiency, 4 Autonomy

Pugh Matrix

Criterion	Parent LLM controls loop (baseline)	Agent self-iteration (chosen)	Hybrid (user-stepped)
Context Usage	0	+ (minimal parent context)	- (more back-and-forth)
Reliability	0	+ (agent-optimized retries)	0
User Transparency	+ (user sees all)	0 (progress messages)	+ (full visibility)
Implementation Effort	- (complex orchestration outside agent)	0	- (more prompts, slower)

Criterion

Parent LLM controls loop (baseline)

Agent self-iteration (chosen)

Hybrid (user-stepped)

Context Usage

+ (minimal parent context)

- (more back-and-forth)

Reliability

+ (agent-optimized retries)

User Transparency

+ (user sees all)

0 (progress messages)

+ (full visibility)

Implementation Effort

- (complex orchestration outside agent)

- (more prompts, slower)

ADR-003: Local-First with Opt-In Remote

Status: Accepted

Context: Privacy concerns with sending diagram data to remote services.

Decision: * Default: Local Kroki (Fat-JAR or user-hosted) * kroki.io requires interactive confirmation * Confirmation stored in config

Consequences: * ✅ GDPR compliant by default * ✅ Works offline * ✅ Users make informed decisions * ⚠️ Initial setup more complex (Kroki download)

Related Quality Goals: 3 Privacy & Security

Pugh Matrix

Criterion	Remote by default (baseline)	Local-first, remote opt-in (chosen)	Local-only
Privacy	- (data leaves host)	+ (default local)	+ (no remote)
Offline Capability	- (requires internet)	+ (works offline)	+ (offline)
Setup Effort	+ (no local install)	0 (needs jar download)	- (must install locally)
Performance/Latency	0	+ (local latency)	- (no remote fallback)

Criterion

Remote by default (baseline)

Local-first, remote opt-in (chosen)

Local-only

Privacy

- (data leaves host)

+ (default local)

+ (no remote)

Offline Capability

- (requires internet)

+ (works offline)

+ (offline)

Setup Effort

+ (no local install)

0 (needs jar download)

- (must install locally)

Performance/Latency

+ (local latency)

- (no remote fallback)

ADR-004: URL References for Rendered Diagrams

Status: Accepted (V2 Feature)

Context: Base64-encoded images or file paths consume significant context.

Decision: MCP server mode can serve rendered diagrams via HTTP, returning short URLs.

Consequences: * ✅ Minimal context consumption * ✅ Diagrams displayable in web interfaces * ⚠️ Requires HTTP server (already present in MCP streaming mode) * ⚠️ Lifecycle management needed (when to delete?)

Related Quality Goals: 1 Context Efficiency

Pugh Matrix

Criterion	Base64 in responses (baseline)	File paths only	Short URLs (chosen)
Context Size	- (large payloads)	0	+ (tiny payload)
User Convenience	+ (inline)	0	+ (easy to preview/embed)
Complexity	0	+ (simple)	0 (reuse MCP HTTP server)
Lifecycle/Storage	- (bloats responses)	- (needs shared FS)	- (need cleanup policy)

Criterion

Base64 in responses (baseline)

File paths only

Short URLs (chosen)

Context Size

- (large payloads)

+ (tiny payload)

User Convenience

+ (inline)

+ (easy to preview/embed)

Complexity

+ (simple)

0 (reuse MCP HTTP server)

Lifecycle/Storage

- (bloats responses)

- (needs shared FS)

- (need cleanup policy)

ADR-005: LiteLLM for Provider Abstraction

Status: Accepted

Context: Need to support multiple LLM providers (Anthropic, OpenAI, local models).

Decision: Use LiteLLM as unified interface.

Consequences: * ✅ 100+ models supported * ✅ Consistent API across providers * ✅ Easy to add new providers * ⚠️ Additional dependency * ⚠️ Abstraction may hide provider-specific features

Related Quality Goals: 5 Extensibility

Pugh Matrix

Criterion	Direct provider SDKs (baseline)	LiteLLM abstraction (chosen)	Single-provider lock-in
Provider Flexibility	0 (per-provider)	+ (swap providers easily)	- (no flexibility)
Dev Velocity	- (multiple SDKs)	+ (one API surface)	+ (simplest code)
Runtime Stability	0	0	+ (fewer moving parts)
Feature Access	+ (full features)	- (some provider-specific features hidden)	- (no access to others)

Criterion

Direct provider SDKs (baseline)

LiteLLM abstraction (chosen)

Single-provider lock-in

Provider Flexibility

0 (per-provider)

+ (swap providers easily)

- (no flexibility)

Dev Velocity

- (multiple SDKs)

+ (one API surface)

+ (simplest code)

Runtime Stability

+ (fewer moving parts)

Feature Access

+ (full features)

- (some provider-specific features hidden)

- (no access to others)

ADR-006: Docker-Bundled Kroki vs. Separate Service

Status: Accepted

Context: Users want simple installation. Kroki Fat-JAR is ~80MB. Should it be included in Docker image?

Decision: Include Kroki Fat-JAR in Docker image by default. Provide slim variant without it.

Consequences: * ✅ One-command deployment: docker run diag-agent * ✅ Works offline immediately * ⚠️ Larger image size (~300MB vs ~50MB slim) * ⚠️ Longer build times

Related Quality Goals: 2 Ease of Installation, 3 Privacy & Security

Pugh Matrix

Criterion	Hosted Kroki service (baseline)	Local Docker Kroki (chosen)	Local native Kroki install
Portability	0	+ (works offline)	+ (offline)
Setup Complexity	+ (no local setup)	- (need Docker + image pull)	- (package install/maintenance)
Runtime Reliability	+ (managed uptime)	+ (self-controlled uptime)	0 (depends on host services)
Security Surface	- (network and external trust)	0 (limited to image and Docker)	- (host-level dependencies)

Criterion

Hosted Kroki service (baseline)

Local Docker Kroki (chosen)

Local native Kroki install

Portability

+ (works offline)

+ (offline)

Setup Complexity

+ (no local setup)

- (need Docker + image pull)

- (package install/maintenance)

Runtime Reliability

+ (managed uptime)

+ (self-controlled uptime)

0 (depends on host services)

Security Surface

- (network and external trust)

0 (limited to image and Docker)

- (host-level dependencies)

Alternatives Considered: * Multi-stage build with optional Fat-JAR (chosen approach) * Always download on first run (slower, requires internet) * Separate kroki container via docker-compose (more complex)

ADR-007: Source File Direct Write (V2 Feature)

Status: Planned for V2

Context: Users want agent to directly update .adoc files with generated diagrams.

Decision: Add --write-to flag that allows specifying target file and location within file.

Implementation Ideas:

diag-agent create "Component diagram" \
  --type c4 \
  --write-to architecture.adoc \
  --section "Level 2: Components" \
  --replace-marker "<!-- DIAGRAM: components -->"

Open Questions: * How to handle concurrent edits? * Should agent create section if missing? * Support for multiple diagram formats in one file?

Consequences: * ✅ Simple change tracking per run * ✅ Reduces accidental overwrites when omitted * ⚠️ Requires source files to be writable * ⚠️ No multi-user locking * ⚠️ Needs docs to set read/write flags

Related Quality Goals: 4 Autonomy

Pugh Matrix

Criterion	Always allow writes (baseline)	Explicit write-to flag (chosen)	Central locking service
Safety	- (risk of accidental edits)	+ (opt-in edits)	+ (prevents conflicts)
User Effort	+ (zero friction)	0 (requires a flag per run)	- (setup overhead)
Reliability	0	+ (predictable behavior)	+ (coordinated access)
Collaboration	- (no coordination)	0 (no extra locks)	+ (supports multi-user)

Criterion

Always allow writes (baseline)

Explicit write-to flag (chosen)

Central locking service

Safety

- (risk of accidental edits)

+ (opt-in edits)

+ (prevents conflicts)

User Effort

+ (zero friction)

0 (requires a flag per run)

- (setup overhead)

Reliability

+ (predictable behavior)

+ (coordinated access)

Collaboration

- (no coordination)

0 (no extra locks)

+ (supports multi-user)

ADR-008: Click as CLI Framework

Status: Accepted

Context: Command-line UX is the primary entry point; needs structured arguments, good help texts, and compatibility with bash-driven LLM tooling.

Decision: Use Click as the CLI framework.

Alternatives Considered: * argparse (stdlib) — stable but verbose, less friendly help output * Typer — modern and type-hint friendly, but another dependency and smaller ecosystem * docopt / fire — fast to start, but less control over UX and validation

Consequences: * ✅ Rich help/usage output with minimal boilerplate * ✅ Mature ecosystem and patterns for nested commands/options * ✅ Works well with bash and LLM-driven command execution * ⚠️ Additional dependency vs. argparse * ⚠️ Some learning curve for contributors unfamiliar with Click

Related Quality Goals: 1 Context Efficiency

Pugh Matrix

Criterion	argparse (baseline)	Click (chosen)	Typer
UX Quality	0	+ (rich help, colors, nesting)	+ (fast to code with type hints)
Dev Velocity	0	+ (concise decorators)	+ (Click-based)
Ecosystem	+ (stdlib, stable)	+ (mature extensions)	0 (smaller ecosystem)
Learning Curve	- (manual help/UX)	0 (moderate)	0 (similar to Click)

Criterion

argparse (baseline)

Click (chosen)

Typer

UX Quality

+ (rich help, colors, nesting)

+ (fast to code with type hints)

Dev Velocity

+ (concise decorators)

+ (Click-based)

Ecosystem

+ (stdlib, stable)

+ (mature extensions)

0 (smaller ecosystem)

Learning Curve

- (manual help/UX)

0 (moderate)

0 (similar to Click)

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.