LAYER_04_APP

Application Layer Skill

Layer Number: 04 Specification: Metadata Model Spec v0.6.0 Purpose: Describes application services, components, and interfaces that support business processes and bridge requirements with technical implementation.

Layer Overview

The Application Layer captures application architecture:

• WHAT - Application services exposed to business
• HOW - Application components and functions
• INTEGRATION - Application interfaces and interactions
• DATA - Data objects processed by applications
• EVENTS - Application events for event-driven architecture

This layer uses ArchiMate 3.2 Application Layer standard with optional properties for external specifications (OpenAPI, orchestration definitions, event schemas).

Entity Types

Intra-Layer Relationships

Structural Relationships

Behavioral Relationships

Cross-Layer References

Outgoing References (Application → Other Layers)

Incoming References (Lower Layers → Application)

Lower layers reference Application layer to show:

• Technology supports Application - Infrastructure hosts application components
• APIs implement Application Services - OpenAPI specs define service contracts
• Data schemas define DataObjects - JSON schemas provide data structure

Codebase Detection Patterns

Pattern 1: Microservice Component

# FastAPI microservice
from fastapi import FastAPI

app = FastAPI(
    title="User Management Service",
    description="Handles user authentication and profile management",
    version="1.0.0"
)

@app.get("/health")
async def health_check():
    return {"status": "healthy"}

Maps to:

• ApplicationComponent: "UserManagementService" (type: backend, subtype: microservice)
• ApplicationService: "User Management Service" (type: synchronous)
• ApplicationInterface: "REST API" (protocol: REST)

Pattern 2: Application Function (Utility)

// Authentication utility function
export class AuthenticationService {
  /**
   * Validates JWT token and returns user context
   * ApplicationFunction: Token Validation
   */
  async validateToken(token: string): Promise<UserContext> {
    // Implementation
  }
}

Maps to:

• ApplicationFunction: "Token Validation"
• ApplicationComponent: "AuthenticationService"

Pattern 3: Event-Driven Architecture

# Event definitions
from dataclasses import dataclass
from enum import Enum

class ApplicationEventType(Enum):
    ORDER_CREATED = "order.created"
    ORDER_FULFILLED = "order.fulfilled"
    PAYMENT_PROCESSED = "payment.processed"

@dataclass
class OrderCreatedEvent:
    """
    Domain event: Order created
    Schema: schemas/events/order-created.json
    Topic: orders.created
    """
    order_id: str
    customer_id: str
    timestamp: datetime

Maps to:

• ApplicationEvent: "OrderCreated" (type: domain-event, topic: orders.created)
• Properties: schema-ref, event-version
• Triggers other ApplicationComponents

Pattern 4: Service Orchestration (Saga)

# Temporal workflow (saga pattern)
from temporalio import workflow

@workflow.defn
class OrderFulfillmentWorkflow:
    """
    Order fulfillment orchestration
    ApplicationProcess: Order Fulfillment Saga
    Pattern: Saga with compensation
    """
    @workflow.run
    async def run(self, order_id: str) -> str:
        # Step 1: Reserve inventory
        await workflow.execute_activity(reserve_inventory, order_id)

        # Step 2: Process payment
        await workflow.execute_activity(process_payment, order_id)

        # Step 3: Ship order
        await workflow.execute_activity(ship_order, order_id)

        return "fulfilled"

Maps to:

• ApplicationProcess: "OrderFulfillmentSaga" (pattern: saga)
• Properties: orchestration-engine=temporal, compensation-enabled=true
• Composes sub-processes (reserve, pay, ship)

Pattern 5: Data Transfer Object (DTO)

// Data object definitions
export interface UserDTO {
  /**
   * User data object
   * Schema: schemas/user.schema.json
   * PII: true (contains email, name)
   * Retention: 7 years
   */
  userId: string;
  email: string;
  name: string;
  createdAt: Date;
}

Maps to:

• DataObject: "User"
• Properties: schema-ref=user.schema.json, pii=true, retention-period=7y

Pattern 6: gRPC Service Interface

// gRPC service definition
service UserService {
  // ApplicationInterface: gRPC
  // Protocol: gRPC
  rpc GetUser (GetUserRequest) returns (User);
  rpc CreateUser (CreateUserRequest) returns (User);
  rpc UpdateUser (UpdateUserRequest) returns (User);
}

Maps to:

• ApplicationInterface: "UserServiceGRPC" (protocol: gRPC)
• ApplicationService: "User Service"
• ApplicationComponent: "UserService"

Pattern 7: Message Queue Consumer

# RabbitMQ consumer
from kombu import Connection, Queue

class OrderEventConsumer:
    """
    Consumes order events from message queue
    ApplicationComponent: OrderEventConsumer (type: worker)
    ApplicationInterface: Message Queue (protocol: AMQP)
    """
    def __init__(self):
        self.queue = Queue('orders.created', exchange='orders')

    def consume(self):
        with Connection('amqp://localhost') as conn:
            with conn.Consumer(self.queue, callbacks=[self.handle_order]):
                conn.drain_events()

    def handle_order(self, body, message):
        # Process order event
        message.ack()

