ASF_01_sys_sw_arch/0 system_design/Project_Structure_Guide.md

ASF Sensor Hub - Project Structure Guide

Version: 2.0
Date: 2025-01-19

Overview

This document describes the clean, organized structure of the System Design documentation. All duplicates have been removed, and only the latest versions are maintained.

Directory Structure

System Design/
└── system_design/                    # Main system design folder
    │
    ├── features/                     # Feature specifications (14 files)
    │   ├── Features.md               # Main feature catalog
    │   ├── [DAQ] Sensor Data Acquisition Features.md
    │   ├── [DQC] Data Quality & Calibration Features.md
    │   ├── [COM] Communication Features.md
    │   ├── [DIAG] Diagnostics & Health Monitoring Features.md
    │   ├── [DATA] Persistence & Data Management Features.md
    │   ├── [OTA] Firmware Update (OTA) Features.md
    │   ├── [SEC] Security & Safety Features.md
    │   ├── [SYS] System Management Features.md
    │   ├── [PWR] Power & Fault Handling Features.md
    │   ├── [HW] Hardware Abstraction Features.md
    │   ├── Cross-Feature Constraints.md
    │   ├── System Assumptions & Limitations.md
    │   └── System_Requirements_Traceability.csv  # Feature → SR mapping
    │
    ├── specifications/               # Core system specifications (3 files)
    │   ├── System_State_Machine_Specification.md
    │   ├── Failure_Handling_Model.md
    │   └── System Review Checklist.md
    │
    ├── SRS/                          # Software Requirements Specification (6 files)
    │   ├── SRS.md                    # Main SRS document
    │   ├── Annex_A_Traceability.md
    │   ├── Annex_B_Interfaces.md
    │   ├── Annex_C_Budgets.md
    │   ├── VV_Matrix.md             # Verification & Validation matrix
    │   └── Traceability_SWRS.csv    # SWR traceability
    │
    ├── analysis/                     # Analysis and review documents (2 files)
    │   ├── Gap_Analysis_and_Solutions.md
    │   └── Engineering_Review_Report.md
    │
    ├── system_requirementsand_and_traceability.csv  # Original system requirements
    ├── README.md                     # Documentation index
    ├── Cleanup_Summary.md            # Cleanup actions taken
    └── Project_Structure_Guide.md    # This file

File Descriptions

Features Folder (features/)

Purpose: Contains all feature specifications with system requirements

Key Files:

• Features.md - Main feature catalog with overview of all 39 features
• [XXX] Feature Files.md - Detailed specifications for each feature group
• System_Requirements_Traceability.csv - Complete mapping of 39 features to 139 system requirements
  • Columns: Feature_ID, Feature_Name, Feature_Group, Sub_Feature_ID, Sub_Feature_Name, System_Requirement_ID, System_Requirement_Description
• Cross-Feature Constraints.md - Architectural constraints across features
• System Assumptions & Limitations.md - System context and boundaries

Statistics:

• 10 feature groups (DAQ, DQC, COM, DIAG, DATA, OTA, SEC, SYS, PWR, HW)
• 39 features total
• 139 system requirements (SR-*)

Specifications Folder (specifications/)

Purpose: Core system specifications

Files:

• System_State_Machine_Specification.md - Complete FSM with 11 states, transitions, and per-state feature execution rules
• Failure_Handling_Model.md - Fault taxonomy (INFO, WARNING, ERROR, FATAL), escalation, and recovery behaviors
• System Review Checklist.md - Gate criteria for implementation readiness

SRS Folder (SRS/)

Purpose: Software Requirements Specification (ISO/IEC/IEEE 29148 compliant)

Files:

• SRS.md - Main SRS with over 200 Software Requirements (SWR-*)
• Annex_A_Traceability.md - Bidirectional traceability (Feature → SR → SWR → Component → Test)
• Annex_B_Interfaces.md - External interfaces specification
• Annex_C_Budgets.md - Timing and resource budgets
• VV_Matrix.md - Verification & Validation matrix mapping SWRs to test methods
• Traceability_SWRS.csv - SWR traceability data

