diff --git a/ASG_Framework.md b/ASG_Framework.md index f965248..e41cb31 100644 --- a/ASG_Framework.md +++ b/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
Retail shop user] + roleR[Retailer
Catalog manager] + system[(sommpanion
System)] + extDB[(Wine Data Service)] + extNats[NATS
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
Retail shop user] + roleR[Retailer
Catalog manager] + system[(sommpanion
System)] + extDB[(Wine Data Service)] + extNats[NATS
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
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