Enhancement: Add architecture docs and diagrams to examples

[teilomillet]

Goal

Make examples more educational by adding architecture diagrams and deeper explanations.

Motivation

Strong examples need to teach how and why, not just what.
Companies evaluating enzu need to understand architecture decisions.

Tasks

For Each Production Example

• Architecture diagram (ASCII art or Mermaid)
  • System components
  • Data flow
  • Budget enforcement points
  • Error handling paths
• Decision log (architecture.md)
  • Why this approach?
  • Trade-offs considered
  • When to use this pattern
  • When NOT to use this pattern
• Cost analysis
  • Expected cost breakdown
  • Optimization opportunities
  • Budget allocation strategy

Example Template

Each production example should have:

examples/invoice_processing/
├── README.md           # What it does, how to run
├── architecture.md     # System design, decisions
├── cost_analysis.md    # Budget strategy, optimization
├── TUTORIAL.md         # Step-by-step walkthrough (optional)
├── pipeline.py         # Main code
└── tests/              # Tests

Documentation Standards

• README.md must include:
  • One-line description
  • Prerequisites
  • Quick start (copy/paste to run)
  • What it demonstrates
  • Expected output
• architecture.md must include:
  • Component diagram
  • Data flow diagram
  • Key decision points
  • Failure modes
• Code comments explain WHY, not WHAT
• Inline examples show actual usage

Diagram Tools

• ASCII art (for simple flows)
• Mermaid (for complex diagrams)
• Keep it simple - clarity over beauty

Acceptance Criteria

• Every production example has architecture doc
• Diagrams are clear and accurate
• New developers can understand design decisions
• Examples serve as learning material, not just code

Estimated Effort

Medium (2-3 days across all examples)