Analysis Folder (analysis/)

Purpose: Analysis and review documents

Files:

• Gap_Analysis_and_Solutions.md - Consolidated gap analysis with:
  • Executive summary
  • Gap & solution matrix
  • Technology stack validation
  • Critical action items
  • Risk assessment
• Engineering_Review_Report.md - Architecture review findings and recommendations

Root Level Files

• system_requirementsand_and_traceability.csv - Original system requirements (kept for reference)
• README.md - Documentation index and quick reference
• Cleanup_Summary.md - Summary of cleanup actions
• Project_Structure_Guide.md - This file

CSV Files

1. features/System_Requirements_Traceability.csv

Purpose: Complete traceability between Features and System Requirements

Columns:

• Feature_ID - Feature identifier (e.g., F-DAQ-01)
• Feature_Name - Feature name
• Feature_Group - Feature group (DAQ, DQC, COM, etc.)
• Sub_Feature_ID - Same as Feature_ID (for consistency)
• Sub_Feature_Name - Same as Feature_Name
• System_Requirement_ID - System requirement ID (e.g., SR-DAQ-001)
• System_Requirement_Description - Full requirement text

Usage: Use this file to:

• Find all system requirements for a feature
• Find which feature(s) a system requirement belongs to
• Generate traceability reports
• Perform impact analysis

2. SRS/Traceability_SWRS.csv

Purpose: Software Requirements traceability

Usage: Links Software Requirements (SWR-) to System Requirements (SR-)

3. system_requirementsand_and_traceability.csv

Purpose: Original system requirements database

Usage: Reference for original system requirements structure

Document Relationships

Features.md
    ↓
[XXX] Feature Files.md
    ↓
System_Requirements_Traceability.csv (Features → SR-*)
    ↓
SRS.md (SR-* → SWR-*)
    ↓
Traceability_SWRS.csv (SWR-* traceability)
    ↓
VV_Matrix.md (SWR-* → Test Methods)

Quick Access Guide

I need to find...

A feature specification: → features/[XXX] Feature Files.md

System requirements for a feature: → features/System_Requirements_Traceability.csv (filter by Feature_ID)

The system state machine: → specifications/System_State_Machine_Specification.md

Failure handling rules: → specifications/Failure_Handling_Model.md

Software requirements: → SRS/SRS.md

Gap analysis: → analysis/Gap_Analysis_and_Solutions.md

Architecture review: → analysis/Engineering_Review_Report.md

Traceability information: → features/System_Requirements_Traceability.csv (Features → SR) → SRS/Annex_A_Traceability.md (Full traceability chain) → SRS/Traceability_SWRS.csv (SWR traceability)

Deprecated Locations

The following locations are deprecated and can be removed after verification:

• ❌ System Design/Features/ → Use system_design/features/
• ❌ System Design/system_arch_final/ → Content moved to system_design/
• ❌ System Design/Creating Gap Analysis and Solutions Documentation/ → Consolidated into analysis/
• ❌ System Design/Gap Analysis and Solutions Documentation/ → Consolidated into analysis/
• ❌ System Design/Engineering Review Report.md → Use analysis/Engineering_Review_Report.md

Maintenance

Adding New Features

1. Create feature file in features/ folder
2. Update features/Features.md with new feature
3. Add system requirements to feature file
4. Update features/System_Requirements_Traceability.csv with new entries

Updating System Requirements

1. Update feature file with new/updated requirements
2. Update features/System_Requirements_Traceability.csv
3. Update SRS/SRS.md if software requirements are affected
4. Update traceability documents

Adding New Specifications

1. Add specification file to specifications/ folder
2. Update README.md if needed

Statistics

• Total Files: 27 files
• Feature Files: 14 files (10 feature specs + 4 supporting docs)
• Specification Files: 3 files
• SRS Files: 6 files
• Analysis Files: 2 files
• CSV Files: 3 files
• Documentation Files: 2 files (README, guides)

---

This structure eliminates duplicates and provides a single source of truth for all system design documentation.