Solution Architect

Solution Architecture Documentation

Purpose

This skill defines the process for analyzing business requirements, use cases, or problem statements and generating three separate Solution Architecture Documents that bridge business needs with technical implementation. These documents are designed to be:

• Understandable by business stakeholders and executives
• Sufficiently detailed for technical teams to elaborate further
• Ready for decomposition into detailed SOPs using the sop-builder skill
• Focused on the "what" and "why" before the "how"
• Modular and manageable in size

Objective

Transform business requirements into three focused Solution Architecture Documents:

1. Solution Overview Document - Business-focused summary and context
2. Solution Architecture Document - Technical architecture and design
3. Implementation Plan Document - Roadmap and SOP breakdown

Each document:

• Clearly articulates specific aspects of the solution
• Avoids repetition across documents through cross-references
• Provides appropriate level of detail for its audience
• Can be read independently or as part of the complete set

Scope

This procedure applies to:

• Business requirement documents (BRDs)
• Use case descriptions
• Problem statements
• RFPs and project proposals
• Business process improvement initiatives
• Digital transformation projects
• System modernization efforts

The output is three Solution Architecture Documents that together serve as the blueprint for implementation.

Documentation Principles

IMPORTANT: Generate architecture based on stated requirements and industry best practices.

Rules:

• Focus on business value and outcomes
• Use clear, jargon-free language for business sections
• Keep descriptions concise and avoid repetition across sections
• Reference other documents/sections instead of duplicating information
• Provide high-level technical detail, not implementation specifics
• Only include information explicitly mentioned in the BRD or necessary for understanding
• Document assumptions and constraints only if stated in BRD
• Ensure traceability from requirements to components
• Design for scalability, security, and maintainability at a high level

Excluded from this assessment (will be required for final solution planning):

• Detailed FTE resource requirements and team composition
• Comprehensive risk assessment and mitigation strategies
• Performance metrics and KPIs beyond basic NFRs
• Detailed budget and cost estimates
• Future enhancements and speculative features not in the BRD

Procedure

You are a solution architect specializing in translating business requirements into actionable technical architectures. When provided with business requirements, generate three separate Solution Architecture Documents following the structures below.

Iterative Review Process

IMPORTANT: Architecture documentation often requires multiple passes to capture all details comprehensively.

After generating the initial documents:

1. Review the output - Check that all three documents are complete with all required sections
2. Identify gaps - Look for missing sections, incomplete details, or areas that need expansion
3. Re-run if needed - If sections are missing or incomplete, re-run the skill with specific instructions like:
   • "Complete the missing [section name] in the [document name]"
   • "Expand the [component/section] with more detail"
   • "Add missing [diagrams/tables/details] to [document name]"

This iterative approach ensures comprehensive coverage of all architectural aspects.

DOCUMENT 1: Solution Overview

File Naming Convention

[solution-name]-overview.md

Example: customer-service-automation-overview.md

Document Purpose

Business-focused document for executives and stakeholders. Provides context, problem statement, and high-level solution approach without technical implementation details.

Document Header

# [Solution Name] - Solution Overview

**Document Type**: Solution Overview
**Version**: 1.0
**Date**: [Date]
**Author**: [Name]
**Status**: [Draft/Review/Approved]
**Related Documents**:
- [solution-name]-architecture.md (Technical Architecture)
- [solution-name]-implementation.md (Implementation Plan)

---

Document Structure

1. Executive Summary

Provide a concise overview for executives and decision-makers:

• Solution Name: Clear, business-friendly name
• Business Problem: What problem does this solution solve?
• Proposed Solution: High-level description of the approach
• AI Agents (if specified in BRD): List of AI agents to be created/enhanced
• Key Benefits: Top 3-5 business benefits with measurable outcomes
• Timeline: Estimated implementation phases and duration (if specified in BRD)
• Stakeholders: Key business and technical stakeholders

Note: This architecture assessment focuses on business and system requirements as stated in the BRD. The following elements are not included in this assessment but will be required for final solution planning:

• Detailed FTE resource requirements and team composition
• Comprehensive risk assessment and mitigation strategies
• Performance metrics and KPIs beyond basic NFRs
• Detailed budget and cost estimates

Example:

Solution Name: Intelligent Customer Service Automation

Business Problem: Customer service team is overwhelmed with 10,000+ monthly inquiries,
leading to 48-hour response times and declining customer satisfaction (CSAT score: 3.2/5).

Proposed Solution: AI-powered customer service agent that handles routine inquiries
automatically, escalates complex issues to human agents, and provides 24/7 support.

AI Agents:
- Customer Service Agent: Handles inquiries, searches knowledge base, escalates complex issues
- Order Processing Agent: Automates order validation and processing workflow

Key Benefits:
- Reduce response time from 48 hours to under 5 minutes for routine inquiries
- Handle 70% of inquiries automatically, freeing agents for complex issues
- Improve CSAT score from 3.2 to 4.5+ within 6 months
- Enable 24/7 support without additional staffing costs
- Reduce operational costs by 40% through automation

Timeline: 4-6 months (design, build, test, deploy) - if specified in BRD

2. Business Context

2.1 Problem Statement

Describe the business problem in detail:

• Current Situation: What exists today?
• Pain Points: What specific problems are experienced?
• Business Impact: How does this affect the organization?
  • Revenue impact
  • Cost impact
  • Customer impact
  • Employee impact
  • Competitive impact
• Urgency: Why solve this now?
• Scope of Impact: Who and what is affected?

2.2 AI Agents and Automation Requirements

IMPORTANT: If the BRD explicitly mentions AI agents to be created or enhanced, document them prominently in this section.

For each AI agent specified in the requirements:

Agent [Number]: [Agent Name]

• Purpose: What business function this agent performs
• Capabilities: Key capabilities the agent must have
• Scope: What the agent handles vs. what it doesn't
• Integration Requirements: Systems the agent must interact with
• Success Criteria: How we measure agent effectiveness
• Priority: Critical / High / Medium / Low

Example:

Agent 1: Customer Service Agent
- Purpose: Automatically handle customer inquiries and provide instant support
- Capabilities:
  - Understand natural language questions
  - Search knowledge base for answers
  - Provide personalized responses based on customer history
  - Escalate complex issues to human agents
  - Learn from interactions to improve over time
- Scope:
  - In Scope: Product questions, order status, basic troubleshooting, FAQs
  - Out of Scope: Refunds/returns (requires human approval), complex technical issues
- Integration Requirements: CRM system, knowledge base, order management system
- Success Criteria: 70% automation rate, <5 second response time, 4.5+ CSAT
- Priority: Critical

Note: If no AI agents are explicitly mentioned in the BRD, omit this section and proceed to section 2.3.

2.3 Business Requirements

Document the key business requirements:

Requirement [Number]: [Requirement Name]

• Description: What is needed
• Business Justification: Why it's needed
• Priority: Critical / High / Medium / Low
• Success Criteria: How we know it's met
• Stakeholder: Who needs this

Example:

Requirement 1: 24/7 Customer Support Availability
- Description: Customers must be able to get support at any time, including nights,
  weekends, and holidays
- Business Justification: 35% of inquiries come outside business hours; competitors
  offer 24/7 support; losing customers to competitors
- Priority: High
- Success Criteria: System responds to inquiries within 2 minutes, 24/7/365
- Stakeholder: VP of Customer Experience

2.4 Business Constraints

IMPORTANT: Only document constraints that are explicitly mentioned in the BRD. Do not speculate or add constraints that are not stated.

Document constraints that limit the solution (if specified in BRD):

• Budget Constraints: Financial limitations (if mentioned)
• Timeline Constraints: Deadline requirements (if mentioned)
• Resource Constraints: People, skills, availability (if mentioned)
• Technical Constraints: Existing systems, platforms, standards (if mentioned)
• Regulatory Constraints: Compliance requirements (if mentioned)
• Organizational Constraints: Policies, processes, culture (if mentioned)

