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.3

Application Layer Skill

Layer Number: 04 Specification: Metadata Model Spec v0.8.3 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: generic, external, internal, service-component
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

---

Type Decision Tree

Use this decision tree before assigning a type to any code pattern. Follow the first matching branch.

IS this a deployed, executable unit (container, microservice, SPA app shell, module)?
  → ApplicationComponent (type: generic/internal/external)

IS this a React component, UI widget, or view?
  → ApplicationComponent (type: generic) — link to ux.component.* for UI detail

IS this a Zustand store, Redux slice, or other state container?
  → ApplicationFunction (performs automated state management behavior)
  NOT ApplicationComponent — stores are behavior, not deployable modules
  Cross-reference: assign the function to the parent ApplicationComponent that owns it

IS this a class/function that provides a capability to other parts of the system
  (business logic, data transformation, orchestration)?
  → ApplicationService (serviceType: synchronous/asynchronous/event-driven/batch)

IS this a URL, port, protocol interface, or access point
  (REST endpoint group, WebSocket endpoint, message queue, postMessage bridge)?
  → ApplicationInterface (protocol: REST/WebSocket/AMQP/HTTP)

IS this a stateless, single-purpose algorithm or behavior
  (parse, validate, transform, export, calculate, layout)?
  → ApplicationFunction (NOT ApplicationService)

IS this a multi-step workflow, pipeline, or saga
  (load → parse → validate → render)?
  → ApplicationProcess
  NOTE: Use ApplicationProcess for orchestration logic triggered by navigation
  (data loading pipelines, guards that orchestrate multiple async operations).
  Use navigation.route for route definitions that map URL patterns to views.
  If a route component is purely declarative (no significant orchestration logic),
  it belongs only in navigation.route — not ApplicationProcess.

IS this a state change notification or domain event
  (model.updated, annotation.added)?
  → ApplicationEvent (eventType: domain/integration/system)

IS this a data structure, DTO, or typed payload
  (ModelData, Annotation, Changeset)?
  → DataObject

IS this a collection of components that together form a subsystem
  (all layout engines, all application services)?
  → ApplicationCollaboration

---

Common Misclassifications

Explicit DO NOT rules with rationale:

Misclassification	Correct Classification	Why
Zustand store as ApplicationService	ApplicationFunction (performs automated state management behavior)	Stores are behavior, not deployable modules — assign to parent ApplicationComponent
Zustand store as ApplicationComponent	ApplicationFunction (performs automated state management behavior)	ArchiMate ApplicationFunction = "automated behavior performed by a component" — maps exactly to Zustand stores
WebSocket client as ApplicationService	ApplicationInterface (protocol: WebSocket)	A WebSocket connection is an interface/access point, not a service
Layout algorithm as ApplicationService	ApplicationFunction	Stateless algorithm = function, not a service with a contract
Layout engine CLASS as ApplicationFunction	ApplicationComponent (type: internal)	A class implementing an interface IS a deployable, replaceable module — not a stateless function
Export function as ApplicationService	ApplicationFunction if purely internal; ApplicationService only if it exposes an output contract	If purely internal algorithm: function. If it has an external contract (API, file): service
React UI component as ApplicationService	ApplicationComponent (type: generic) with UX cross-reference	UI components are components; link to UX layer for rendering details
Fetch interceptor / auth header injector	ApplicationFunction	Stateless function that wraps fetch — NOT a service; cross-reference security.securitypolicy.*

---

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: AI / RAG Processing Pipeline

# Retrieval-Augmented Generation pipeline
class RAGPipeline:
    """
    Multi-stage AI document processing pipeline.
    ApplicationProcess: RAGPipeline (pattern: pipeline)
    """

    def run(self, query: str) -> str:
        chunks = self.chunker.chunk(documents)      # ApplicationFunction: DocumentChunker
        embeddings = self.embedder.embed(chunks)    # ApplicationFunction: EmbeddingGenerator
        results = self.retriever.retrieve(          # ApplicationFunction: VectorRetriever
            query_embedding, embeddings
        )
        return self.reranker.rerank(results, query) # ApplicationFunction: ResultReranker

Maps to:

• ApplicationProcess: "RAGPipeline" (pattern: pipeline) — the orchestrating process
• ApplicationFunction: "DocumentChunker" — assigned-to the RAG component; flows-to EmbeddingGenerator
• ApplicationFunction: "EmbeddingGenerator" — flows-to VectorRetriever
• ApplicationFunction: "VectorRetriever" — flows-to ResultReranker
• ApplicationFunction: "ResultReranker" — terminal stage; delivers output to the calling service
• ApplicationComponent: "RAGService" — owns all four functions via assigned-to

