# 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.**
