ton/ASG_Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
narawat
2026-05-19 15:33:18 +07:00
parent 003c2d952f
commit 31cad17f91
1 changed files with 48 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
ASG_Framework.md
View File

@@ -10,7 +10,7 @@ This document defines the documentation framework for a software project. It est
|----------|---------|-----------------|------------------|------------------------|-------------------| |----------|---------|-----------------|------------------|------------------------|-------------------|
| **Requirements** | Capture the **business intent** — why we're building this and what success looks like. Defines boundaries and user-visible outcomes. | Stakeholders, Product Owners, Lead Developers | User stories, PRDs, acceptance criteria, non-functional constraints. | "System must process tabular data from Julia to SvelteKit UI with <200ms latency for 5-member teams." | 95% of requests complete <200ms (synthetic monitoring). | | **Requirements** | Capture the **business intent** — why we're building this and what success looks like. Defines boundaries and user-visible outcomes. | Stakeholders, Product Owners, Lead Developers | User stories, PRDs, acceptance criteria, non-functional constraints. | "System must process tabular data from Julia to SvelteKit UI with <200ms latency for 5-member teams." | 95% of requests complete <200ms (synthetic monitoring). |
| **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. | | **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). | | **Specification** | The **technical contract** — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. Maps technical implementation to both *what* (requirements) and *how* (solution design). | Developers, QA Engineers, CI/CD pipelines | OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes. | `contract.yaml` defining a NATS subject (solution-design SD-3.1) that accepts Arrow streams with snake_case headers (requirements FR-001). | 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). | | **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 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. | | **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 Plan** | The **execution roadmap** — how implementation is organized, prioritized, and delivered. Maps code to spec and validates against specification. | Developers, Project Managers, Lead Developers | Implementation plan, module breakdown, task list, delivery timeline, test strategy. | Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation. | 100% of specification sections mapped to implementation tasks, <10% timeline drift. | | **Implementation Plan** | The **execution roadmap** — how implementation is organized, prioritized, and delivered. Maps code to spec and validates against specification. | Developers, Project Managers, Lead Developers | Implementation plan, module breakdown, task list, delivery timeline, test strategy. | Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation. | 100% of specification sections mapped to implementation tasks, <10% timeline drift. |
@@ -69,6 +69,7 @@ This document defines the documentation framework for a software project. It est
- Decision rationale: Explain why each major decision was made (e.g., "Chose NATS over Kafka for simpler ops", "Used server-side rendering for SEO") - Decision rationale: Explain why each major decision was made (e.g., "Chose NATS over Kafka for simpler ops", "Used server-side rendering for SEO")
- Risk assessment: Identify potential risks and how they will be mitigated - Risk assessment: Identify potential risks and how they will be mitigated
- Traceability: Link each solution component to specific requirement ID(s) (e.g., FR-001, NFR-201) that it addresses - Traceability: Link each solution component to specific requirement ID(s) (e.g., FR-001, NFR-201) that it addresses
- Solution Design IDs: Assign unique IDs to major decisions (e.g., SD-2.1 for "Use NATS for async messaging") to enable specification traceability
**Best Practices**: **Best Practices**:
- Write solution design from the user's perspective first, then justify technical choices - Write solution design from the user's perspective first, then justify technical choices
@@ -101,7 +102,10 @@ This document defines the documentation framework for a software project. It est
- Error codes and their meanings - Error codes and their meanings
- Data validation rules and constraints - Data validation rules and constraints
- Rate limiting and quota definitions - Rate limiting and quota definitions
- Each specification item must cite the specific requirement ID(s) from requirements.md (for example, FR-001, NFR-201). Link each endpoint, schema, validation rule, error case, etc to the exact requirement(s) it implements or satisfies. - Each specification item must cite:
- **Requirement ID(s)** from requirements.md (e.g., FR-001, NFR-201) — defines *what* the system must do
- **Solution Design reference(s)** from solution-design.md (e.g., SD-2.1, SD-3.3) — defines *how* and *why* this technical approach was chosen
- Link each endpoint, schema, validation rule, error case, etc to the exact requirement(s) and solution design decision(s) it implements or satisfies.
**Best Practices**: **Best Practices**:
- Use formal specification languages (OpenAPI 3.0+, AsyncAPI) - Use formal specification languages (OpenAPI 3.0+, AsyncAPI)
@@ -238,7 +242,11 @@ The walkthrough functions as a collaborative audit, mapping the proposed solutio
- Integration test suites - Integration test suites
- Schema validation jobs - Schema validation jobs
- Security scanning and audit jobs - Security scanning and audit jobs
- Each validation must include explicit references to requirements.md (e.g., FR-001, NFR-201), specification.md (exact spec IDs or paths — API contracts, data schemas, e.g., sections 3.1, 4.2), and ui-specification.md (components, interactions, visual states, e.g., sections 15.1, 15.3) as applicable. - Each validation must include explicit references to:
- requirements.md (e.g., FR-001, NFR-201) — business intent
- solution-design.md (e.g., SD-2.1, SD-3.3) — architectural decisions
- specification.md (exact spec IDs or paths — API contracts, data schemas, e.g., sections 3.1, 4.2) — technical rules
- ui-specification.md (components, interactions, visual states, e.g., sections 15.1, 15.3) — UI contract
**Best Practices**: **Best Practices**:
- Fail CI on specification violations - Fail CI on specification violations
@@ -298,9 +306,11 @@ Once requirements are stable, translate them into an viable solution. This ensur
### 3. Define the Specification ### 3. Define the Specification
With solution design in place, define the technical specification. This becomes the contract for implementation. With solution design in place, define the technical specification. This becomes the contract for implementation. Each specification item must trace to **both**:
- **Requirements** (WHAT - business intent)
- **Solution Design** (HOW/WHY - architectural decisions)
**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format) and `error-codes.md`. **Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format), `error-codes.md`, and traceability mappings to requirements.md and solution-design.md.
### 4. Define UI Specification Early ### 4. Define UI Specification Early
@@ -357,7 +367,9 @@ Since all docs defined in the ASG Framework are **living documents** that evolve
1. **Requirements Review**: After writing requirements, ask "What happens if X?" for each user story 1. **Requirements Review**: After writing requirements, ask "What happens if X?" for each user story
2. **Solution Design Review**: After writing solution design, verify every requirement is addressed by at least one solution component with a corresponding requirement ID reference 2. **Solution Design Review**: After writing solution design, verify every requirement is addressed by at least one solution component with a corresponding requirement ID reference
3. **Specification Review**: After writing the spec, verify every requirement has at least one rule with a corresponding requirement ID reference 3. **Specification Review**: After writing the spec, verify every spec item has:
- At least one requirement ID reference (WHAT)
- At least one solution design reference (HOW/WHY)
4. **UI Specification Review**: After writing UI Specification, verify every spec rule has at least one UI representation 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 5. **Walkthrough Review**: After writing walkthrough, verify every UI step has a corresponding backend flow
@@ -371,7 +383,7 @@ This habit ensures that each documentation stage is complete and validated befor
|-------|-----------------|----------------| |-------|-----------------|----------------|
| **Requirements** | If I can't state the Value, I'm building a feature nobody needs. | Clarifies the business impact before technical discussion begins | | **Requirements** | If I can't state the Value, I'm building a feature nobody needs. | Clarifies the business impact before technical discussion begins |
| **Solution Design** | If I can't Imagine the solution, I'm building without a compass. | Ensures the technical approach solves the user problem before spec writing | | **Solution Design** | If I can't Imagine the solution, I'm building without a compass. | Ensures the technical approach solves the user problem before spec writing |
| **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 | | **Specification** | If I can't write a Rule with a requirement ID reference AND/OR solution design reference, I haven't thought the logic through. | Ensures traceability from technical rules to both business requirements (*what*) and architectural decisions (*how/why*) |
| **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 | | **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 | | **Walkthrough** | If I can't Trace the full flow, the system has a 'broken bridge'. | Identifies gaps between components before implementation begins |
@@ -543,15 +555,15 @@ Identify potential risks and mitigation strategies.
## 7. Requirements Traceability ## 7. Requirements Traceability
Link each solution component to specific requirements. Link each solution component to specific requirements and assign Solution Design IDs for specification traceability.
| Solution Component | Requirement ID | Description | | Solution Component | Requirement ID | Solution Design ID | Description |
|-------------------|----------------|-------------| |-------------------|----------------|-------------------|-------------|
| Comparison table UI | FR-101 | Display wines in table format | | Comparison table UI | FR-101 | SD-2.1 | Display wines in table format |
| Filtering | FR-102 | Filter wines by criteria | | Filtering | FR-102 | SD-2.2 | Filter wines by criteria |
| Sorting | FR-103 | Sort wines by any column | | Sorting | FR-103 | SD-2.3 | Sort wines by any column |
| Real-time updates | NFR-201 | Updates appear within 100ms | | Real-time updates | NFR-201 | SD-2.4 | Updates appear within 100ms |
| Export comparison | FR-201 | Export comparison to PDF/CSV | | Export comparison | FR-201 | SD-2.5 | Export comparison to PDF/CSV |
### Specification Template ### Specification Template
@@ -562,7 +574,7 @@ openapi: 3.0.0
info: info:
title: NATSBridge API title: NATSBridge API
version: 1.0.0 version: 1.0.0
description: Technical specification with requirements traceability description: Technical specification with requirements and solution design traceability
paths: paths:
/api/v1/endpoint: /api/v1/endpoint:
post: post:
@@ -578,7 +590,8 @@ paths:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/Response' $ref: '#/components/schemas/Response'
x-requirement-id: FR-001 # Reference to Requirements document x-requirement-id: FR-001 # Reference to Requirements document (WHAT)
x-solution-design-ref: SD-3.1 # Reference to Solution Design decision (HOW/WHY)
components: components:
schemas: schemas:
Request: Request:
@@ -586,13 +599,15 @@ components:
properties: properties:
data: data:
type: string type: string
x-requirement-id: FR-002 # Reference to Requirements document x-requirement-id: FR-002 # Reference to Requirements document (WHAT)
x-solution-design-ref: SD-3.2 # Reference to Solution Design decision (HOW/WHY)
Response: Response:
type: object type: object
properties: properties:
status: status:
type: string type: string
x-requirement-id: FR-003 # Reference to Requirements document x-requirement-id: FR-003 # Reference to Requirements document (WHAT)
x-solution-design-ref: SD-3.1 # Reference to Solution Design decision (HOW/WHY)
``` ```
### UI Specification Template ### UI Specification Template
@@ -606,9 +621,9 @@ components:
**Version**: 1.0.0 **Version**: 1.0.0
## Requirements Traceability ## Requirements Traceability
| UI Element | Requirement ID | Description | | UI Element | Requirement ID | Solution Design Ref | Description |
|------------|----------------|-------------| |------------|----------------|---------------------|-------------|
| Login form | FR-001 | Username/password authentication | | Login form | FR-001 | SD-2.1 | Username/password authentication |
| Sidebar menu | NFR-202 | Collapsible sidebar for usability | | Sidebar menu | NFR-202 | Collapsible sidebar for usability |
| Wine table | FR-101 | Sortable, searchable inventory table | | Wine table | FR-101 | Sortable, searchable inventory table |
@@ -657,19 +672,19 @@ flowchart TD
``` ```
**Specification Traceability:** **Specification Traceability:**
| Architecture Component | Specification Section | UI Specification Section | Requirement ID | | Architecture Component | Solution Design Ref | Specification Section | UI Specification Section | Requirement ID |
|------------------------|----------------------|--------------------------|----------------| |------------------------|---------------------|----------------------|--------------------------|----------------|
| NATS Bridge (smartsend) | specification.md:3.1 | - | FR-301, NFR-201 | | NATS Bridge (smartsend) | SD-3.1 | specification.md:3.1 | - | FR-301, NFR-201 |
| Login Form | specification.md:10.1 | ui-specification.md:15.2.1 | FR-001, NFR-201 | | Login Form | SD-2.1 | specification.md:10.1 | ui-specification.md:15.2.1 | FR-001, NFR-201 |
| Wine Inventory Table | specification.md:4.2 | ui-specification.md:15.3.3 | FR-101, NFR-205 | | Wine Inventory Table | SD-2.2 | specification.md:4.2 | ui-specification.md:15.3.3 | FR-101, NFR-205 |
| Sidebar Menu | specification.md:11.1 | ui-specification.md:15.3.2 | NFR-202 | | Sidebar Menu | SD-2.3 | specification.md:11.1 | ui-specification.md:15.3.2 | NFR-202 |
**Component Details:** **Component Details:**
- **Caddy**: Static file serving (specification.md:2.2, ui-specification.md:15.1) - **Caddy**: Static file serving (specification.md:2.2, ui-specification.md:15.1, solution-design.md:SD-1.1)
- **Node.js API**: NATS bridge client (specification.md:3.1) - **Node.js API**: NATS bridge client (specification.md:3.1, solution-design.md:SD-3.1)
- **Julia Worker**: Backend processing (specification.md:4.1) - **Julia Worker**: Backend processing (specification.md:4.1, solution-design.md:SD-4.1)
- **NATS Cluster**: Message bus (specification.md:3.3) - **NATS Cluster**: Message bus (specification.md:3.3, solution-design.md:SD-3.3)
- **Storage**: Data persistence (specification.md:5.1) - **Storage**: Data persistence (specification.md:5.1, solution-design.md:SD-5.1)
### Runbook Template ### Runbook Template