Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-autoskill-36k/skillsmp/merged-e3fc16a5d91dc62b-business-layer-modeling/SKILL.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill merged-e3fc16a5d91dc62b-business-layer-modeling. Copyright stays with the author.

Business Layer Skill

Layer Number: 02
Specification: Metadata Model Spec v0.7.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