LAYER_02_BUSINESS

Business Layer Skill

Layer Number: 02 Specification: Metadata Model Spec v0.6.0 Purpose: Represents business services, processes, actors, and objects that define the organization's operational structure and capabilities.

Layer Overview

The Business Layer captures the operational structure of the organization:

• WHO - Business actors, roles, and collaborations
• WHAT - Business services and products
• HOW - Business processes, functions, and interactions
• INFORMATION - Business objects and their representations

This layer uses ArchiMate 3.2 Business Layer standard without custom extensions, with optional extensions for BPMN integration, SLA tracking, and security controls.

Entity Types

Intra-Layer Relationships

Structural Relationships

Behavioral Relationships

Cross-Layer References

Outgoing References (Business → Lower Layers)

Incoming References (Lower Layers → Business)

Lower layers (Application, Technology, API, etc.) reference Business layer elements to show:

• Realization: Application services realize business services
• Support: Technology supports business operations
• Traceability: APIs map to business interfaces

Codebase Detection Patterns

Pattern 1: Service Layer Classes

# FastAPI Business Service
@app.post("/api/orders")
async def create_order(order_data: OrderRequest):
    """Creates a new customer order (Business Service: Order Management)"""
    pass

Maps to:

• BusinessService: "Order Management Service"
• BusinessProcess: "Create Order Process"
• BusinessObject: "Order"
• BusinessInterface: "API Interface"

Pattern 2: Domain Models

from dataclasses import dataclass

@dataclass
class Customer:
    """Customer business object"""
    customer_id: str
    name: str
    email: str
    status: str  # active, inactive, suspended

Maps to:

• BusinessObject: "Customer"
• Potential BusinessProcess: "Customer Management"

Pattern 3: Event Definitions

// Domain events
export enum BusinessEvents {
  ORDER_CREATED = "order.created",
  ORDER_FULFILLED = "order.fulfilled",
  PAYMENT_RECEIVED = "payment.received",
}

Maps to:

• BusinessEvent entities (order.created, order.fulfilled, payment.received)

Pattern 4: BPMN Process References

# Process definition with BPMN reference
class OrderFulfillmentProcess:
    """
    Order fulfillment business process
    BPMN: processes/order-fulfillment.bpmn
    KPI: 95% orders fulfilled within 24 hours
    """
    def execute(self, order_id: str):
        pass

Maps to:

• BusinessProcess: "Order Fulfillment"
• Properties: bpmn-file, kpi-target

Pattern 5: Role-Based Authorization

from enum import Enum

class BusinessRole(Enum):
    SALES_REP = "sales_representative"
    ACCOUNT_MANAGER = "account_manager"
    CUSTOMER_SERVICE = "customer_service"
    ADMIN = "administrator"

@require_role(BusinessRole.SALES_REP)
def create_opportunity(data):
    pass

Maps to:

• BusinessRole entities (SalesRepresentative, AccountManager, etc.)

Pattern 6: SLA Configuration

# Service SLA definitions
services:
  order_processing:
    sla:
      availability: 99.9%
      response_time: 500ms
      throughput: 1000 req/sec
    business_hours: "24/7"

Maps to:

• BusinessService with SLA properties
• Contract entity for formal SLA

Modeling Workflow

Step 1: Identify Business Actors and Roles

# Add business actors
dr add business actor "Customer" \
  --description "End user purchasing products"

dr add business actor "Sales Team" \
  --description "Internal sales organization"

# Add business roles
dr add business role "Sales Representative" \
  --description "Responsible for customer acquisition"

dr add business role "Account Manager" \
  --description "Manages existing customer relationships"

Step 2: Define Business Services

# Core business service
dr add business service "Order Management Service" \
  --properties sla-availability=99.9%,sla-response-time=500ms \
  --description "Manages customer order lifecycle"

# Link to motivation layer
dr relationship add "business/service/order-management" \
  supports "motivation/goal/improve-order-efficiency"

Step 3: Model Business Processes

# Main process
dr add business process "Order Fulfillment Process" \
  --properties bpmn-file=processes/order-fulfillment.bpmn \
  --description "End-to-end order fulfillment from creation to delivery"

# Sub-processes
dr add business process "Pick Items Process" \
  --description "Pick items from warehouse inventory"

dr add business process "Pack Order Process" \
  --description "Pack picked items for shipment"

# Composition relationships
dr relationship add "business/process/order-fulfillment" \
  composes "business/process/pick-items"

dr relationship add "business/process/order-fulfillment" \
  composes "business/process/pack-order"

# Process flows
dr relationship add "business/process/pick-items" \
  flows-to "business/process/pack-order"

Step 4: Define Business Objects

# Core business objects
dr add business object "Order" \
  --description "Customer purchase order"

dr add business object "Customer" \
  --description "Individual or organization purchasing products"

dr add business object "Product" \
  --description "Item available for purchase"

# Process access to objects
dr relationship add "business/process/order-fulfillment" \
  accesses "business/object/order"

Step 5: Model Business Events

# Events that trigger processes
dr add business event "Order Received" \
  --properties type=state-change,topic=orders.received \
  --description "New order submitted by customer"

