docs: add swim lane architecture diagram

[bherrmann7]

Replace simple bullet list with Mermaid sequence diagram showing:

• Four swim lanes: User, BlueBerry App, LLM Integration, Tool Layer
• Phase 1: Stack setup (client creation, MCP init, tool discovery)
• Phase 2: Request/response loop with tool execution flow
• Component table and explanation of FunctionInvocation pattern

[claude]

PR Review: docs: add swim lane architecture diagram

✅ Overall Assessment

This is an excellent documentation enhancement! The Mermaid sequence diagram significantly improves the Architecture section by providing a visual, detailed explanation of BlueBerry's operation. The changes are well-crafted and add substantial value.

---

🎯 Strengths

1. Visual Communication: The sequence diagram is far superior to the bullet list for explaining complex interactions between components
2. Comprehensive Coverage: Diagram covers both initialization (Phase 1) and runtime operation (Phase 2)
3. Clear Swim Lanes: Four logical groupings (User, BlueBerry App, LLM Integration, Tool Layer) match the architectural layers
4. Educational Value: The "Magic: Automatic Tool Execution" section demystifies the UseFunctionInvocation() pattern
5. Consistent Terminology: Component names align with the codebase (ChatSession, McpClientManager, etc.)
6. Accurate Technical Details: The diagram correctly represents the streaming flow and middleware interception

---

📝 Suggestions for Improvement

1. Minor Technical Accuracy

The sequence shows BB->>BB: Load system prompt + CLAUDE.md, but based on CLAUDE.md:138, the system actually loads from:

• ~/.bb/system-prompt.txt (default/user-customizable)
• CLAUDE.md or GEMINI.md (project-specific context)

Consider clarifying this is loading project context files rather than suggesting CLAUDE.md is always loaded.

2. Component Table Enhancement

The table could benefit from mentioning ConversationManager which handles persistence (per CLAUDE.md:43). Perhaps add a row:

| **Application** | ConversationManager | Chat history persistence to ~/.bb-history/ |

3. Diagram Formatting

The line breaks in labels like Microsoft.Extensions.AI<br/>+ OpenAI SDK render correctly in Mermaid. This is good, but ensure they display properly in GitHub's renderer (they should).

4. Typo in Original README

Line 5 of README.md has a typo: "computeing" → "computing". Not part of this PR, but worth noting for a future fix.

---

🔍 Code Quality Assessment

• Documentation Best Practices: ✅ Excellent use of visual diagrams
• Accuracy: ✅ Technically accurate representation of the architecture
• Clarity: ✅ Much clearer than the previous bullet list
• Maintainability: ✅ Mermaid diagrams are maintainable and version-controllable

---

🔒 Security & Performance

• No security concerns: Documentation-only change
• No performance impact: No code changes
• Rendering Performance: Mermaid diagrams may have slight client-side rendering overhead, but this is negligible

---

🧪 Testing Considerations

Manual Testing Needed:

• Verify Mermaid diagram renders correctly on GitHub
• Check rendering on mobile devices
• Ensure diagram is readable at different zoom levels

Recommendation: Preview the README on a fresh browser/incognito window to ensure the Mermaid syntax is correct.

---

📊 Coverage Analysis

This PR improves documentation coverage for:

• ✅ Architecture overview
• ✅ Component interactions
• ✅ Request/response flow
• ✅ Tool execution mechanism

Still undocumented (not this PR's scope, but for future consideration):

• Error handling flows
• Token tracking implementation
• Conversation persistence mechanism

---

🎯 Final Recommendation

APPROVE ✅

This PR significantly improves the README's technical depth without compromising readability. The diagram will help both users and contributors understand BlueBerry's architecture at a glance.

Suggested Next Steps:

1. Merge this PR as-is
2. Consider adding a similar diagram for error handling flows in a future PR
3. Fix the "computeing" typo in a separate commit

Great work enhancing the documentation! 🎉

[claude]

Pull Request Review: Architecture Documentation Enhancement

✅ Strengths

Excellent Documentation Improvement

• The Mermaid sequence diagram is a significant upgrade from the simple bullet list
• Visual representation makes the architecture immediately understandable
• Clear separation of swim lanes helps readers understand component boundaries
• The two-phase breakdown (Setup → Request/Response Loop) provides logical flow

Technical Accuracy

• Correctly represents the UseFunctionInvocation() middleware pattern as the key architectural component
• Accurately shows the streaming flow and how function calls are intercepted automatically
• Properly depicts the relationship between Microsoft.Extensions.AI, OpenAI SDK, and MCP SDK
• The component table provides a helpful reference

Good Narrative Structure

• "The Magic: Automatic Tool Execution" section effectively explains the key innovation
• The step-by-step breakdown makes the function invocation pattern clear
• Aligns well with the detailed architecture descriptions in CLAUDE.md

🔍 Observations & Suggestions

Minor: Mermaid Diagram Complexity

• The diagram is quite detailed, which is great for accuracy but might be overwhelming on first viewing
• Consider: Could add a simplified "30,000-foot view" diagram before this detailed one, showing just User → BlueBerry → LLM → Tools in a simple flow
• Current diagram is perfect for developers diving deep; a simpler version could help new users

Content Organization

• The old "Components" section at lines 114-120 in the original README now duplicates some information from the new component table
• Consider: You might want to remove or consolidate that old section in a future PR to avoid redundancy

Consistency Note

• PR description mentions "FunctionInvocation pattern" which is well-explained in the new text
• The diagram and explanation are consistent with the technical implementation described in CLAUDE.md

Mermaid Rendering Compatibility

• The diagram uses standard Mermaid syntax that should render correctly on GitHub
• The box grouping syntax is properly formatted
• Line break in participant labels (Microsoft.Extensions.AI<br/>+ OpenAI SDK) is valid Mermaid syntax

🎯 Code Quality Assessment

Documentation Standards: ✅ High quality

• Clear, well-structured Mermaid diagram
• Proper markdown formatting
• Good use of visual hierarchy with notes and separators

Technical Correctness: ✅ Accurate

• Correctly represents the actual architecture from the codebase
• Tool execution flow matches the ChatSession.cs implementation pattern
• Component responsibilities align with CLAUDE.md descriptions

Completeness: ✅ Thorough

• Covers both initialization and runtime phases
• Includes all major components (ChatSession, TokenTracker, MCP, SDK layers)
• Explains the critical middleware pattern that makes the system work

📝 Final Verdict

Recommendation: ✅ Approve and Merge

This is a solid documentation improvement that:

• Replaces a vague bullet list with a concrete, accurate diagram
• Helps new contributors understand the architecture quickly
• Maintains technical accuracy while improving readability
• Requires no changes to code or tests (docs-only change)

The PR achieves its stated goal of adding a swim lane architecture diagram and does so effectively. The addition of the component table and "The Magic" explanation section adds valuable context beyond just the diagram.

No blocking issues found. This is ready to merge. 🚀

---

Reviewed by Claude Code following CLAUDE.md guidelines