Key relationships:

ApplicationFunction: chunker → flows-to → ApplicationFunction: embedder
ApplicationFunction: embedder → flows-to → ApplicationFunction: retriever
ApplicationFunction: retriever → flows-to → ApplicationFunction: reranker
ApplicationComponent: rag-service → assigned-to → ApplicationFunction: chunker (×4)
ApplicationProcess: rag-pipeline → realizes → ApplicationService: rag-service

Rule: Each discrete pipeline stage is an ApplicationFunction, not a separate service — stages share the same component boundary and have no independent business contract. Use ApplicationProcess to model the orchestration. If a stage is independently deployable (e.g., a separate embedding microservice), elevate it to ApplicationComponent + ApplicationService.

---

Pattern 8: 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" \
  --description "Customer-facing web application"

# Backend microservices
dr add application component "user-service" \
  --description "User management microservice"

dr add application component "order-service" \
  --description "Order processing microservice"

# Worker component
dr add application component "email-worker" \
  --description "Background worker for email notifications"

Step 2: Define Application Services

# Synchronous service
dr add application service "user-management-api" \
  --description "User management REST API"

# Asynchronous service
dr add application service "notification-service" \
  --description "Asynchronous notification delivery"

# Link component to service
dr relationship add application.applicationcomponent.user-service \
  application.applicationservice.user-management-api --predicate realizes

Step 3: Model Application Interfaces

# REST API interface
dr add application interface "user-api-rest" \
  --description "REST interface for user service"

# gRPC interface
dr add application interface "order-grpc" \
  --description "gRPC interface for order service"

# Message queue interface
dr add application interface "event-bus" \
  --description "Event bus for async communication"

# Link service to interface
dr relationship add application.applicationservice.user-management-api \
  application.applicationinterface.user-api-rest --predicate realizes

Step 4: Define Application Functions

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

dr add application function "data-validation" \
  --description "Validates input data against business rules"

dr add application function "caching" \
  --description "Caches frequently accessed data"

# Assign function to component
dr relationship add application.applicationcomponent.user-service \
  application.applicationfunction.authentication --predicate assigned-to

Step 5: Model Application Events

# Domain events
dr add application event "order-created" \
  --description "Published when new order is created"

dr add application event "payment-processed" \
  --description "Published when payment completes"

# Event triggering
dr relationship add application.applicationevent.order-created \
  application.applicationcomponent.inventory-service --predicate triggers

dr relationship add application.applicationevent.order-created \
  application.applicationcomponent.email-worker --predicate triggers

Step 6: Define Data Objects

# Core data objects
dr add application data-object "user" \
  --description "User account information"

dr add application data-object "order" \
  --description "Customer order data"

# Service access to data
dr relationship add application.applicationservice.user-management-api \
  application.dataobject.user --predicate accesses

dr relationship add application.applicationservice.order-api \
  application.dataobject.order --predicate accesses

Step 7: Model Application Processes (Orchestration)

# Saga workflow
dr add application process "order-fulfillment-saga" \
  --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.applicationprocess.order-fulfillment-saga \
  application.applicationprocess.reserve-inventory --predicate composes

dr relationship add application.applicationprocess.order-fulfillment-saga \
  application.applicationprocess.process-payment --predicate composes

dr relationship add application.applicationprocess.order-fulfillment-saga \
  application.applicationprocess.ship-order --predicate composes

# Process flows
dr relationship add application.applicationprocess.reserve-inventory \
  application.applicationprocess.process-payment --predicate flows-to

dr relationship add application.applicationprocess.process-payment \
  application.applicationprocess.ship-order --predicate flows-to

Step 8: Cross-Layer Integration

# Link to business layer
dr relationship add application.applicationservice.order-api \
  business.service.order-management --predicate realizes

# Link to motivation layer
dr relationship add application.applicationservice.user-management-api \
  motivation.goal.improve-user-experience --predicate supports

# Link to technology layer
dr relationship add application.applicationcomponent.user-service \
  technology.node.k8s-cluster-prod --predicate deployed-on

# Link to API layer
dr relationship add application.applicationservice.user-management-api \
  api.openapi-document.user-api --predicate defined-by

# Link to data model layer
dr relationship add application.dataobject.user \
  data-model.schema.user --predicate defined-by

# Link to APM layer
dr relationship add application.applicationservice.order-api \
  apm.metric.order-processing-latency --predicate tracked-by

Step 9: Validate

dr validate --layers application
dr 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

---

React / SPA Codebase Detection Patterns

These patterns cover the actual structure of React/TypeScript single-page applications. Apply the Type Decision Tree to each pattern.

Pattern: React Component

