layer-04-app

name	LAYER_04_APP
description	Expert knowledge for Application Layer modeling in Documentation Robotics
triggers	["application service","application component","data object","application function","application process","microservice","archimate application"]
version	0.8.1

Application Layer Skill

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

CLI Introspection: Run dr schema types application for the authoritative, always-current list of node types. Run dr schema node <type-id> for full attribute details on any type.

Entity Type	Description	Key Attributes
ApplicationComponent	Modular, deployable, replaceable part of a system	Types: frontend, backend, mobile, desktop, service, library, batch, worker
ApplicationCollaboration	Aggregate of application components working together	Example: Microservices ecosystem, service mesh
ApplicationInterface	Point of access where application service is available	Protocols: REST, GraphQL, SOAP, gRPC, WebSocket, Message Queue, Event Bus
ApplicationFunction	Automated behavior performed by application component	Examples: Authentication, Data Validation, Caching, Logging
ApplicationInteraction	Unit of collective application behavior	Patterns: request-response, publish-subscribe, async-messaging, streaming, batch
ApplicationProcess	Sequence of application behaviors (orchestration/saga)	Can reference orchestration definitions (Temporal, Conductor, Camunda)
ApplicationEvent	Application state change notification	Types: domain-event, integration-event, system-event, audit-event
ApplicationService	Service that exposes application functionality	Types: synchronous, asynchronous, batch, streaming, webhook
DataObject	Data structured for automated processing	Includes schema reference, PII marking, retention policies

---

Intra-Layer Relationships

Structural Relationships

Source Type	Predicate	Target Type	Example
ApplicationCollaboration	aggregates	ApplicationComponent	"Payment Ecosystem" aggregates "PaymentService", "FraudDetection", "NotificationService"
ApplicationComponent	composes	ApplicationInterface	Component exposes interface for external access
ApplicationProcess	composes	ApplicationProcess	Workflow composed of sub-processes (saga pattern)
ApplicationComponent	assigned-to	ApplicationFunction	Component performs specific function
ApplicationCollaboration	assigned-to	ApplicationInteraction	Collaboration executes interaction pattern
ApplicationComponent	realizes	ApplicationService	"UserManagementAPI" realizes "User Management Service"
ApplicationFunction	realizes	ApplicationService	"Authentication Function" realizes "Auth Service"
ApplicationProcess	realizes	ApplicationService	"Order Processing Workflow" realizes "Order Service"
ApplicationService	realizes	ApplicationInterface	Service exposes interface
DataObject	specializes	DataObject	"CustomerOrder" specializes "Order"

Behavioral Relationships

Source Type	Predicate	Target Type	Example
ApplicationEvent	triggers	ApplicationComponent	"OrderCreated" triggers "InventoryService"
ApplicationEvent	triggers	ApplicationFunction	"UserLoggedIn" triggers "AuditLogging" function
ApplicationEvent	triggers	ApplicationProcess	"PaymentFailed" triggers "RefundProcess"
ApplicationProcess	triggers	ApplicationEvent	Workflow completion triggers event
ApplicationService	flows-to	ApplicationService	Synchronous service-to-service call
ApplicationProcess	flows-to	ApplicationProcess	Sequential process orchestration
ApplicationService	accesses	DataObject	Service reads/writes data
ApplicationFunction	accesses	DataObject	Function operates on data
ApplicationProcess	accesses	DataObject	Workflow manipulates data
ApplicationInteraction	accesses	DataObject	Interaction pattern involves data exchange
ApplicationInterface	serves	ApplicationComponent	Interface provides access to component

---

Cross-Layer References

Outgoing References (Application → Other Layers)

Target Layer	Reference Type	Example
Layer 1 (Motivation)	ApplicationService supports Goal	Service achieves business goals
Layer 1 (Motivation)	ApplicationService delivers Value	Service delivers business value
Layer 1 (Motivation)	ApplicationService governed by Principle	Service follows architectural principles
Layer 1 (Motivation)	ApplicationFunction fulfills Requirement	Function implements functional requirement
Layer 2 (Business)	ApplicationService realizes BusinessService	Tech realizes business capability
Layer 2 (Business)	ApplicationProcess supports BusinessProcess	Automates business workflow
Layer 2 (Business)	DataObject represents BusinessObject	Technical data represents business concept
Layer 5 (Technology)	ApplicationComponent deployed-on Node	Service deployed to Kubernetes cluster
Layer 5 (Technology)	ApplicationService uses TechnologyService	Application uses database service
Layer 5 (Technology)	DataObject stored-in Artifact	Data persisted in database
Layer 6 (API)	ApplicationService defined-by OpenAPI Specification	Service has OpenAPI contract
Layer 7 (Data Model)	DataObject defined-by JSON Schema	Data structure defined as schema
Layer 11 (APM)	ApplicationService tracked-by BusinessMetric	Service performance monitored
Layer 11 (APM)	ApplicationService has-sla SLA Target	Latency, availability targets
Layer 11 (APM)	ApplicationService traced-by APM	Distributed tracing enabled

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

Issue	Cause	Fix
Orphaned Component	Component not assigned to function or service	Assign to ApplicationFunction or realize ApplicationService
Unrealized Service	Service not realized by component/function	Add realization link
Missing Interface	Service has no interface	Add ApplicationInterface
No Cross-Layer Relationships	Application not linked to business/technology	Add realization and deployment relationships
Undocumented Events	Events exist in code but not modeled	Add ApplicationEvent entities
Missing Data Objects	Services access data not modeled	Add DataObject entities
No Orchestration	Complex workflows not modeled as processes	Add ApplicationProcess for sagas

---

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>