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

update

Browse Source
This commit is contained in:
narawat
2026-09-08 16:05:43 +07:00
parent f560951379
commit 9de603d8ea
2 changed files with 156 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ASG_Framework.md
+138 -143
View File
@@ -9,9 +9,9 @@ This document defines the documentation framework for a software project. It est
| Document | Purpose | Primary Audience | Format / Content | Example (SaaS Context) | Measurement (KPI) |
|----------|---------|-----------------|------------------|------------------------|-------------------|
| **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)." | 0 solution components without a requirement ID reference. |
| **Walkthrough** | The **end-to-end trace** — maps the entire system flow from startup to cycle completion for each participant. Provides a "big picture" view that validates solution design before technical specification is locked. | Product Owners, Architects, Developers, End Users | Per-participant sections, sequence diagrams, state machine diagrams. Explicitly links to solution-design.md and requirements.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. |
| **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). |
| **Solution Design** | Translate requirements into **a 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, decision rationale, high-level component diagram, alternatives considered. | "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)." | 0 solution components without a requirement ID reference. |
| **Walkthrough** | The **end-to-end trace** — maps the entire system flow from startup to cycle completion for each participant. Provides a "big picture" view that validates solution design before technical specification is locked. | Product Owners, Architects, Developers, End Users | Per-participant sections, sequence diagrams, state machine diagrams. Explicitly links to `2-solution_design.md` and `1-requirements.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. |
| **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-001.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). |
| **Validation** | The **enforcer** — defines tests before implementation begins to ensure spec compliance. Blocks drift and human error. | QA Engineers, Developers, Automation servers | Unit tests, integration tests, performance tests, penetration tests, contract tests, CI jobs, linting rules, schema validation. | CI job rejects PR with camelCase field not allowed by YAML spec. | <1% of PRs bypass validation gates. |
| **Implementation Plan** | The **execution roadmap** — how implementation is organized, prioritized, and delivered. Maps code to validation tests and 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 validation tests covered by implementation tasks, <10% timeline drift. |
@@ -42,7 +42,7 @@ This document defines the documentation framework for a software project. It est
- Boundary definitions that state what is in scope and out of scope.
- Security requirements including threat model outcomes, authentication and authorization expectations, data classification, encryption requirements, and compliance controls.
- Observability requirements specifying required telemetry, metrics, traces, logs, alerting thresholds, and retention policies.
- Traceability Rule: Requirements must be self-contained (no cross-references to other docs as justification), but must include IDs (e.g., FR-001) so downstream artifacts (spec, UI spec, architecture) can trace back. All downstream documents MUST cite requirement IDs, but requirements themselves stand alone.
- Traceability Rule: Requirements must be self-contained (no cross-references to other docs as justification), but must include IDs (e.g., FR-001) so downstream artifacts (spec, UI spec, architecture) can trace back. All downstream documents MUST cite requirement IDs, but requirements themselves stand alone. Walkthrough steps (WT-XXX) may also cite requirement IDs directly.
**Best Practices**:
- **Link each requirement to a measurable KPI** — functional requirements should have explicit KPIs; non-functional requirements should have measurable thresholds
@@ -55,7 +55,7 @@ This document defines the documentation framework for a software project. It est
### 2. Solution Design
`2-solution_design.md`
**Purpose**: Translate requirements into an *viable solution* — how the system solves the user problem. Defines approach, components, and trade-offs before technical details.
**Purpose**: Translate requirements into **a viable solution** — how the system solves the user problem. Defines approach, components, and trade-offs before technical details.
**Why It Matters**:
- Prevents technical-first thinking that skips design decisions
@@ -66,10 +66,10 @@ This document defines the documentation framework for a software project. It est
**Content Guidelines**:
- Problem decomposition: Break down the user problem into smaller, solvable pieces
- Solution approach: Describe the high-level approach (e.g., "Use event sourcing for audit trail", "Implement caching layer for performance")
- Alternatives considered: Document at least 2-3 alternative approaches with rationale for why they were rejected
- Solution approach: Introduce the solution the way Steve Jobs introduced the iPhone — present what you're delivering to the user first, then explain how it solves their problem. The narrative starts with the product, not the technical components. (e.g., "We're building a comparison table that lets users evaluate wines side-by-side with instant filtering and sorting" — not "We'll use event sourcing with a caching layer")
- Decision rationale: Explain the design reasoning behind each major decision — why the solution was designed this way, and how each decision connects to form a cohesive approach that solves the user problem. (e.g., "We chose server-side rendering so shared comparisons are indexable by search engines, enabling retailers to distribute links without login walls")
- High-level component diagram: Show major components and their relationships (not technical details, just the big picture)
- Decision rationale: Explain why each major decision was made (e.g., "Chose NATS over Kafka for simpler ops", "Used server-side rendering for SEO")
- Alternatives considered: Document at least 2-3 alternative approaches with rationale for why they were rejected
- 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
- Decision IDs: Assign unique IDs to major decisions using the format `SD-XXX` (e.g., `SD-001` for "Use NATS for async messaging") to enable specification traceability
@@ -80,7 +80,7 @@ This document defines the documentation framework for a software project. It est
- Use diagrams that are easy to update (Mermaid.js)
- Document trade-off decisions explicitly
- Review solution design against requirements to verify completeness
- Get sign-off from product, architecture, and engineering before creating walkthroughs
- Create walkthroughs to validate the solution design end-to-end; sign-off from product, architecture, and engineering happens after walkthroughs confirm the approach works
**Gap-Check Question**: Does the Solution Design clearly explain how the system solves the user problem, not just what it does?
@@ -89,20 +89,12 @@ This document defines the documentation framework for a software project. It est
---
### 3. Walkthrough
`3-walkthrough.md`
`3-walkthrough.md` (single file with per-participant sections)
**Primary Audience**: Product Owners, Architects, Developers, End Users
**Purpose**: The *end-to-end trace* — each section maps one system participant's complete journey from their own POV, from session start to task completion. Provides a "big picture" view that validates solution design before technical specification is locked. Each section is standalone: described entirely from that participant's perspective, with cross-references to other participants' sections where their workflows intersect.
**System Participants Overview**
| Participant | Section | Role | What It Shows |
|-------------|---------|------|---------------|
| **[Participant A Name]** | Participant A | [Brief role description] | [Key end-to-end journey summary] |
| **[Participant B Name]** | Participant B | [Brief role description] | [Key end-to-end journey summary] |
| **[Participant C Name]** | Participant C | [Brief role description] | [Key end-to-end journey summary] |
**Per-Participant Walkthroughs**
The walkthrough is organized as one document with a dedicated section per system participant, each tracing the complete journey from that participant's perspective.
- Traces the complete flow from that participant's login/session start to task completion and logout
@@ -127,12 +119,13 @@ The walkthrough is organized as one document with a dedicated section per system
- Error paths and edge cases specific to that participant's journey
- Sequence diagrams showing request/response patterns across participants for complex multi-user flows
- State machine diagrams for workflows that span multiple participants
- Each major walkthrough step must cite the exact **Solution Design decision ID(s)** (e.g., SD-001, SD-002) from `solution-design.md` and/or **Requirement ID(s)** from `requirements.md` that it implements or depends on.
- Each major walkthrough step must cite the exact **Solution Design decision ID(s)** (e.g., SD-001, SD-002) from `2-solution_design.md` and/or **Requirement ID(s)** from `1-requirements.md` that it implements or depends on.
- Assign a unique ID to each walkthrough step using the format `WT-XXX` (e.g., `WT-001` for Participant A login, `WT-002` for Participant B order placement) to enable downstream traceability
**Best Practices**:
- Write each section from one participant's perspective, then cross-reference other participants' sections
- Include concrete examples with realistic data values for each participant's typical usage
- Link each step to its corresponding Solution Design decision (SD-XXX IDs) and requirement IDs
- Link each step to its corresponding Solution Design decision (SD-XXX.Y IDs), Requirement ID(s), and Walkthrough ID (WT-XXX)
- Map cross-participant interactions explicitly (e.g., "Customer action X → Retailer notification Y")
- Document failure modes and recovery paths from each participant's perspective
- Keep walkthroughs updated as requirements and participant roles evolve
@@ -142,6 +135,7 @@ The walkthrough is organized as one document with a dedicated section per system
### 4. Specification
`4-specification.md`
**Purpose**: 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).
**Why It Matters**:
@@ -157,10 +151,11 @@ The walkthrough is organized as one document with a dedicated section per system
- Error codes and their meanings
- Data validation rules and constraints
- Rate limiting and quota definitions
- Assign a unique ID to each specification item using the format `SP-XXX` (e.g., `SP-001` for the Request schema, `SP-002` for POST endpoint) for downstream traceability
- 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.
- **Requirement ID(s)** from `1-requirements.md` (e.g., FR-001, NFR-201) — defines *what* the system must do
- **Solution Design reference(s)** from `2-solution_design.md` (e.g., SD-001.1, SD-002.1) — 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 it implements or satisfies.
**Best Practices**:
- Use formal specification languages (OpenAPI 3.0+, AsyncAPI)
@@ -190,7 +185,8 @@ The walkthrough is organized as one document with a dedicated section per system
- Design tokens (CSS variables, Figma tokens)
- Accessibility standards (WCAG compliance)
- Responsive design breakpoints and layouts
- Each UI specification artifact must cite the specific requirement ID(s) from requirements.md (for example FR-001, NFR-201) and/or the exact specification ID(s) or spec path(s) from specification.md that it implements or depends on.
- Each UI specification artifact must cite the specific requirement ID(s) from `1-requirements.md` and/or the exact solution design decision ID(s) from `2-solution_design.md` that it implements or depends on
- Assign a unique ID to each UI artifact using the format `UI-XXX` (e.g., `UI-001` for Login Form, `UI-002` for Wine Table) to enable downstream traceability
**Best Practices**:
- Use design systems with versioned component libraries
@@ -217,7 +213,7 @@ Because implementation must satisfy specifications, Validation derives all test
| **4. Specification** | API contracts, data schemas, error codes, validation rules |
| **5. UI Specification** | Component states, visual patterns, accessibility compliance |
Every specification rule, walkthrough journey, and NFR threshold must have a corresponding test. Tests are written before code so implementation can be validated as it's built. If a spec rule, walkthrough journey, or NFR has no corresponding test, the Validation doc is incomplete.
Every specification rule, walkthrough journey, and NFR threshold must have a corresponding test — each spec item carries an `SP-XXX` ID, every walkthrough step carries a `WT-XXX` ID, and every UI artifact carries a `UI-XXX` ID. Tests are written before code so implementation can be validated as it's built. If a spec rule, walkthrough journey, NFR threshold, or UI state has no corresponding test, the Validation doc is incomplete.
**Test Types**
@@ -225,40 +221,44 @@ Each validation test must include explicit references to its source document:
| Test Type | Source | Example Reference |
|-----------|--------|-------------------|
| **Unit tests** | specification.md, ui-specification.md | `specification.md:3.2.1` rejects camelCase headers; `ui-specification.md:## Wine Table` sort states |
| **Integration tests** | 3-walkthrough.md, specification.md | Participant A section step 4.2 → endpoint chain in specification.md |
| **Performance tests** | requirements.md NFRs, solution-design.md | `NFR-101` latency threshold; `SD-002` WebSocket performance decision |
| **Penetration tests** | requirements.md security NFRs, specification.md auth endpoints | `NFR-301` authentication; `specification.md:auth/login` endpoint |
| **Contract tests** | specification.md sections | Mapped to endpoint definitions and schema constraints |
| **Linting rules** | ui-specification.md style guides | Enforcing design tokens from ui-specification.md |
| **Schema validation** | specification.md data schemas | Validating Arrow stream headers (snake_case), JSON payloads |
| **Visual regression** | ui-specification.md component states | Verifying hover, disabled, error states match spec |
| **Security scanning** | requirements.md, specification.md | SAST, dependency vulnerability checks, OWASP rules |
| **Unit tests** | `4-specification.md`, `5-ui_specification.md` | `4-specification.md:3.2.1` rejects camelCase headers; `5-ui_specification.md:## Wine Table` sort states |
| **Integration tests** | `3-walkthrough.md`, `4-specification.md` | `WT-001` Participant A login → endpoint chain in `4-specification.md`; `SP-002` |
| **Performance tests** | `1-requirements.md` NFRs, `2-solution_design.md` | `NFR-101` latency threshold; `SD-002` WebSocket performance decision |
| **Penetration tests** | `1-requirements.md` security NFRs, `4-specification.md` auth endpoints | `NFR-301` authentication; `4-specification.md:auth/login` endpoint |
| **Contract tests** | `4-specification.md` sections | Mapped to endpoint definitions and schema constraints |
| **Linting rules** | `5-ui_specification.md` style guides | Enforcing design tokens from `5-ui_specification.md` |
| **Schema validation** | `4-specification.md` data schemas | Validating Arrow stream headers (snake_case), JSON payloads |
| **Visual regression** | `5-ui_specification.md` component states | Verifying hover, disabled, error states match spec |
| **Security scanning** | `1-requirements.md`, `4-specification.md` | SAST, dependency vulnerability checks, OWASP rules |
| **CI/CD pipeline** | All test types above | Automated execution on every commit and PR |
**Specification-to-Test Execution Trace**
Every specification rule must have a runnable, verifiable test. This trace maps each spec item to its corresponding test file, test function, and CI gate — proving that every requirement was tested, not just claimed.
Every traceable item — specification rules (SP-XXX), walkthrough journeys (WT-XXX), UI artifacts (UI-XXX), NFR thresholds, and SD decisions — must have a runnable, verifiable test. This trace maps each item to its corresponding test file, test function, and CI gate — proving that every requirement was tested, not just claimed.
**Trace Format**:
| Requirement ID | Source Path | Unit Test File | Unit Test Function | Additional Test File(s) | CI Gate | Status |
|----------------|-------------|----------------|-------------------|------------------------|---------|--------|
| FR-001 | `specification.md#/components/schemas/Request` | `tests/unit/schema-validation.test.ts` | `test_rejects_camelCase_headers` | — | `ci/contract-validation.yaml` | Pass |
| FR-002 | `specification.md#/paths/~1api~1v1~1endpoint` | `tests/unit/api-routes.test.ts` | `test_post_wine_returns_201` | `tests/integration/wine-flow.test.ts` | `ci/contract-validation.yaml` | Pass |
| FR-003 | `specification.md#/paths/~1api~1v1~1endpoint` | — | — | `tests/integration/error-handling.test.ts` | `ci/contract-validation.yaml` | Pass |
| NFR-101 | `requirements.md:4.1` | — | — | `tests/performance/load.test.ts` | `ci/performance.yaml` | Pass |
| SD-001 | `solution-design.md:5.1` | — | — | `tests/integration/nats-async.test.ts` | `ci/integration.yaml` | Pass |
| UI-WineTable | `ui-specification.md## Wine Table` | `tests/unit/wine-table.test.tsx` | `test_sort_by_name` | `tests/visual/wine-table.spec.js` | `ci/visual-regression.yaml` | Pass |
| Requirement/Spec ID | Participant | Source Path | Unit Test File | Unit Test Function | Additional Test File(s) | CI Gate | Status |
|---------------------|-------------|-------------|----------------|-------------------|------------------------|---------|--------|
| SP-001 | — | `4-specification.md#/components/schemas/Request` | `tests/unit/schema-validation.test.ts` | `test_rejects_camelCase_headers` | — | `ci/contract-validation.yaml` | Pass |
| SP-002 | — | `4-specification.md#/paths/~1api~1v1~1endpoint` | `tests/unit/api-routes.test.ts` | `test_post_wine_returns_201` | `tests/integration/wine-flow.test.ts` | `ci/contract-validation.yaml` | Pass |
| WT-001 | Customer | `3-walkthrough.md:#login` | `tests/integration/customer-login.test.ts` | `test_login_flow` | — | `ci/integration.yaml` | Pass |
| WT-002 | Retailer | `3-walkthrough.md:#order` | `tests/integration/retailer-order.test.ts` | `test_order_placement` | — | `ci/integration.yaml` | Pass |
| NFR-101 | — | `1-requirements.md:4.1` | — | — | `tests/performance/load.test.ts` | `ci/performance.yaml` | Pass |
| SD-001 | — | `2-solution_design.md:5.1` | — | — | `tests/integration/nats-async.test.ts` | `ci/integration.yaml` | Pass |
| UI-001 | — | `5-ui_specification.md## Wine Table` | `tests/unit/wine-table.test.tsx` | `test_sort_by_name` | `tests/visual/wine-table.spec.js` | `ci/visual-regression.yaml` | Pass |
**Additional Test File(s)** column covers: integration tests (participant section flows), performance tests (NFR benchmarks), penetration tests (security NFRs), and visual regression tests (UI component states).
**Additional Test File(s)** column covers: unit tests (spec rules, UI states), integration tests (WT walkthrough flows), performance tests (NFR benchmarks), penetration tests (security NFRs), contract tests (endpoint/schema pairs), linting rules (design tokens), schema validation (data schemas), security scanning (SAST/dependency checks), and visual regression tests (UI component states).
**Trace Rules**:
- **Every** specification section with a concrete rule (endpoint, schema field, validation constraint, error code) must have at least one unit test
- **Every** participant section journey must have at least one integration test
- **Every** specification section with a concrete rule (endpoint, schema field, validation constraint, error code) must have at least one unit test and one contract test — each spec item carries an `SP-XXX` ID
- **Every** walkthrough journey must have at least one integration test — each walkthrough step carries a `WT-XXX` ID
- **Every** performance NFR must have at least one performance test (load/stress/benchmark)
- **Every** security NFR must have at least one penetration test scenario
- **Every** UI component state must have at least one unit test (behavior) and one visual regression test (appearance)
- **Every** UI component state must have at least one unit test (behavior) and one visual regression test (appearance) — each UI artifact carries a `UI-XXX` ID
- **Every** data schema must have at least one schema validation test
- **Every** style guide token must have at least one linting rule
- **Every** security NFR must have at least one security scanning test (SAST/dependency checks)
- A test may cover multiple spec items, but each spec item must be covered by **at least one** test
- Status is tracked via CI gate results (Pass/Fail/Skipped) — not manual checks
@@ -271,10 +271,10 @@ Every specification rule must have a runnable, verifiable test. This trace maps
- Document validation failure remediation steps
**How to Maintain**:
1. When writing a new spec rule, add a trace row **before** implementation
1. When writing a new spec rule, assign an SP-XXX ID; when writing walkthrough steps assign WT-XXX; when defining UI artifacts assign UI-XXX; when creating implementation tasks assign IMP-XXX — then add trace rows **before** implementation
2. When writing the test, fill in the test file and function
3. CI gate auto-updates Status from pipeline results
4. Gap-Check step 6 (Validation Review) verifies 100% row coverage — no spec rule without a test
4. **Gap-Check Step 5** (Validation Review) verifies 100% row coverage — no traceable item without a test
**Tooling** (optional):
- Use YAML or JSON files (e.g., `validation/test-trace.yaml`) as machine-readable trace data
@@ -296,14 +296,14 @@ Every specification rule must have a runnable, verifiable test. This trace maps
**Content Guidelines**:
- Implementation phases and timeline (e.g., Phase 1: Core API + data layer; Phase 2: UI components; Phase 3: Integration tests + E2E validation)
- Module/component breakdown with responsibilities and dependencies
- Task list with assignees, priorities, and estimated effort
- Test coverage: which validation tests each implementation task satisfies
- Task list with assignees, priorities, estimated effort — assign unique task IDs using the format `IMP-XXX` (e.g., `IMP-001` for Core API implementation)
- Test coverage: which validation tests each IMP-XXX task satisfies
- Build and deployment preparation (CI/CD setup, environment configuration)
- Risk mitigation: known blockers and mitigation steps
**Best Practices**:
- Break implementation into small, testable increments (1-3 day sprints)
- Map each implementation task to specific validation tests (not just specification sections)
- Break implementation into small, testable increments (1-3 day task units)
- Assign an `IMP-XXX` ID to each implementation task and map it to specific validation tests it satisfies
- Define clear ownership for each module or component
- Include test coverage targets for each phase
- Document dependencies between modules to avoid blocking work
@@ -329,8 +329,8 @@ Every specification rule must have a runnable, verifiable test. This trace maps
- Troubleshooting guides for common issues
- Runbook entries for specific error codes
- Contact information and escalation paths
- Explicit references to [`specification.md`](specification.md) (API contracts, data schemas, specific endpoint sections)
- Explicit references to [`ui-specification.md`](ui-specification.md) (components, interactions, visual states, specific component sections)
- Explicit references to [`4-specification.md`](4-specification.md) (API contracts, data schemas, specific endpoint sections)
- Explicit references to [`5-ui_specification.md`](5-ui_specification.md) (components, interactions, visual states, specific component sections)
**Best Practices**:
- Write runbooks for every P1/P2 incident
@@ -354,15 +354,15 @@ Before writing any code or documentation, establish clear requirements. Ask:
### 2. Define Solution Design
Once requirements are stable, translate them into an viable solution. This ensures the technical approach solves the user problem, not just requirements.
Once requirements are stable, translate them into a viable solution. This ensures the technical approach solves the user problem, not just requirements.
**Action**: Create `docs/solution-design/` with `solution-design.md`, problem decomposition, alternatives considered, high-level component diagram, and decision rationale.
**Action**: Create `docs/solution-design/` with `2-solution_design.md`, problem decomposition, solution approach, decision rationale, high-level component diagram, and alternatives considered.
### 3. Create Walkthroughs Early
As soon as the solution design is defined, create walkthroughs — one document with a section per system participant. This helps identify gaps in each participant's flow and provides onboarding material. Each section traces the complete journey from that participant's perspective and cross-references other participants' workflows. The walkthrough should explicitly link to solution-design.md (SD-XXX IDs) and requirements.md.
As soon as the solution design is defined, create walkthroughs — one document with a section per system participant. This helps identify gaps in each participant's flow and provides onboarding material. Each section traces the complete journey from that participant's perspective and cross-references other participants' workflows. The walkthrough should explicitly link to `2-solution_design.md` (SD-XXX.Y IDs) and `1-requirements.md`.
**Action**: Create `docs/walkthrough/` with `3-walkthrough.md` containing one section per participant (e.g., Customer, Retailer, Admin), sequence diagrams, and cross-references to solution design decisions and requirements.
**Action**: Create `docs/walkthrough/` with `3-walkthrough.md` containing one section per participant (e.g., Customer, Retailer, Admin), sequence diagrams, and cross-references to `2-solution_design.md` (SD-XXX.Y IDs) and `1-requirements.md`.
### 4. Define the Specification
@@ -370,25 +370,25 @@ With walkthrough in place, define the technical specification. This becomes the
- **Requirements** (WHAT - business intent)
- **Solution Design** (HOW/WHY - architectural decisions)
**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format), `error-codes.md`, and traceability mappings to requirements.md, solution-design.md, and 3-walkthrough.md.
**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format), `error-codes.md`, and traceability mappings to `1-requirements.md`, `2-solution_design.md`, and `3-walkthrough.md`. Each specification item must have an `SP-XXX` ID.
### 5. Define UI Specification Early
Create UI specifications before implementing frontend components. This ensures design consistency and provides a contract for implementation.
**Action**: Create `docs/ui-specification/` with `component-library.md`, `style-guide.md`, and `design-tokens.json`.
**Action**: Create `docs/ui-specification/` with `component-library.md`, `style-guide.md`, and `design-tokens.json`. Each UI artifact must have a `UI-XXX` ID.
### 6. Define Validation Tests Before Implementation
Write validation tests **before** implementation begins. This ensures every specification rule and UI state has a corresponding test that defines success. Tests should reference specification.md, ui-specification.md, requirements.md (NFR thresholds), and solution-design.md (performance decisions). Create a specification-to-test execution trace that maps every spec item to its test file, test function, and CI gate.
Write validation tests **before** implementation begins. This ensures every specification rule (SP-XXX), walkthrough journey (WT-XXX), UI state (UI-XXX), and NFR threshold has a corresponding test that defines success. Tests should reference `4-specification.md`, `5-ui_specification.md`, `3-walkthrough.md`, `1-requirements.md` (NFR thresholds), and `2-solution_design.md` (performance decisions). Create a specification-to-test execution trace that maps every spec item to its test file, test function, and CI gate.
**Action**: Create `docs/validation/` with `unit-tests/` (spec rules, schema fields, component states), `integration-tests/` (end-to-end flows from each participant walkthrough section), `performance-tests/` (NFR benchmarks: latency, TPS), `penetration-tests/` (security NFRs, auth flows), `contract-tests/`, `ci-pipeline.yaml`, `lint-rules/`, and `test-trace.yaml` (specification-to-test execution trace mapping every spec path to its test file, test function, and CI gate).
**Action**: Create `docs/validation/` with `unit-tests/` (spec rules, schema fields, component states), `integration-tests/` (WT-XXX walkthrough flows), `performance-tests/` (NFR benchmarks: latency, TPS), `penetration-tests/` (security NFRs, auth flows), `contract-tests/`, `ci-pipeline.yaml`, `lint-rules/`, and `test-trace.yaml` (specification-to-test execution trace mapping every spec path to its test file, test function, and CI gate).
### 7. Create Implementation Plan
With validation tests defined, create the implementation plan. Map each implementation task to specific validation tests that it must satisfy.
With validation tests defined, create the implementation plan. Assign `IMP-XXX` IDs to each task and map them to the specific validation tests they must satisfy.
**Action**: Create `docs/implementation-plan/` with phases, module breakdown, task list with assignees, and test coverage targets.
**Action**: Create `docs/implementation-plan/` with `7-implementation-plan.md` containing phases, module breakdown, task list with assignees/priorities/effort (`IMP-XXX` IDs), and test coverage targets.
### 8. Document Operations from Day One
@@ -405,11 +405,11 @@ Since all docs defined in the ASG Framework are **living documents** that evolve
| Stage Transition | Goal | Gap-Check Question | Example Gap | Result |
|------------------|------|-------------------|-------------|--------|
| **Requirements → Solution Design** | Turn a "Wish" into a "Solution" | Does the Solution Design clearly explain how the system solves the user problem, not just what it does? | Requirements say "users can compare wines", but solution design only mentions "wine comparison API" without explaining how users will actually use the comparison feature | Add UI flow and user interaction patterns to the solution design |
| **Solution Design → Walkthrough** | Turn a "Solution" into a "Story" | Does every participant section trace the complete flow the Solution Design describes, including all SD-XXX decisions? Is there a section for each system participant? | Solution design says "use NATS for async messaging", but Participant A section doesn't trace the async flow or reference SD-001 | Add the async messaging flow with SD-001 reference to Participant A section |
| **Walkthrough → Specification** | Turn the "Story" into "Rules" | Does the Specification cover all the behaviors defined in every participant section? | Participant A section shows 10 interaction steps, but Specification only defines 2 REST endpoints | Add the missing endpoint definitions 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 |
| **Solution Design → Walkthrough** | Turn a "Solution" into a "Story" | Does every SD-XXX decision appear in at least one participant's walkthrough section? Is there a WT-XXX ID for every walkthrough step? Is there a section for each system participant? | Solution design defines SD-001 (NATS async messaging), but no participant section traces the async flow | Add an async messaging flow to Participant B section with SD-001 reference and WT-003 ID |
| **Walkthrough → Specification** | Turn the "Story" into "Rules" | Does the Specification define SP-XXX rules for every WT-XXX walkthrough step? | Walkthrough defines 20 WT-XXX steps across 3 participants, but Specification only has SP-001 through SP-005 (10 items) | Add the missing endpoint definitions, schema rules, and error codes to Specification with SP-006 through SP-020 |
| **Specification → UI Specification** | Turn a "Rule" into a "Button" | Does the UI Specification expose all data entities and states defined in the Specification? Are UI-XXX IDs assigned to every UI artifact? | Specification defines 15 API response schemas with 30 fields, but UI Specification only has 3 components (UI-001 through UI-003) | Add the remaining UI components for each data entity with UI-XXX IDs to match Specification coverage
| **UI Specification → Validation** | Turn "Design" into "Tests" | Do the Validation tests cover all specification rules, UI states, performance NFRs, and security requirements? | UI Spec defines 15 component states but Validation only has 5 unit tests; NFR-101 latency threshold has no performance test | Add unit tests for all component states, performance benchmarks for NFR thresholds, and pen test scenarios for security NFRs |
| **Validation → Implementation Plan** | Turn "Tests" into "Tasks" | Does the Implementation Plan satisfy all validation tests with clear ownership? | Validation defines 30 test cases but Implementation Plan only has tasks for 20 | Add implementation tasks for remaining test cases with assignees and timelines |
| **Validation → Implementation Plan** | Turn "Tests" into "Tasks" | Does the Implementation Plan satisfy all validation tests with clear ownership? | Validation defines 30 test cases but Implementation Plan only has tasks for 20 | Verify every validation test maps to at least one implementation task with an assignee and timeline |
### Why Gap-Checks Matter
@@ -422,13 +422,14 @@ 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
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. **Walkthrough Review**: After writing walkthrough, verify every SD-XXX decision and requirement is traced in every participant section with error paths included, and that each system participant has a dedicated section
3. **Walkthrough Review**: After writing walkthrough, verify every SD-XXX.Y decision, requirement ID, and WT-XXX walkthrough step is traced in every participant section with error paths included, and that each system participant has a dedicated section
4. **Specification Review**: After writing the spec, verify every spec item has:
- An `SP-XXX` ID assigned for downstream traceability
- At least one requirement ID reference (WHAT)
- At least one solution design reference (HOW/WHY)
- Coverage for all behaviors defined in each participant section
5. **UI Specification Review**: After writing UI Specification, verify every spec rule has at least one UI representation with a corresponding requirement ID reference
6. **Validation Review**: After writing Validation, verify every specification section and UI state has at least one corresponding unit/integration test case; every performance NFR has a benchmark test; every security NFR has a penetration test scenario — each with explicit references to specification.md, ui-specification.md, and/or requirements.md
5. **UI Specification Review**: After writing UI Specification, verify every `UI-XXX` artifact has a corresponding requirement ID, solution design reference, and specification ID
6. **Validation Review**: After writing Validation, verify every specification section and UI state has at least one corresponding test case — unit tests for SP-XXX spec rules and UI-XXX UI states, integration tests for WT-XXX walkthrough flows, performance tests for NFR thresholds, penetration test scenarios for security NFRs, contract tests for SP-XXX endpoint/schema definitions, linting rule coverage for `5-ui_specification.md` style guides, schema validation for all data schemas, and security scanning for all security NFRs — each with explicit references to `4-specification.md`, `5-ui_specification.md`, `3-walkthrough.md`, and/or `1-requirements.md`
7. **Implementation Plan Review**: After writing the plan, verify every validation test is covered by at least one implementation task with an assignee and timeline
---
@@ -440,11 +441,11 @@ This habit ensures that each documentation stage is complete and validated befor
| Stage | Debug Checklist | Why It Matters |
|-------|-----------------|----------------|
| **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 |
| **Walkthrough** | If I can't Trace every participant's full flow, the system has 'broken bridges'. | Identifies gaps between components and validates the solution design end-to-end for each system participant |
| **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 |
| **Validation** | If I can't Write a Test for every spec rule, UI state, NFR threshold, and security requirement, implementation is untestable. | Ensures code can be tested from day one — unit, integration, performance, and pen tests define success before implementation begins |
| **Solution Design** | If I can't see the Solution, I'm building without a compass. | Ensures the technical approach solves the user problem before spec writing |
| **Walkthrough** | If I can't Trace every participant's flow with **WT-XXX** IDs, the system has broken bridges. | Identifies gaps between components and validates the solution design end-to-end for each system participant |
| **Specification** | If I can't write a Rule with a requirement and 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 **UI-XXX** ID and traceability reference, the user has no way to trigger the logic. | Ensures traceability from UI elements to business requirements |
| **Validation** | If I can't Write a Test for every traceable item, implementation is untestable. | Ensures code can be tested from day one — unit, integration, performance, contract, and security tests define success before implementation begins |
**How to Use This Habit:**
@@ -478,11 +479,11 @@ Each documentation artifact has associated KPIs. Track these to ensure quality:
|----------|-----|--------|
| Requirements | Requirement coverage | 100% of features have associated requirements |
| Solution Design | Solution completeness | 0 solution components without a requirement ID reference |
| Walkthrough | Participant coverage | 100% of identified system participants have a walkthrough section |
| Specification | Specification compliance rate | 100% of messages validate against spec |
| UI Specification | UI spec compliance | 100% of components match design spec (visual regression tests) |
| Walkthrough | New dev time-to-first-PR | <2 days from onboarding to first contribution |
| Implementation | Test coverage | >80% unit test coverage |
| Validation | Bypass rate | <1% of PRs bypass validation gates |
| Implementation | Test coverage | >80% unit test coverage |
| Runbook | MTTR | <15 minutes for P1 incidents |
**Review Cadence**:
@@ -594,14 +595,18 @@ These rules serve as a binary decision framework:
## 6. Requirements Traceability Matrix
| Requirement ID | Description | Implementation File | Test File |
|----------------|-------------|---------------------|-----------|
| FR-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` |
| NFR-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` |
| Requirement ID | WT ID | SP ID | UI ID | IMP ID | Description | Implementation File | Test File |
|----------------|-------|-------|-------|--------|-------------|---------------------|-----------|
| FR-XXX | WT-XXX | SP-XXX | UI-XXX | IMP-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` |
| NFR-XXX | WT-XXX | SP-XXX | UI-XXX | IMP-XXX | [Brief description] | `path/to/file.ext` | `tests/file.spec.js` |
**Notes**:
- Functional Requirements (FR) define what the system shall do
- Non-Functional Requirements (NFR) define system qualities (performance, availability, security, etc.)
- **WT-XXX** IDs link requirements to walkthrough journey steps in `3-walkthrough.md`
- **SP-XXX** IDs are assigned to each specification item in `4-specification.md` for downstream traceability (Validation, Implementation Plan)
- **UI-XXX** IDs are assigned to each UI artifact in `5-ui_specification.md` for downstream traceability (Validation, Implementation Plan)
- **IMP-XXX** IDs are assigned to each implementation task in `7-implementation-plan.md` for downstream mapping to validation tests
- KPIs are measurable targets that validate whether requirements were met post-deployment
- Each requirement must include a clear requirement ID for traceability
- All acceptance conditions must be verifiable through testing or manual inspection
@@ -634,15 +639,17 @@ Describe the high-level approach to solving the problem.
- [e.g., "Use server-side rendering for SEO"]
- [e.g., "Support unlimited wine comparisons for power users"]
## 3. Alternatives Considered
## 3. Decision Rationale
Document at least 2-3 alternative approaches with rationale.
Explain the design reasoning behind each major decision — why the solution was designed this way, and how each decision connects to form a cohesive approach that solves the user problem.
| Alternative | Pros | Cons | Decision |
|-------------|------|------|----------|
| Client-side comparison | Fast updates, no server load | Memory-intensive, no sharing | Rejected - memory constraints on mobile |
| Server-side comparison | Centralized, scalable | Latency, complex state sync | Accepted - matches performance requirements |
| Hybrid approach | Best of both worlds | Complex, hard to maintain | Rejected - over-engineering |
| Decision ID | Decision | Rationale | Alternatives Rejected |
|-------------|----------|-----------|----------------------|
| SD-001 | Use NATS for async messaging | Required for real-time messaging with low overhead | Kafka - too complex for current scale |
| SD-002 | Use WebSockets for real-time updates | Required for <100ms feedback | REST polling - too slow, too many requests |
| SD-003 | Store comparison list in localStorage | Allows offline comparison editing | Redux - overkill for this feature |
| SD-004 | Server-side rendering for comparison view | SEO for comparison pages shared via unique links | Client-side rendering - no SEO benefit |
| SD-005 | Server-side PDF/CSV export | Generates downloadable exports with user data | Client-side export — requires user browser permissions |
## 4. High-Level Component Diagram
@@ -659,16 +666,15 @@ flowchart TD
- **[Component Name]**: [Brief description of responsibilities and how it solves part of the problem]
- Links to requirements: FR-001, NFR-201
## 5. Decision Rationale
## 5. Alternatives Considered
Explain why each major decision was made.
Document at least 2-3 alternative approaches with rationale.
| Decision ID | Decision | Rationale | Alternatives Rejected |
|-------------|----------|-----------|----------------------|
| SD-001 | Use NATS for async messaging | Required for real-time messaging with low overhead | Kafka - too complex for current scale |
| SD-002 | Use WebSockets for real-time updates | Required for <100ms feedback | REST polling - too slow, too many requests |
| SD-003 | Store comparison list in localStorage | Allows offline comparison editing | Redux - overkill for this feature |
| SD-004 | Server-side rendering for comparison export | SEO for shared comparisons | Client-side rendering - no SEO benefit |
| Alternative | Pros | Cons | Decision |
|-------------|------|------|----------|
| Client-side comparison | Fast updates, no server load | Memory-intensive, no sharing | Rejected - memory constraints on mobile |
| Server-side comparison | Centralized, scalable | Latency, complex state sync | Accepted - matches performance requirements |
| Hybrid approach | Best of both worlds | Complex, hard to maintain | Rejected - over-engineering |
## 6. Risk Assessment
@@ -687,10 +693,10 @@ Link each solution component to specific requirements and assign Solution Design
| Solution Component | Requirement ID | Decision ID | Description |
|-------------------|----------------|-------------|-------------|
| Comparison table UI | FR-101 | SD-001 | Display wines in table format (uses NATS messaging) |
| Filtering | FR-102 | SD-002 | Filter wines by criteria (uses WebSocket updates) |
| Sorting | FR-103 | SD-003 | Sort wines by any column (stored in localStorage) |
| Filtering | FR-102 | SD-003 | Filter wines by criteria (stored in localStorage) |
| Sorting | FR-103 | SD-004 | Sort wines by any column (stored in localStorage) |
| Real-time updates | NFR-201 | SD-002 | Updates appear within 100ms (uses WebSocket) |
| Export comparison | FR-201 | SD-004 | Export comparison to PDF/CSV (uses server-side rendering) |
| Export comparison | FR-201 | SD-005 | Export comparison to PDF/CSV (uses server-side rendering) |
### Specification Template
@@ -718,7 +724,8 @@ paths:
schema:
$ref: '#/components/schemas/Response'
x-requirement-id: FR-001 # Reference to Requirements document (WHAT)
x-solution-design-ref: SD-3.1 # Reference to Solution Design decision (HOW/WHY)
x-solution-design-ref: SD-001.1 # Reference to Solution Design decision (HOW/WHY)
x-spec-id: SP-001 # Specification item ID for downstream traceability
components:
schemas:
Request:
@@ -727,14 +734,16 @@ components:
data:
type: string
x-requirement-id: FR-002 # Reference to Requirements document (WHAT)
x-solution-design-ref: SD-3.2 # Reference to Solution Design decision (HOW/WHY)
x-solution-design-ref: SD-001.2 # Reference to Solution Design decision (HOW/WHY)
x-spec-id: SP-002 # Specification item ID for downstream traceability
Response:
type: object
properties:
status:
type: string
x-requirement-id: FR-003 # Reference to Requirements document (WHAT)
x-solution-design-ref: SD-3.1 # Reference to Solution Design decision (HOW/WHY)
x-solution-design-ref: SD-001.1 # Reference to Solution Design decision (HOW/WHY)
x-spec-id: SP-003 # Specification item ID for downstream traceability
```
### UI Specification Template
@@ -746,13 +755,14 @@ components:
**Name**: [Component Name]
**Status**: [Draft/Approved/Deprecated]
**Version**: 1.0.0
**UI-XXX**: [Unique UI spec ID assigned to this component]
## Requirements Traceability
| UI Element | Requirement ID | Solution Design Ref | Description |
|------------|----------------|---------------------|-------------|
| Login form | FR-001 | SD-2.1 | Username/password authentication |
| Sidebar menu | NFR-202 | Collapsible sidebar for usability |
| Wine table | FR-101 | Sortable, searchable inventory table |
| UI Element | UI Spec Ref | Requirement ID | Solution Design Ref | Description |
|------------|-------------|----------------|---------------------|-------------|
| Login form | UI-001 | FR-001 | SD-001.1 | Username/password authentication |
| Sidebar menu | UI-002 | FR-102 | SD-002.1 | Collapsible sidebar for navigation |
| Wine table | UI-003 | FR-101 | SD-003.1 | Sortable, searchable inventory table |
## Design Tokens
- **Color**: `--color-primary`
@@ -760,12 +770,13 @@ components:
- **Spacing**: `--spacing-md`
## Component States
| State | Description | Example | Requirement ID |
|-------|-------------|---------|----------------|
| Default | Normal state | `<Button />` | FR-001 |
| Hover | Mouse over | `<Button hover />` | NFR-201 |
| Disabled | Disabled state | `<Button disabled />` | NFR-203 |
| Error | Error state | `<Button error />` | EH-004 |
**UI-XXX**: [UI spec ID from the Component Overview]
| State | Description | Example | Requirement ID | UI Spec Ref |
|-------|-------------|---------|----------------|-------------|
| Default | Normal state | `<Button />` | FR-001 | UI-001 |
| Hover | Mouse over | `<Button hover />` | FR-002 | UI-001 |
| Disabled | Disabled state | `<Button disabled />` | FR-003 (disabled state) | UI-001 |
| Error | Error state | `<Button error />` | FR-003 | UI-001 |
## Accessibility
- [ ] WCAG 2.1 AA compliant
@@ -780,38 +791,18 @@ components:
## References
- Figma: [Link to design file]
- Storybook: [Link to component story]
- Requirements: [`docs/requirements.md`](../requirements.md)
- Requirements: [`1-requirements.md`](../1-requirements.md)
```
### Architecture Template
```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#3b82f6'}}}%%
flowchart TD
A[Client] --> B[Caddy]
B --> C[Node.js API]
C --> D[Julia Worker]
D --> E[NATS Cluster]
E --> F[Storage]
style A fill:#f9f9f9,stroke:#333
style E fill:#e0e7ff,stroke:#3b82f6
```
### Specification Traceability Template
**Specification Traceability:**
| Architecture Component | Solution Design Ref | Specification Section | UI Specification Section | Requirement ID |
|------------------------|---------------------|----------------------|--------------------------|----------------|
| NATS Bridge (smartsend) | SD-3.1 | specification.md:3.1 | - | FR-301, NFR-201 |
| Login Form | SD-2.1 | specification.md:10.1 | ui-specification.md:15.2.1 | FR-001, NFR-201 |
| Wine Inventory Table | SD-2.2 | specification.md:4.2 | ui-specification.md:15.3.3 | FR-101, NFR-205 |
| Sidebar Menu | SD-2.3 | specification.md:11.1 | ui-specification.md:15.3.2 | NFR-202 |
**Component Details:**
- **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, solution-design.md:SD-3.1)
- **Julia Worker**: Backend processing (specification.md:4.1, solution-design.md:SD-4.1)
- **NATS Cluster**: Message bus (specification.md:3.3, solution-design.md:SD-3.3)
- **Storage**: Data persistence (specification.md:5.1, solution-design.md:SD-5.1)
| Architecture Component | Solution Design Ref | Specification Section | Specification ID (SP) | UI Specification Section | UI Spec Ref (UI) | Requirement ID | Walkthrough Ref (WT) |
|------------------------|---------------------|----------------------|----------------------|--------------------------|------------------|----------------|----------------------|
| NATS Bridge (smartsend) | SD-001.1 | `4-specification.md`:3.1 | SP-001 | - | - | FR-301, NFR-201 | WT-001 |
| Login Form | SD-002.1 | `4-specification.md`:10.1 | SP-002 | `5-ui_specification.md`:15.2.1 | UI-001 | FR-001, NFR-201 | WT-002 |
| Wine Inventory Table | SD-002.2 | `4-specification.md`:4.2 | SP-003 | `5-ui_specification.md`:15.3.3 | UI-002 | FR-101, NFR-205 | WT-003 |
| Sidebar Menu | SD-002.3 | `4-specification.md`:11.1 | SP-004 | `5-ui_specification.md`:15.3.2 | UI-003 | NFR-202 | WT-004 |
### Runbook Template
@@ -833,6 +824,10 @@ flowchart TD
## Rollback
- Run: `kubectl rollout undo deployment/natsbridge`
## References
- API contract: [`4-specification.md`](4-specification.md)
- UI component states: [`5-ui_specification.md`](5-ui_specification.md)
## Post-Incident
- [ ] Review logs for root cause
- [ ] Update runbook if needed
etc.md
+18 -9
View File
@@ -1,12 +1,21 @@
there is no overview about participants that will read the walkthrough doc like the following? I need it so that when participants check this doc, they will know who are included
this info should be just under the doc's purpose statement
System Participants Overview
| Participant | Section | Role | What It Shows |
|-------------|---------|------|---------------|
| **Frontend Application** (Customer UI) | Participant A | Primary user-facing client that initiates sessions and exchanges messages with the agent | End-to-end journey: register → send message → receive response → handle termination |
| **Agent Instance** (yiemAgent Process) | Participant B | Per-session Julia task that manages conversation, calls LLM via load balancer, and executes MCP tools | Lifecycle: spawn → chat loop → tool calls → response enrichment → terminate |
| **Session Manager** (Main Service Loop) | Participant C | Central coordinator that manages session lifecycle, enforces timeouts, and dispatches messages | Operations: startup → warmup → registration routing → timeout polling → message dispatch |
| **External Services** (MCP, SLB, Object Storage) | Participant D | Backing services for LLM routing, tool execution, and file transfer | Integration: LLM request flow → MCP tool/list and tool/call → S3 upload/download |