Maps to:

• ApplicationComponent: "OrderEventConsumer" (type: worker)
• ApplicationInterface: "OrderQueue" (protocol: AMQP)
• ApplicationEvent: "OrderCreated" (triggers this component)

Modeling Workflow

Step 1: Identify Application Components

# Frontend component
dr add application component "web-app" \
  --properties type=frontend,technology=react,repository=github.com/org/web-app \
  --description "Customer-facing web application"

# Backend microservices
dr add application component "user-service" \
  --properties type=backend,subtype=microservice,language=python \
  --description "User management microservice"

dr add application component "order-service" \
  --properties type=backend,subtype=microservice,language=typescript \
  --description "Order processing microservice"

# Worker component
dr add application component "email-worker" \
  --properties type=worker,runtime=nodejs \
  --description "Background worker for email notifications"

Step 2: Define Application Services

# Synchronous service
dr add application service "user-management-api" \
  --properties type=synchronous,protocol=REST,openapi-spec=specs/user-api.yaml \
  --description "User management REST API"

# Asynchronous service
dr add application service "notification-service" \
  --properties type=asynchronous,pattern=publish-subscribe \
  --description "Asynchronous notification delivery"

# Link component to service
dr relationship add "application/component/user-service" \
  realizes "application/service/user-management-api"

Step 3: Model Application Interfaces

# REST API interface
dr add application interface "user-api-rest" \
  --properties protocol=REST,base-url=/api/v1/users,authentication=JWT \
  --description "REST interface for user service"

# gRPC interface
dr add application interface "order-grpc" \
  --properties protocol=gRPC,port=50051 \
  --description "gRPC interface for order service"

# Message queue interface
dr add application interface "event-bus" \
  --properties protocol=AMQP,broker=rabbitmq \
  --description "Event bus for async communication"

# Link service to interface
dr relationship add "application/service/user-management-api" \
  realizes "application/interface/user-api-rest"

Step 4: Define Application Functions

# Core functions
dr add application function "authentication" \
  --properties type=security \
  --description "Validates user credentials and issues tokens"

dr add application function "data-validation" \
  --properties type=business-logic \
  --description "Validates input data against business rules"

dr add application function "caching" \
  --properties type=performance,strategy=redis \
  --description "Caches frequently accessed data"

# Assign function to component
dr relationship add "application/component/user-service" \
  assigned-to "application/function/authentication"

Step 5: Model Application Events

# Domain events
dr add application event "order-created" \
  --properties type=domain-event,topic=orders.created,schema=schemas/order-created.json \
  --description "Published when new order is created"

dr add application event "payment-processed" \
  --properties type=domain-event,topic=payments.processed,schema=schemas/payment-processed.json \
  --description "Published when payment completes"

# Event triggering
dr relationship add "application/event/order-created" \
  triggers "application/component/inventory-service"

dr relationship add "application/event/order-created" \
  triggers "application/component/email-worker"

Step 6: Define Data Objects

# Core data objects
dr add application data-object "user" \
  --properties schema-ref=schemas/user.schema.json,pii=true,retention-period=7y \
  --description "User account information"

dr add application data-object "order" \
  --properties schema-ref=schemas/order.schema.json,pii=false,retention-period=10y \
  --description "Customer order data"

# Service access to data
dr relationship add "application/service/user-management-api" \
  accesses "application/data-object/user"

dr relationship add "application/service/order-api" \
  accesses "application/data-object/order"

Step 7: Model Application Processes (Orchestration)

# Saga workflow
dr add application process "order-fulfillment-saga" \
  --properties pattern=saga,orchestration-engine=temporal,compensation=true \
  --description "End-to-end order fulfillment orchestration"

# Sub-processes
dr add application process "reserve-inventory" \
  --description "Reserve items from inventory"

dr add application process "process-payment" \
  --description "Charge customer payment method"

dr add application process "ship-order" \
  --description "Initiate shipping workflow"

# Process composition
dr relationship add "application/process/order-fulfillment-saga" \
  composes "application/process/reserve-inventory"

dr relationship add "application/process/order-fulfillment-saga" \
  composes "application/process/process-payment"

dr relationship add "application/process/order-fulfillment-saga" \
  composes "application/process/ship-order"

# Process flows
dr relationship add "application/process/reserve-inventory" \
  flows-to "application/process/process-payment"

dr relationship add "application/process/process-payment" \
  flows-to "application/process/ship-order"

Step 8: Cross-Layer Integration

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

# Link to motivation layer
dr relationship add "application/service/user-management-api" \
  supports "motivation/goal/improve-user-experience"

# Link to technology layer
dr relationship add "application/component/user-service" \
  deployed-on "technology/node/k8s-cluster-prod"

# Link to API layer
dr relationship add "application/service/user-management-api" \
  defined-by "api/openapi-document/user-api"

# Link to data model layer
dr relationship add "application/data-object/user" \
  defined-by "data-model/schema/user"

