@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/integrations/github_copilot/skills/dr_04_application_layer/SKILL.md

@@ -0,0 +1,670 @@
+---
+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
+
+```python
+# 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)
+
+```typescript
+// 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
+
+```python
+# 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)
+
+```python
+# 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)
+
+```typescript
+// 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
+
+```protobuf
+// 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
+
+```python
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+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)
+
+```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)
+
+```typescript
+@Controller("orders") // ApplicationComponent
+export class OrdersController {
+  @Get(":id") // ApplicationInterface (REST)
+  async getOrder(@Param("id") id: string): Promise<OrderDTO> {
+    // DataObject
+    // ApplicationFunction: "GetOrder"
+  }
+}
+```
+
+### Spring Boot (Java)
+
+```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:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+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>
+```