update

ASG_Framework.md

@@ -485,6 +485,18 @@ Each documentation artifact has associated KPIs. Track these to ensure quality:
 | Implementation | Implementation coverage | 100% of validation tests mapped to at least one task |
 | Runbook | MTTR | <15 minutes for P1 incidents |
 
+### Delivery & Outcome Metrics
+
+The table above measures documentation adherence. This group measures the *actual system and how fast the team ships* — the axes doc-compliance never could. DORA is the delivery bundle; the Outcome row is the post-deploy business KPI (KPI-XXX) defined per requirement in `1-requirements.md`.
+
+| Category | KPI | Source |
+|----------|-----|--------|
+| Delivery (DORA) | Lead time for changes — median time from commit to production deploy | CI/CD pipeline |
+| Delivery (DORA) | Deployment frequency — deployments per unit time | CI/CD pipeline |
+| Delivery (DORA) | Change failure rate — % of deploys requiring rollback or fix | CI/CD pipeline |
+| Delivery (DORA) | MTTR — mean time to recover from a production incident | CI/CD pipeline (see Runbook MTTR KPI) |
+| Outcome | Post-deploy business KPI — whether a feature achieves its goal after release | `1-requirements.md` KPI-XXX |
+
 **Review Cadence**:
 - Weekly: Review KPI dashboards and documentation gaps
 - Monthly: Update documentation based on incident learnings
@@ -544,6 +556,26 @@ These rules serve as a binary decision framework:
 - **NFR-XXX**: [Deployment-specific requirement]
 - *Example: NFR-501 - System shall be deployed to MicroK8s cluster with relative URL support*
 
+### System Context (C4 Level 1)
+
+Show the system as a black box and the people and external systems around it. This diagram is the visual form of the In Scope / Out of Scope / Dependencies statements above: it fixes scope for sign-off and shows only what touches the system.
+
+```mermaid
+%% C4 Level 1 - System Context
+flowchart LR
+    roleC[Customer<br/>Retail shop user]
+    roleR[Retailer<br/>Catalog manager]
+    system[(sommpanion<br/>System)]
+    extDB[(Wine Data Service)]
+    extNats[NATS<br/>Messaging Broker]
+
+    roleC -->|views catalog, selects wines| system
+    roleR -->|manages wine catalog| system
+    system -->|reads master wine data| extDB
+    system -->|publishes catalog updates| extNats
+    extNats -->|pushes inventory notifications| roleR
+```
+
 ## 3. Functional Requirements (FR)
 
 ### FR-XXX: [Requirement Title]
@@ -638,17 +670,41 @@ Explain the design reasoning behind each major decision — why the solution was
 
 ## 4. High-Level Component Diagram
 
+### C4 Level 1 - System Context
+
+The scope boundary for sign-off: the system as a black box plus the people and external systems it interacts with. Mirrors the walkthrough's System Context and the Requirements diagram; keep this one stable so downstream docs can reference it.
+
 ```mermaid
-%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#3b82f6'}}}%%
-flowchart TD
-    A[User] --> B[Comparison UI]
-    B --> C[Comparison State]
-    B --> D[Wine API]
-    C --> D
+%% C4 Level 1 - System Context
+flowchart LR
+    roleC[Customer<br/>Retail shop user]
+    roleR[Retailer<br/>Catalog manager]
+    system[(sommpanion<br/>System)]
+    extDB[(Wine Data Service)]
+    extNats[NATS<br/>Messaging Broker]
+
+    roleC -->|views catalog, selects wines| system
+    roleR -->|manages wine catalog| system
+    system -->|reads master wine data| extDB
+    system -->|publishes catalog updates| extNats
+    extNats -->|pushes inventory notifications| roleR
+```
+
+### C4 Level 2 - Container
+
+The high-level tech stack and how the building blocks communicate. This is the architecture diagram the Solution Design's Decision Rationale (Section 3) explains — each container maps to a decision, and each decision maps back to a requirement.
+
+```mermaid
+%% C4 Level 2 - Container
+flowchart LR
+    user[Customer<br/>Browser SPA] -->|HTTPS| ssr[SvelteKit SSR API]
+    ssr -->|reads / writes| post[(PostgreSQL)]
+    ssr -->|publishes catalog:updates| nats[(NATS)]
+    nats -->|pushes updates| dash[Retailer Dashboard]
 ```
 
 **Component Descriptions**:
-- **[Component Name]**: [Brief description of responsibilities and how it solves part of the problem]
+- **[Container Name]**: [Brief description of the container's responsibilities and how it solves part of the problem]
   - Links to requirements: FR-001, NFR-201
 
 ## 5. Alternatives Considered