2.2: Architecture Agent Instructions

Role Definition

Architecture Agent (SWE.2)

Primary Responsibility: Design software architecture, allocate requirements to components, define interfaces, evaluate alternatives

ASPICE Process: SWE.2 Software Architectural Design

Success Metrics:

  • ADR Drafting Quality: 80-90% approved on first review
  • UML Diagram Generation: 85-95% accuracy (correct syntax, semantics)
  • Interface Validation: 95-100% type consistency checks

Input Work Products

Required Inputs (Must Exist Before Starting)

1. Software Requirements Specification (SWE.1 Output)

  • Content: Software requirements (SWE-XXX), interface definitions, traceability to SYS
  • Quality Criteria: Requirements approved by human, no critical ambiguities

2. System Architecture (SYS.3 Output)

  • Content: High-level block diagram (SW/HW boundary, ECU allocation)
  • Purpose: Defines context for software architecture (e.g., ACC runs on ECU-1, interfaces with ECU-2 via CAN)

3. Project Constraints

  • Technical Constraints: CPU (TriCore 300 MHz), RAM (2 MB), coding standards (MISRA C:2012)
  • Architectural Patterns: AUTOSAR Classic, layered architecture, microservices (if applicable)

Execution Steps

Step-by-Step Workflow

Step 1: Analyze Requirements and Identify Components

Action: Group related requirements into logical software components

Component Identification Rules:

  1. Functional Cohesion: Group requirements that implement a single feature (e.g., ACC control loop)
  2. Data Cohesion: Group requirements that operate on shared data (e.g., sensor fusion)
  3. Interface Boundaries: Separate components at interface boundaries (CAN, API, RTOS tasks)

Example Grouping:

Requirements:

  • [SWE-045-1] Calculate obstacle distance (radar)
  • [SWE-045-2] Calculate closing speed
  • [SWE-045-3] Trigger emergency brake
  • [SWE-078-1] Read CAN messages
  • [SWE-078-2] Write CAN messages

Identified Components:

Component 1: ACC_Controller
├─ SWE-045-1: Calculate distance
├─ SWE-045-2: Calculate speed
└─ SWE-045-3: Brake trigger logic

Component 2: CAN_Driver
├─ SWE-078-1: Read CAN messages
└─ SWE-078-2: Write CAN messages

Output: Component list with requirement allocation (Markdown table)

| Component | Requirements | Rationale |
|-----------|--------------|-----------|
| ACC_Controller | SWE-045-1, SWE-045-2, SWE-045-3 | Core ACC control logic |
| CAN_Driver | SWE-078-1, SWE-078-2 | CAN communication |
| Sensor_Fusion | SWE-089-1, SWE-089-2 | Combine radar + camera |

Step 2: Design Software Architecture

Action: Create architectural diagrams (C4 Context, Container, Component levels)

Diagram Types (using the C4 model — a four-level notation for software architecture: Context, Containers, Components, and Code; see c4model.com):

  1. C4 Context Diagram: Shows the system boundary and which external systems/users interact with it
  2. C4 Container Diagram: Shows the major deployable units (processes, services, databases) within the system
  3. C4 Component Diagram: Shows internal components within a container and how they interact

Example: C4 Component Diagram (PlantUML)

@startuml ACC_Architecture

package "ACC ECU (TriCore TC397)" {
    component ACC_Controller {
        port "CAN_Rx" as CAN_Rx
        port "CAN_Tx" as CAN_Tx
        component "Distance_Calculation" as DistCalc
        component "Speed_Calculation" as SpeedCalc
        component "Brake_Logic" as BrakeLogic
    }

    component CAN_Driver {
        port "HW_CAN_Port" as HW_CAN
    }

    component RTOS {
        component "Task_ACC_10ms"
        component "Task_CAN_5ms"
    }
}

' External systems
component "Radar Sensor" as Radar
component "Brake Actuator" as Brake

' Interfaces
Radar --> CAN_Driver : CAN_MSG_0x200\n(50 Hz)
CAN_Driver --> ACC_Controller : CAN_Rx\nRadar data
ACC_Controller --> CAN_Driver : CAN_Tx\nBrake command
CAN_Driver --> Brake : CAN_MSG_0x300\n(on demand)

' Internal dependencies
DistCalc --> SpeedCalc : distance data
SpeedCalc --> BrakeLogic : speed data

' RTOS scheduling
RTOS --> ACC_Controller : Schedule 10ms
RTOS --> CAN_Driver : Schedule 5ms

note right of ACC_Controller
  ASIL-B safety-critical component
  Latency: ≤50ms (SWE-045)
  MISRA C:2012 compliant
end note

@enduml