# Link to APM layer
dr relationship add "application/service/order-api" \
  tracked-by "apm/metric/order-processing-latency"

Step 9: Validate

dr validate --layer application
dr validate --validate-relationships

Application Architecture Patterns

Pattern 1: Microservices Architecture

ApplicationCollaboration: "E-commerce Platform"
├── aggregates → ApplicationComponent: "UserService"
│   ├── realizes → ApplicationService: "User API"
│   └── deployed-on → Node: "K8s Cluster"
├── aggregates → ApplicationComponent: "OrderService"
│   ├── realizes → ApplicationService: "Order API"
│   └── deployed-on → Node: "K8s Cluster"
├── aggregates → ApplicationComponent: "PaymentService"
│   └── realizes → ApplicationService: "Payment API"
└── uses → ApplicationInterface: "API Gateway"

Pattern 2: Event-Driven Architecture

ApplicationEvent: "OrderCreated"
├── triggers → ApplicationComponent: "InventoryService"
├── triggers → ApplicationComponent: "EmailWorker"
├── triggers → ApplicationComponent: "AnalyticsService"
└── published-by → ApplicationComponent: "OrderService"
    └── uses → ApplicationInterface: "EventBus" (protocol: AMQP)

Pattern 3: Saga Orchestration

ApplicationProcess: "Order Fulfillment Saga"
├── composes → ApplicationProcess: "Reserve Inventory"
│   ├── flows-to → ApplicationProcess: "Process Payment"
│   └── compensation → ApplicationProcess: "Release Inventory"
├── composes → ApplicationProcess: "Process Payment"
│   ├── flows-to → ApplicationProcess: "Ship Order"
│   └── compensation → ApplicationProcess: "Refund Payment"
└── properties: orchestration-engine=temporal, pattern=saga

Pattern 4: API Gateway Pattern

ApplicationInterface: "API Gateway"
├── protocol: REST
├── routes-to → ApplicationService: "User API"
├── routes-to → ApplicationService: "Order API"
├── routes-to → ApplicationService: "Payment API"
├── applies → ApplicationFunction: "Authentication"
├── applies → ApplicationFunction: "Rate Limiting"
└── applies → ApplicationFunction: "Request Logging"

Best Practices

1. Components are Deployable Units - One component = one deployment artifact
2. Services are Contracts - ApplicationService represents capability, not implementation
3. Separate Read from Write - Consider CQRS pattern for complex domains
4. Model Events Explicitly - Event-driven systems need first-class event entities
5. Link to Business Layer - Every application service should realize a business service
6. Reference External Specs - Link to OpenAPI, GraphQL schemas, Protobuf definitions
7. Mark PII Explicitly - DataObjects with PII need retention and security policies
8. Use Orchestration for Sagas - Model complex workflows as ApplicationProcess
9. Distinguish Interface from Service - Interface is access point; Service is capability
10. Track Dependencies - Model service-to-service dependencies clearly

Framework-Specific Patterns

FastAPI / Flask (Python)

# FastAPI application
from fastapi import FastAPI

app = FastAPI(title="User Service")  # ApplicationComponent + ApplicationService

@app.get("/users/{user_id}")  # ApplicationInterface (REST)
async def get_user(user_id: str) -> UserDTO:  # DataObject
    pass  # ApplicationFunction: "GetUser"

NestJS / Express (TypeScript/Node.js)

@Controller("orders") // ApplicationComponent
export class OrdersController {
  @Get(":id") // ApplicationInterface (REST)
  async getOrder(@Param("id") id: string): Promise<OrderDTO> {
    // DataObject
    // ApplicationFunction: "GetOrder"
  }
}

Spring Boot (Java)

@RestController  // ApplicationComponent
@RequestMapping("/api/products")
public class ProductController {

  @GetMapping("/{id}")  // ApplicationInterface (REST)
  public ProductDTO getProduct(@PathVariable String id) {  // DataObject
    // ApplicationFunction: "GetProduct"
  }
}

Validation Tips

Quick Reference

Add Commands:

dr add application component <name> --properties type=<type>
dr add application service <name> --properties type=<type>,protocol=<protocol>
dr add application interface <name> --properties protocol=<protocol>
dr add application function <name> --properties type=<type>
dr add application event <name> --properties type=<type>,topic=<topic>
dr add application data-object <name> --properties schema-ref=<path>,pii=<bool>
dr add application process <name> --properties pattern=<pattern>

Relationship Commands:

dr relationship add <component> realizes <service>
dr relationship add <service> realizes <interface>
dr relationship add <component> assigned-to <function>
dr relationship add <event> triggers <component>
dr relationship add <service> accesses <data-object>
dr relationship add <process> composes <sub-process>
dr relationship add <process-a> flows-to <process-b>

Cross-Layer Commands:

dr relationship add application/<service> realizes business/<service>
dr relationship add application/<component> deployed-on technology/<node>
dr relationship add application/<service> defined-by api/<openapi-doc>
dr relationship add application/<data-object> defined-by data-model/<schema>