// src/core/components/GraphViewer.tsx
export function GraphViewer({ nodes, edges }: GraphViewerProps) {
  return <ReactFlow nodes={nodes} edges={edges} />;
}

→ ApplicationComponent (type: generic) → Cross-reference: x-uses: [technology.systemsoftware.react, technology.artifact.react-flow] → Also add ux.component.graph-viewer in the UX layer for rendering detail

Pattern: Zustand Store

// src/core/stores/modelStore.ts
export const useModelStore = create<ModelStoreState>((set) => ({
  layers: {}, elements: {},
  loadModel: (data) => set({ ... })
}));

→ ApplicationFunction (performs automated state management behavior) → NOT ApplicationComponent — stores are behavior, not deployable modules → Cross-reference: assign to the parent ApplicationComponent that owns the store

Pattern: Stateless Service / Utility (parser, transformer)

// src/core/services/yamlParser.ts
export function parseYAMLModel(yaml: string): ModelData { ... }

→ ApplicationService (serviceType: synchronous) if it orchestrates other services → OR ApplicationFunction if it is a purely stateless computation with no external contract

Pattern: WebSocket Client

// src/apps/embedded/services/websocketClient.ts
const ws = new WebSocket("ws://localhost:3000/ws");
ws.on("model.updated", handler);

→ ApplicationInterface (protocol: WebSocket) — the ws connection is the interface → ApplicationEvent for each event type: model.updated, annotation.added, changeset.created

Pattern: Layout Engine Class (implements interface)

// src/core/layout/engines/DagreLayoutEngine.ts
export class DagreLayoutEngine implements LayoutEngine {
  async layout(nodes: Node[], edges: Edge[]): Promise<PositionedGraph> { ... }
}

→ ApplicationComponent (type: internal) — it IS a deployable, replaceable module → NOT ApplicationFunction — it has class structure, implements an interface, has state

Pattern: Layout Utility (pure function)

// src/core/layout/verticalLayerLayout.ts
export function computeVerticalLayout(layers: Layer[]): LayoutResult { ... }

→ ApplicationFunction — stateless algorithm, no interface → Capture even if standalone (not in an engines/ directory)

Pattern: Multi-step Loading Pipeline

// src/core/services/dataLoader.ts
async function loadModel(source: DataSource): Promise<void> {
  const raw = await fetch(source.url);
  const parsed = parseYAMLModel(raw);
  const validated = validateSchema(parsed);
  const transformed = transformToReactFlow(validated);
  modelStore.setModel(transformed);
}

→ ApplicationProcess (orchestration pipeline: fetch → parse → validate → transform → store)

Pattern: Fetch Interceptor

// src/apps/embedded/utils/fetchInterceptor.ts
export function interceptFetch(token: string) {
  window.fetch = async (url, options = {}) => {
    return originalFetch(url, {
      ...options,
      headers: { ...options.headers, Authorization: `Bearer ${token}` }
    });
  };
}

→ ApplicationFunction → source-provenance: extracted → Relationship: security.securitypolicy.bearer-token-policy (governed-by)

Pattern: Data Transfer Object / Interface

// src/core/types/model.ts
export interface ModelData {
  layers: Layer[];
  elements: Element[];
}
export interface Annotation {
  id: string;
  elementId: string;
  content: string;
}

→ DataObject for each significant data structure (ModelData, Annotation, Changeset, etc.)

---

Coverage Completeness Checklist

Before declaring application layer extraction complete, verify ALL 9 entity types have been considered:

□ ApplicationComponent — deployable units, UI components, layout engine classes (NOT Zustand stores — those are ApplicationFunction)
□ ApplicationService — capabilities with a business contract (data loader, parser service)
□ ApplicationInterface — access points: WebSocket endpoint, REST interface, postMessage bridge
□ ApplicationFunction — stateless algorithms: parse, validate, transform, export, layout; Zustand/Redux stores (state management behavior); fetch interceptors
□ ApplicationProcess — multi-step pipelines: loading pipeline, export pipeline
□ ApplicationEvent — state change notifications: model.updated, annotation.added, user events
□ DataObject — key data structures: ModelData, Annotation, Changeset, GraphNode, LayoutPreset
□ ApplicationCollaboration — component groupings: layout engine suite (groups of deployable ApplicationComponents)
□ ApplicationInteraction — collective behaviors across multiple components (if applicable)

If any type has ZERO elements, explicitly decide:
  "This type doesn't apply to this codebase" with reasoning.

---

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>
dr add application service <name>
dr add application interface <name>
dr add application function <name>
dr add application event <name>
dr add application data-object <name>
dr add application process <name>

Relationship Commands:

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

Cross-Layer Commands:

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