AI Agent Action: Generate PlantUML code, render diagram (using PlantUML CLI — install via brew install plantuml or apt install plantuml — or the web service at plantuml.com)

Quality Check:

  • [OK] All components from Step 1 present in diagram
  • [OK] Interfaces labeled (message IDs, frequency, data types)
  • [OK] RTOS tasks shown (if real-time system)
  • [OK] Safety-critical components annotated (ASIL-B)

Step 3: Define Component Interfaces

Action: Specify API signatures for inter-component communication

Interface Definition Template (C header file):

/**
 * @file acc_controller.h
 * @brief ACC Controller Component Interface
 * @architecture_component ACC_Controller
 * @safety_class ASIL-B
 * @implements [SWE-045-1, SWE-045-2, SWE-045-3]
 */

#ifndef ACC_CONTROLLER_H
#define ACC_CONTROLLER_H

#include <stdint.h>
#include <stdbool.h>

/**
 * @brief Initialize ACC controller
 * @return 0 = success, -1 = failure
 * @precondition CAN driver initialized
 */
int ACC_Init(void);

/**
 * @brief Main ACC control loop (called by RTOS every 10ms)
 * @implements [SWE-045-3] Brake trigger logic
 * @return 0 = success, -1 = sensor fault detected
 * @safety_class ASIL-B
 * @wcet 8.5 ms (WCET = Worst-Case Execution Time, measured on TriCore TC397 @ 300 MHz)
 */
int ACC_ControlLoop_10ms(void);

/**
 * @brief Get current obstacle distance
 * @param[out] distance_m Pointer to distance output (meters)
 * @return 0 = success, -1 = invalid sensor data
 * @implements [SWE-045-1]
 */
int ACC_GetObstacleDistance(float* distance_m);

/**
 * @brief Get current closing speed
 * @param[out] speed_kmh Pointer to speed output (km/h, positive = approaching)
 * @return 0 = success, -1 = invalid sensor data
 * @implements [SWE-045-2]
 */
int ACC_GetClosingSpeed(float* speed_kmh);

/**
 * @brief Enable/disable ACC system
 * @param[in] enable true = enable, false = disable (safe state)
 * @safety_class ASIL-B (safe state transition)
 */
void ACC_SetEnabled(bool enable);

#endif /* ACC_CONTROLLER_H */

Quality Check:

  • [OK] All functions have Doxygen headers (@brief, @param, @return)
  • [OK] Traceability tags present (@implements [SWE-XXX])
  • [OK] Safety annotations (@safety_class ASIL-B)
  • [OK] Preconditions/postconditions specified
  • [OK] Error codes defined (return values)

Step 4: Evaluate Alternative Architectures (ADR)

Action: Document architectural decisions in ADR (Architecture Decision Record) format

ADR Template:

# ADR-003: AUTOSAR Classic vs Adaptive for ACC ECU

## Status
Proposed

## Context
The ACC ECU software requires an operating system and middleware layer.
Two options: AUTOSAR Classic R4.4 (traditional, proven) vs AUTOSAR Adaptive R21-11 (modern, flexible).

## Decision
We will use **AUTOSAR Classic R4.4** for the ACC ECU.

## Rationale

### Option 1: AUTOSAR Classic R4.4 (SELECTED)
**Pros**:
- [+] Proven technology (used in >100M vehicles)
- [+] Lower cost (tooling: €50k vs €200k for Adaptive)
- [+] Simpler development (less C++ expertise needed)
- [+] Better real-time determinism (static configuration)
- [+] Tool support (Vector DaVinci, EB tresos)

**Cons**:
- [-] Less flexible (static configuration, hard to update)
- [-] No OTA updates (requires reflashing)

### Option 2: AUTOSAR Adaptive R21-11 (REJECTED)
**Pros**:
- [+] Modern C++ (better abstraction)
- [+] OTA update support (Service-Oriented Architecture)
- [+] Better suited for future ML integration

**Cons**:
- [-] Higher cost (tooling: €200k, training: 2 months)
- [-] Less deterministic (dynamic memory, threading)
- [-] Immature ecosystem (fewer certified tools)
- [-] Overkill for simple ACC (no OTA requirement from OEM)

## Consequences
- **Positive**: Lower cost, faster development, proven technology
- **Negative**: No OTA updates (OEM does not require this feature)
- **Mitigation**: If OTA needed in future, migrate to Adaptive in next generation (ECU-2)

## Alternatives Considered
- FreeRTOS + custom middleware (rejected: no AUTOSAR compliance, higher integration effort)
- QNX RTOS (rejected: licensing cost, not automotive-standard)

## Decision Makers
- @architect (lead)
- @project_manager (budget approval)
- @oem_customer (confirmed no OTA requirement)

## Date
2025-12-17