dr add business event "Payment Confirmed" \
  --properties type=state-change,topic=payments.confirmed \
  --description "Payment successfully processed"

# Event triggering
dr relationship add "business/event/order-received" \
  triggers "business/process/order-fulfillment"

Step 6: Establish Cross-Layer Relationships

# Link to application layer
dr relationship add "business/service/order-management" \
  realized-by "application/service/order-api"

# Link to motivation layer
dr relationship add "business/service/order-management" \
  delivers "motivation/value/customer-satisfaction"

# Link to data layer
dr relationship add "business/object/order" \
  defined-by "data-model/schema/order.schema.json"

Step 7: Validate

dr validate --layer business
dr validate --validate-relationships

Common Modeling Scenarios

Scenario 1: E-commerce Order Management

Product: "E-commerce Platform"
├── composes → BusinessService: "Order Service"
│   ├── realizes ← BusinessProcess: "Order Fulfillment"
│   │   ├── triggers ← BusinessEvent: "Order Received"
│   │   ├── accesses → BusinessObject: "Order"
│   │   └── assigned-to → BusinessRole: "Order Processor"
│   └── realized-by → ApplicationService: "OrderManagementAPI"
├── composes → BusinessService: "Payment Service"
│   └── realizes ← BusinessProcess: "Payment Processing"
└── aggregates → Contract: "E-commerce SLA"

Scenario 2: Customer Support System

BusinessFunction: "Customer Support"
├── composes → BusinessProcess: "Ticket Resolution"
│   ├── triggers ← BusinessEvent: "Support Request Received"
│   ├── assigned-to → BusinessRole: "Support Agent"
│   ├── accesses → BusinessObject: "Support Ticket"
│   └── flows-to → BusinessProcess: "Follow-up Communication"
├── realizes → BusinessService: "Support Service"
│   ├── serves → BusinessActor: "Customer"
│   └── properties: sla-response-time=2h, sla-resolution-time=24h
└── tracked-by → BusinessMetric: "First Response Time"

Scenario 3: Sales Pipeline

BusinessCollaboration: "Sales Team"
├── composes → BusinessRole: "Sales Representative"
├── composes → BusinessRole: "Sales Manager"
└── assigned-to → BusinessInteraction: "Sales Meeting"
    ├── accesses → BusinessObject: "Opportunity"
    ├── flows-to → BusinessProcess: "Proposal Generation"
    └── triggers → BusinessEvent: "Deal Closed"

BPMN Integration

When business processes reference BPMN diagrams:

dr add business process "Loan Approval Process" \
  --properties bpmn-file=processes/loan-approval.bpmn,bpmn-version=2.0 \
  --description "End-to-end loan application review and approval"

BPMN Properties:

• bpmn-file: Path to BPMN XML file
• bpmn-version: BPMN specification version (2.0)
• bpmn-task-mapping: Map BPMN tasks to business roles

Validation: Ensure BPMN task IDs align with business process sub-processes.

SLA and Performance Tracking

Business services can define SLA targets:

business-service:
  id: "payment-processing-service"
  properties:
    sla-availability: "99.99%"
    sla-response-time: "200ms"
    sla-throughput: "5000 tps"
    business-hours: "24/7"
    escalation-time: "15m"

These SLAs flow down to:

• Application Layer - Application services inherit targets
• APM Layer - Monitoring dashboards track against targets
• Motivation Layer - SLAs trace to business goals

ArchiMate Export

dr export archimate --layer business --output business.archimate

Supported ArchiMate Elements:

• All 13 business entity types map directly to ArchiMate 3.2 Business Layer
• Relationships: composition, aggregation, assignment, realization, specialization, triggering, flow, serving, access, association

Best Practices

1. Start with Services, Not Processes - Identify WHAT the business provides before HOW it's delivered
2. Use Process Composition - Break complex processes into manageable sub-processes
3. Model Events Explicitly - Event-driven architectures need explicit BusinessEvent entities
4. Link to Motivation Early - Connect services and processes to goals for traceability
5. Don't Over-Detail - Focus on architecturally significant processes, not every task
6. Use BPMN for Complex Workflows - Reference BPMN files rather than modeling every detail
7. Distinguish Role from Actor - Role is responsibility; Actor is individual/team
8. Model Contracts for SLAs - Formalize service agreements as Contract entities
9. Track Business Objects - Identify key domain concepts even if data model comes later

Validation Tips

Quick Reference

Add Commands:

dr add business actor <name>
dr add business role <name>
dr add business service <name> --properties sla-availability=<value>
dr add business process <name> --properties bpmn-file=<path>
dr add business object <name>
dr add business event <name> --properties type=<type>,topic=<topic>
dr add business function <name>
dr add business collaboration <name>

Relationship Commands:

dr relationship add <source> realizes <target>
dr relationship add <source> composes <target>
dr relationship add <source> assigned-to <target>
dr relationship add <source> triggers <target>
dr relationship add <source> flows-to <target>
dr relationship add <source> accesses <target>
dr relationship add <source> serves <target>

Cross-Layer Relationship Commands:

dr relationship add <business-service> supports <motivation-goal>
dr relationship add <business-service> realized-by <application-service>
dr relationship add <business-object> defined-by <data-schema>