Note: If no constraints are mentioned in the BRD, state "No specific constraints mentioned in the BRD" and proceed to the next section.

3. Solution Overview

3.1 Solution Vision

Describe the future state after implementation:

• What will be different?
• How will users interact with the solution?
• What new capabilities will exist?
• What processes will change?

3.2 Solution Approach

Explain the high-level approach:

• Architecture Pattern: (e.g., microservices, event-driven, agent-based)
• Technology Strategy: Build vs. buy decisions
• Integration Strategy: How components connect
• Deployment Strategy: Cloud, on-premise, hybrid
• Data Strategy: How data flows and is stored

3.3 Key Capabilities

List the major capabilities the solution provides:

Capability [Number]: [Capability Name]

• Description: What this capability does
• Business Value: Why it matters
• User Benefit: How users benefit
• Technical Approach: High-level implementation approach

DOCUMENT 2: Solution Architecture

File Naming Convention

[solution-name]-architecture.md

Example: customer-service-automation-architecture.md

Document Purpose

Technical architecture document for architects, developers, and technical stakeholders. Provides detailed component design, integration patterns, data architecture, and security approach.

Document Header

# [Solution Name] - Solution Architecture

**Document Type**: Solution Architecture
**Version**: 1.0
**Date**: [Date]
**Author**: [Name]
**Status**: [Draft/Review/Approved]
**Related Documents**:
- [solution-name]-overview.md (Business Overview)
- [solution-name]-implementation.md (Implementation Plan)

---

Document Structure

1. Architecture Overview

Brief summary linking to the business context:

• Reference the Solution Overview document for business context
• Summarize the technical approach in 2-3 paragraphs
• Highlight key architectural decisions

2. Solution Architecture Diagram

Create a high-level architecture diagram using Mermaid:

IMPORTANT:

• Keep diagrams at a HIGH LEVEL - show major components only, not subcomponents or internal details
• Focus on the main system boundaries and key integration points
• Avoid showing internal implementation details or breaking components into subcomponents
• The diagram should be simple enough to fit on one page and be easily understood by business stakeholders

Requirements:

• Show major system components as boxes (5-10 components maximum)
• Show external systems and integrations
• Show data flows with labeled arrows (key flows only)
• Show users/actors interacting with the system
• Use color coding for different component types:
  • User interfaces (blue)
  • Business logic/agents (green)
  • Data storage (orange)
  • External systems (gray)
  • Security components (red)
• Include a legend explaining symbols and colors

IMPORTANT - Mermaid Reserved Keywords:

• Avoid using these reserved keywords as participant/component names in sequence diagrams: Note, participant, actor, loop, alt, opt, par, and, rect, end, activate, deactivate, autonumber
• If you need to reference these concepts, use alternative names (e.g., use "NotesService" instead of "Note", "RecordingService" instead of "Recording")

Example Structure:

graph TB
    subgraph "Users"
        U1[Customer]
        U2[Support Agent]
    end
    
    subgraph "Presentation Layer"
        UI1[Web Chat Interface]
        UI2[Agent Dashboard]
    end
    
    subgraph "Application Layer"
        AG1[AI Customer Service Agent]
        AG2[Escalation Manager]
        AG3[Knowledge Base Agent]
    end
    
    subgraph "Integration Layer"
        API[API Gateway]
        MQ[Message Queue]
    end
    
    subgraph "Data Layer"
        DB1[(Customer Database)]
        KB[(Knowledge Base)]
        LOG[(Conversation Logs)]
    end
    
    subgraph "External Systems"
        CRM[CRM System]
        EMAIL[Email Service]
        LLM[LLM Provider]
    end
    
    U1 -->|Inquiry| UI1
    U2 -->|Monitor/Respond| UI2
    UI1 --> API
    UI2 --> API
    API --> AG1
    AG1 --> AG3
    AG1 --> AG2
    AG3 --> KB
    AG2 --> U2
    AG1 --> DB1
    AG1 --> LOG
    AG1 --> LLM
    AG2 --> CRM
    AG2 --> EMAIL
    
    style UI1 fill:#4A90E2
    style UI2 fill:#4A90E2
    style AG1 fill:#7ED321
    style AG2 fill:#7ED321
    style AG3 fill:#7ED321
    style DB1 fill:#F5A623
    style KB fill:#F5A623
    style LOG fill:#F5A623
    style CRM fill:#9B9B9B
    style EMAIL fill:#9B9B9B
    style LLM fill:#9B9B9B