## Implemented By
[TBD - Implementation Agent will generate AUTOSAR Classic configuration]

AI Agent Action:

  1. Generate ADR draft (as above)
  2. Research pros and cons for each option (from training data, web search if available)
  3. DO NOT make the final decision → Escalate to human architect
  4. Include "Status: Proposed" (awaiting human approval)

Escalation Rule: Always escalate ADRs — architectural decisions are a human responsibility

Step 5: Allocate Requirements to Components

Action: Create traceability matrix (SWE → Architecture Component)

Output Format: Markdown table

| Software Requirement | Component | Interface | Rationale |
|----------------------|-----------|-----------|-----------|
| SWE-045-1 | ACC_Controller | ACC_GetObstacleDistance() | Core ACC logic |
| SWE-045-2 | ACC_Controller | ACC_GetClosingSpeed() | Core ACC logic |
| SWE-045-3 | ACC_Controller | ACC_ControlLoop_10ms() | Main control loop |
| SWE-078-1 | CAN_Driver | CAN_ReadMessage() | HW abstraction |
| SWE-078-2 | CAN_Driver | CAN_WriteMessage() | HW abstraction |

Quality Check: Verify 100% requirement coverage — all SWE requirements must be allocated to components

Step 6: Validate Architecture Consistency

Action: Check for common architectural issues

Validation Checks:

  1. Cyclic Dependencies: No component should depend on itself (directly or indirectly)
  2. Interface Consistency: All function calls must match signatures
  3. Safety Segregation: ASIL-B components isolated from QM components (if mixed criticality)
  4. Resource Constraints: Total memory usage ≤ RAM budget (2 MB)

Example Validation (Python):

import networkx as nx

def detect_cyclic_dependencies(architecture):
    """
    Detect cyclic dependencies in component graph
    Returns: List of cycles (if any)
    """
    G = nx.DiGraph()

    # Build graph (nodes = components, edges = dependencies)
    for component in architecture.components:
        G.add_node(component.name)
        for dependency in component.depends_on:
            G.add_edge(component.name, dependency)

    # Find cycles
    cycles = list(nx.simple_cycles(G))

    if cycles:
        return f"[ERROR] Cyclic dependency detected: {cycles}"
    else:
        return "[OK] No cyclic dependencies"

# Example
architecture = parse_architecture("ACC_Architecture.plantuml")
result = detect_cyclic_dependencies(architecture)
print(result)

Escalation: If validation fails (cyclic dependencies, resource overflow), escalate to architect: "Architecture has cyclic dependency: ACC_Controller → CAN_Driver → ACC_Controller"

Output Work Products

What Architecture Agent Must Generate

1. Software Architecture Document (SAD)

  • Content:
    • Component diagram (C4, PlantUML)
    • Component descriptions (purpose, requirements, interfaces)
    • Interface specifications (C header files)
    • Traceability (SWE → Components)
  • Format: Markdown + embedded PlantUML diagrams

2. Architecture Decision Records (ADRs)

  • Content: One ADR per major decision (see Step 4 template)
  • Status: "Proposed" (awaiting human approval)
  • Format: Markdown (ADR-XXX.md)

3. Traceability Matrix (SWE → Architecture)

  • Format: Markdown table or Excel
  • Content: Requirement-to-component allocation

4. Validation Report

  • Content: Results of consistency checks (cyclic dependencies, interface validation)
  • Format: Markdown

5. Pull Request Summary

## Summary
- Designed software architecture with 5 components (ACC_Controller, CAN_Driver, Sensor_Fusion, HMI, Diagnostics)
- Generated C4 component diagram (PlantUML)
- Defined 23 API functions across components
- Created 3 ADRs (AUTOSAR Classic, CAN vs Ethernet, PID controller selection)
- Validated architecture (no cyclic dependencies, interfaces consistent)

## AI Confidence
- High confidence: Component identification, interface definitions (85% accuracy)
- Medium confidence: ADR pros/cons (requires human decision)

## Traceability
- 100% SWE → Component coverage (34/34 requirements allocated)

## Human Action Required
1. Review and approve ADRs (ADR-003, ADR-007, ADR-012)
2. Validate component boundaries (is Sensor_Fusion part of ACC_Controller or separate?)
3. Approve API signatures (any missing error codes?)

## Quality Metrics
- PlantUML syntax valid: [PASS] (compiled without errors)
- Interface type consistency: 100% (all function calls type-safe)
- Cyclic dependencies: [PASS] None detected
- ASPICE SWE.2 BP coverage: BP1-5 fully addressed

Quality Criteria

Acceptance Criteria for Architecture Agent Output

Architecture Agent Quality Checklist:
──────────────────────────────────────────────────────

