From de2ce38eb90a4173470d6055873bb19ddfda7f73 Mon Sep 17 00:00:00 2001 From: narawat Date: Tue, 19 May 2026 08:22:38 +0700 Subject: [PATCH] update --- ASG_Framework.md | 87 +++++++++++++++++++----------------------------- 1 file changed, 34 insertions(+), 53 deletions(-) diff --git a/ASG_Framework.md b/ASG_Framework.md index d8bf885..b769dd1 100644 --- a/ASG_Framework.md +++ b/ASG_Framework.md @@ -4,7 +4,7 @@ This document defines the documentation framework for a software project. It est --- -## The ASG Framework: Nine Pillars of Documentation +## The ASG Framework: Eight Pillars of Documentation | Document | Purpose | Primary Audience | Format / Content | Example (SaaS Context) | Measurement (KPI) | |----------|---------|-----------------|------------------|------------------------|-------------------| @@ -12,8 +12,8 @@ This document defines the documentation framework for a software project. It est | **Solution Design** | Translate requirements into an **viable solution** — how the system solves the user problem. Defines approach, components, and trade-offs before technical details. | Product Owners, Architects, Developers | Problem decomposition, solution approach, alternatives considered, high-level component diagram, decision rationale. | "Problem: Users need to compare wines. Solution: Build a comparison table with filtering, sorting, and visual comparison. Components: Data layer (Wine API), UI layer (Table component), Logic layer (Filter/Sort engine)." | 100% of user problems mapped to solution components before spec writing. | | **Specification** | The **technical contract** — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. | Developers, QA Engineers, CI/CD pipelines | OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes. | `contract.yaml` defining a NATS subject that accepts Arrow streams with snake_case headers. | 100% of messages validated against spec (CI block rate). | | **UI Specification** | The **design contract** — precise rules for UI components, interactions, and visual patterns. Ensures consistency across design and implementation. | Product Designers, Frontend Developers, QA Engineers | Component libraries, style guides, interaction specs, design tokens. | Atomic design system with Figma tokens synced to CSS variables. | 100% of UI components match design spec (visual regression tests). | -| **Walkthrough** | The **end-to-end trace** — maps the entire system flow from startup to cycle completion. Provides a "big picture" view that aligns users and developers, exposing architectural gaps before coding begins. | Product Owners, Architects, Developers | End-to-end user journey, sequence diagrams, state machine diagrams. Explicitly links to specification.md and ui-specification.md. | "User logs in → selects wine → edits details → saves → backend validates against spec → UI updates with error states." | 100% of user journeys traced across all layers before implementation starts. | -| **Architecture** | The **blueprint** — how components fit together, interact, and scale. Guides system structure and trade-offs. | Architects, Senior Developers, DevOps | C4 diagrams, Mermaid.js, component/network/storage models. | Diagram showing 6-node cluster routing traffic via Caddy → Node.js API → Julia pods. | 100% of major decisions logged with trade-off analysis. | +| **Walkthrough** | The **end-to-end trace** — maps the entire system flow from startup to cycle completion. Provides a "big picture" view that validates solution design before technical specification is locked. | Product Owners, Architects, Developers | End-to-end user journey, sequence diagrams, state machine diagrams. Explicitly links to specification.md and ui-specification.md. | "User logs in → selects wine → edits details → saves → backend validates against spec → UI updates with error states." | 100% of user journeys traced across all layers before implementation starts. | + | **Implementation** | The **real code** — business logic, helpers, tests, configs. Where design becomes executable. | Developers, Code Reviewers | Source code, README.md, unit tests, setup scripts. | Julia function for matrix calculation + SvelteKit component rendering table. | >80% unit test coverage, <5% drift from spec. | | **Validation** | The **enforcer** — ensures implementation matches the spec. Blocks drift and human error. | Automation servers, QA, Lead Developers | CI jobs, contract tests, linting, integration checks. | CI job rejects PR with camelCase field not allowed by YAML spec. | <1% of PRs bypass validation gates. | | **Runbook** | The **operational manual** — how the system lives in production, scales, and recovers. Guides on-call engineers. | DevOps, SREs, On-call Developers | K8s manifests, Helm charts, Markdown guides. Deployment, scaling, backup/restore, troubleshooting. | GitOps manifest ensuring 6 Julia replicas restart if memory >80%. | MTTR <15 minutes for P1 incidents. | @@ -147,14 +147,33 @@ This document defines the documentation framework for a software project. It est ### 5. Walkthrough `walkthrough.md` -**Purpose**: The *end-to-end trace* — maps the entire system flow from startup to cycle completion, incorporating both internal logic and external interactions. Provides a "big picture" view that aligns users and developers, exposing architectural gaps before coding begins. +**Purpose**: The *end-to-end trace* — maps the entire system flow from startup to cycle completion, incorporating both internal logic and external interactions. Provides a "big picture" view that aligns users and developers, validating the solution design before technical specification is locked. + +**Unified Lifecycle Review** +The walkthrough functions as a collaborative audit, mapping the proposed solution directly onto your workflow to ensure a shared "single source of truth." It synchronizes the user's operational needs with the developer's technical implementation. + +**For the User: Validating Operational Utility** +- **Visual Fidelity**: Concrete demonstration of the UI and user-facing components +- **Workflow Integration**: Clear mapping of how the tool fits into existing day-to-day operations +- **Operational Control**: Practical exposure to system controls and interaction patterns +- **Outcome Verification**: Direct observation of the system's outputs and deliverables +- **Impact Assessment**: Data-driven evaluation of the solution's ROI and efficiency gains +- **Expectation Alignment**: Early discovery of discrepancies between intended functionality and actual experience + +**For the Developer: Aligning Architecture with Reality** +- **Requirement Validation**: Confirming the solution satisfies core business objectives +- **Impact Analysis**: Assessing the solution's real-world behavioral performance +- **Knowledge Synthesis**: Identifying disconnects between domain intent and technical interpretation +- **Specification Refinement**: Spotting missing technical dependencies or edge cases +- **System Harmony**: Observing how the technical workflow and the user process interleave +- **Code-to-Process Mapping**: Refining abstraction layers to better reflect the user's actual sequence of events **Why It Matters**: - Serves as a single source of truth for system behavior, bridging user experience and technical implementation - Validates that all components (UI, API, backend logic) work together cohesively before implementation begins -- Exposes architectural gaps and integration risks early in the design phase +- Exposes solution design gaps and integration risks early in the design phase - Aligns stakeholders (product, design, development) on the complete user journey -- Provides a reference for verifying implementation against intended behavior +- Provides a reference for verifying implementation against intended behavior and for tracing requirements through to architecture **Content Guidelines**: - End-to-end user journey from system startup to task completion @@ -171,41 +190,11 @@ This document defines the documentation framework for a software project. It est - Link each step to its corresponding specification and UI spec sections - Document failure modes and recovery paths - Keep walkthroughs updated as requirements evolve -- Review walkthroughs against architecture to verify feasibility +- Review walkthroughs against the solution design to verify completeness --- -### 6. Architecture -`architecture.md` - -**Purpose**: The *blueprint* — how components fit together, interact, and scale. Guides system structure and trade-offs. - -**Why It Matters**: -- Provides a mental model for system design -- Guides technical decision-making and trade-off analysis -- Facilitates onboarding of new architects and senior developers -- Documents scaling and performance considerations -- Enables traceability from technical specifications and UI specifications to architectural decisions - -**Content Guidelines**: -- C4 diagrams (Context, Container, Component levels) -- Mermaid.js flowcharts for sequence diagrams -- Component interaction diagrams -- Network topology and data flow -- Storage and caching strategies -- Scaling and resilience patterns -- Each architecture component must cite the exact specification ID(s) or spec path(s) in specification.md and/or the UI‑spec artifact ID(s) or path(s) in ui-specification.md that it implements or depends on. - -**Best Practices**: -- Use diagrams that are easy to update (Mermaid.js over static images) -- Document trade-off decisions with Rationale Documents -- Include scaling considerations for each component -- Document failure modes and recovery strategies -- Keep architecture diagrams versioned with code - ---- - -### 7. Implementation +### 6. Implementation **Purpose**: The *real code* — business logic, helpers, tests, configs. Where design becomes executable. @@ -232,7 +221,7 @@ This document defines the documentation framework for a software project. It est --- -### 8. Validation +### 7. Validation `validation.md` **Purpose**: The *enforcer* — ensures implementation matches the spec. Blocks drift and human error. @@ -261,7 +250,7 @@ This document defines the documentation framework for a software project. It est --- -### 9. Runbook +### 8. Runbook `runbook.md` **Purpose**: The *operational manual* — how the system lives in production, scales, and recovers. Guides on-call engineers. @@ -326,25 +315,19 @@ As soon as the UI specification is defined, create walkthroughs. This helps iden **Action**: Create `docs/walkthrough/` with `TOUR.md`, sequence diagrams, and cross-references to specification and UI spec sections. -### 6. Design the Architecture - -With requirements, solution design, specification, UI spec, and walkthrough in place, design the architecture. Document trade-off decisions explicitly. - -**Action**: Create `docs/architecture/` with Mermaid diagrams and `trade-offs.md`. - -### 7. Implement with Validation in Mind +### 6. Implement with Validation in Mind Write implementation code that adheres to the specification. Build validation into the CI pipeline from day one. **Action**: Ensure test files are co-located with implementation and run on every commit. -### 8. Automate Validation +### 7. Automate Validation Build automated validation that runs in CI/CD. This ensures spec compliance and prevents drift. **Action**: Configure CI jobs to validate against specification and block PRs on violations. -### 9. Document Operations from Day One +### 8. Document Operations from Day One Create runbook entries as soon as deployment procedures are established. Update them when incidents occur. @@ -362,13 +345,13 @@ Since all docs defined in the ASG Framework are **living documents** that evolve | **Solution Design → Specification** | Turn a "Solution" into a "Contract" | Does the Specification define all technical details that the solution approach requires? | Solution design says "use caching for performance", but Specification doesn't define cache invalidation strategy | Add cache TTL, invalidation rules, and error handling to Specification | | **Specification → UI Specification** | Turn a "Rule" into a "Button" | Does the UI Specification expose all the data and states defined in the Specification? | Specification says device must "Handshake" within 5 seconds, but UI Specification has no connection status indicator | Add a `Connection Status` component to UI Specification | | **UI Specification → Walkthrough** | Turn "Screens" into a "Story" | Does the Walkthrough reflect the complete flow including error states and timing? | Walkthrough shows "Success" screen, but Specification says backend process takes 2 minutes | Add a `Processing` state to UI Specification and `JobStatus` field to Specification | -| **Walkthrough → Architecture** | Turn the "Story" into "Steel" | Does the Architecture support the performance and integration requirements defined in the Walkthrough? | Walkthrough shows 10 IoT sensors sending real-time updates, but Architecture uses REST API | Switch to NATS/MQTT for high-frequency data flow | +| **Walkthrough → Specification** | Turn the "Story" into "Rules" | Does the Specification cover all the behaviors defined in the Walkthrough? | Walkthrough shows 10 IoT sensors sending real-time updates, but Specification only defines REST API | Add NATS/MQTT protocol definitions to Specification | ### Why Gap-Checks Matter - **Prevent rework**: Catch missing requirements before coding begins - **Ensure completeness**: Verify all scenarios are covered across all layers -- **Validate feasibility**: Confirm architectural decisions support the intended user flow +- **Validate feasibility**: Confirm technical approach supports the intended user flow - **Maintain alignment**: Keep all stakeholders (product, design, dev) on the same page ### How to Run Gap-Checks @@ -378,7 +361,6 @@ Since all docs defined in the ASG Framework are **living documents** that evolve 3. **Specification Review**: After writing the spec, verify every requirement has at least one rule with a corresponding requirement ID reference 4. **UI Specification Review**: After writing UI Specification, verify every spec rule has at least one UI representation with a corresponding requirement ID reference 5. **Walkthrough Review**: After writing walkthrough, verify every UI step has a corresponding backend flow -6. **Architecture Review**: After designing architecture, verify every walkthrough flow is technically feasible and every architecture decision references specification and UI specification sections --- @@ -393,7 +375,6 @@ This habit ensures that each documentation stage is complete and validated befor | **Specification** | If I can't write a Rule with a requirement ID reference, I haven't thought the logic through. | Ensures traceability from technical rules to business requirements | | **UI Specification** | If I can't See it with a requirement ID reference, the user has no way to trigger the logic. | Ensures traceability from UI elements to business requirements | | **Walkthrough** | If I can't Trace the full flow, the system has a 'broken bridge'. | Identifies gaps between components before implementation begins | -| **Architecture** | If the Walkthrough doesn't Require it, or if I can't trace spec/UI-spec references, I'm over-engineering or missing requirements. | Ensures traceability from architecture to spec/UI-spec and requirements | **How to Use This Habit:**