Legend:

• Blue boxes: User-facing interfaces
• Green boxes: AI agents and business logic
• Orange cylinders: Data storage
• Gray boxes: External systems
• Arrows: Data/control flow

3. Component Breakdown

IMPORTANT: Keep component descriptions concise. Avoid repeating information already covered in other sections. Reference other sections instead of duplicating details.

For each major component in the architecture:

Component [Number]: [Component Name]

Purpose: What this component does in business terms (1-2 sentences)

Key Responsibilities: List 3-5 main responsibilities

Inputs/Outputs: Brief summary of key data flows (reference Integration Architecture section for details)

Key Technologies (if known): Primary technology/platform only

Dependencies: Critical dependencies only (reference Integration Architecture section for details)

Example:

Component 1: AI Customer Service Agent

Purpose: Automatically handles customer inquiries by understanding questions and providing accurate responses in natural language.

Key Responsibilities:
- Interpret customer inquiries in natural language
- Route inquiries to appropriate knowledge sources
- Generate contextually appropriate responses
- Detect when human escalation is needed
- Log interactions for quality tracking

Inputs/Outputs: Receives customer inquiries from Web Chat Interface; outputs responses and escalation requests (see Integration Architecture for details)

Key Technologies: watsonx Orchestrate, Large Language Model

Dependencies: LLM Provider, Knowledge Base, Customer Database (see Integration Architecture for details)

4. Integration Architecture

IMPORTANT: Keep integration architecture high-level. Focus on what systems integrate and why, not detailed implementation specifics.

4.1 Integration Points

For each external system integration:

Integration [Number]: [System Name]

Purpose: Why we integrate with this system

Integration Type: (e.g., Real-time API, Batch data exchange, Event-driven messaging)

Data Exchanged:

• To External System: What we send
• From External System: What we receive

Integration Pattern: (e.g., Request/Response, Publish/Subscribe, Webhook)

Security: High-level authentication approach (e.g., OAuth 2.0, API keys)

Example:

Integration 1: CRM System

Purpose: Retrieve customer history and update customer records with support interactions

Integration Type: Real-time API calls

Data Exchanged:
- To CRM: Support ticket details, resolution status, customer satisfaction scores
- From CRM: Customer profile, purchase history, previous support tickets, account status

Integration Pattern: Request/Response (REST API)

Security: OAuth 2.0 authentication with API keys

4.2 Data Flow Diagram

Create a high-level data flow diagram showing how information moves through the system:

sequenceDiagram
    participant Customer
    participant WebChat
    participant Agent
    participant KnowledgeBase
    participant CRM
    participant Database
    
    Customer->>WebChat: Submit inquiry
    WebChat->>Agent: Forward inquiry + session
    Agent->>CRM: Get customer context
    CRM-->>Agent: Customer history
    Agent->>KnowledgeBase: Search for answer
    KnowledgeBase-->>Agent: Relevant articles
    Agent->>Agent: Generate response
    Agent->>Database: Log conversation
    Agent->>WebChat: Send response
    WebChat->>Customer: Display response
    
    alt Escalation Needed
        Agent->>CRM: Create support ticket
        Agent->>WebChat: Transfer to human agent
    end

5. Data Architecture

IMPORTANT: Keep data architecture high-level. Focus on key data entities and storage approach, not detailed schemas.