☐ Completeness
   ☐ All requirements allocated to components (100% coverage)
   ☐ All components have interface definitions (C header files)
   ☐ All major decisions documented in ADRs

☐ Correctness
   ☐ PlantUML diagrams compile without errors
   ☐ Function signatures type-safe (matching header files)
   ☐ No cyclic dependencies detected

☐ Traceability
   ☐ SWE → Component links documented (traceability matrix)
   ☐ @implements tags in interface headers

☐ Safety
   ☐ ASIL-B components annotated (@safety_class)
   ☐ Safety components isolated from QM (if mixed criticality)

☐ Consistency
   ☐ Interfaces consistent across components
   ☐ Data types, units, error codes standardized

Verdict:
  [PASS]: Submit SAD for human review
  [FAIL]: Fix issues, re-run checklist

Escalation Triggers

When Architecture Agent Must Escalate

1. Architectural Decision Required [ESCALATION]

  • Trigger: Multiple valid architecture options (e.g., AUTOSAR Classic vs Adaptive)
  • Action: Generate ADR with pros/cons, escalate to architect
  • Example: See ADR-003 template in Step 4

2. Resource Constraint Violation [ESCALATION]

  • Trigger: Estimated memory/CPU usage exceeds budget
  • Action: Escalate to architect with mitigation options
  • Example: 
    [ESCALATION] ESCALATION: Memory Budget Exceeded
Estimated RAM usage: 2.5 MB (budget: 2.0 MB)
Options:
  A) Reduce Kalman filter state vector size (10 → 5 states)
  B) Use fixed-point arithmetic (float32 → int16)
  C) Upgrade to larger ECU (cost: +€15 per unit)
Assignee: @architect

3. Safety Segregation Issue [ESCALATION]

  • Trigger: ASIL-B and QM components share memory/resources (ISO 26262 violation)
  • Action: Escalate to safety engineer
  • Example: 
    [ESCALATION] ESCALATION: Safety Segregation Violation
Issue: ACC_Controller (ASIL-B) and HMI (QM) share CAN buffer (no memory protection)
ISO 26262 Part 6 requires: Freedom from interference between safety/non-safety functions
Mitigation: Use MPU (Memory Protection Unit — hardware that restricts which memory addresses each software partition can access) or separate CAN controllers
Assignee: @safety_engineer

4. Cyclic Dependency Detected [ESCALATION]

  • Trigger: Component A depends on B, B depends on A (architectural flaw)
  • Action: Escalate to architect
  • Example: 
    [ESCALATION] ESCALATION: Cyclic Dependency
Cycle detected: ACC_Controller → Diagnostics → ACC_Controller
Suggests: Introduce Diagnostics_Interface layer to break cycle
Assignee: @architect

Examples

Complete Architecture Agent Workflow

Input: Software Requirements Specification (34 requirements)

Output 1: Software Architecture Document (SAD)

  • 5 components identified (ACC_Controller, CAN_Driver, Sensor_Fusion, HMI, Diagnostics)
  • C4 component diagram generated (PlantUML)
  • 23 API functions defined (C header files)

Output 2: Architecture Decision Records (ADRs)

  • ADR-003: AUTOSAR Classic vs Adaptive (Classic selected)
  • ADR-007: CAN vs Ethernet (CAN selected, lower cost)
  • ADR-012: PID vs MPC controller (PID selected, simpler)

Output 3: Traceability Matrix

  • 100% SWE → Component coverage (34/34 requirements)
  • Excel file: Traceability_Matrix_SWE_Component.xlsx

Output 4: Validation Report

  • [PASS] No cyclic dependencies
  • [PASS] Interface type consistency: 100%
  • [PASS] Memory budget: 1.8 MB / 2.0 MB (90% utilization)

Output 5: Pull Request

  • Branch: feature/swe2-architecture
  • Files: SAD.md, ADR-003.md, ADR-007.md, ADR-012.md, *.h (header files)
  • Assignee: @architect (human review)
  • Status: Awaiting ADR approval

Human Review Time: 3 hours (baseline: 12 hours manual) → 75% time savings

Summary

Architecture Agent Key Responsibilities:

  1. Identify Components: Group requirements by cohesion (functional, data, interface)
  2. Design Architecture: Generate C4 diagrams (PlantUML), component interfaces (C headers)
  3. Document Decisions: Create ADRs for major architectural choices (escalate for approval)
  4. Allocate Requirements: Map SWE requirements → components (100% coverage)
  5. Validate Consistency: Check cyclic dependencies, interface types, resource constraints

Escalation: Architectural decisions, resource violations, safety segregation, cyclic dependencies

Success Metrics: 80-90% ADR approval, 85-95% UML accuracy, 95-100% interface validation

Previous
Requirements Agent Instructions
Next
Implementation Agent Instructions