Weyoun/hackathon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add architectural review and requirement refinement verification

Browse Source 
Complete architectural analysis and requirement traceability improvements:

  1. Architecture Review Report (NEW)
     - Independent architectural review identifying 15 issues
     - 5 critical issues: security (no TLS), buffer inadequacy, performance
       bottleneck, missing circuit breaker, inefficient backoff
     - 5 major issues: no metrics, no graceful shutdown, missing rate limiting,
       no backpressure, low test coverage
     - Overall architecture score: 6.5/10
     - Recommendation: DO NOT DEPLOY until critical issues resolved
     - Detailed analysis with code examples and effort estimates

  2. Requirement Refinement Verification (NEW)
     - Verified Req-FR-25, Req-NFR-7, Req-NFR-8 refinement status
     - Added 12 missing Req-FR-25 references to architecture documents
     - Confirmed 24 Req-NFR-7 references (health check endpoint)
     - Confirmed 26 Req-NFR-8 references (health check content)
     - 100% traceability for all three requirements

  3. Architecture Documentation Updates
     - system-architecture.md: Added 4 Req-FR-25 references for data transmission
     - java-package-structure.md: Added 8 Req-FR-25 references across components
     - Updated DataTransmissionService, GrpcStreamPort, GrpcStreamingAdapter,
       DataConsumerService with proper requirement annotations

  Files changed:
  - docs/ARCHITECTURE_REVIEW_REPORT.md (NEW)
  - docs/REQUIREMENT_REFINEMENT_VERIFICATION.md (NEW)
  - docs/architecture/system-architecture.md (4 additions)
  - docs/architecture/java-package-structure.md (8 additions)

  All 62 requirements now have complete bidirectional traceability with
  documented architectural concerns and critical issues identified for resolution.
This commit is contained in:
Christoph Wagner
2025-11-19 11:06:02 +01:00
parent a7516834ad
commit 5b658e2468
30 changed files with 5689 additions and 580 deletions
Download Patch File Download Diff File Expand all files Collapse all files
requirements/DataCollector SRS.md
+16 -16
View File
@@ -64,15 +64,15 @@ The main task of the HSP is to connect the Collector to a large amount of endpoi
| Req-FR-23 | HSP shall encode binary file as Base64 strings within the JSON payload. |
| Req-FR-24 | Each JSON message shall include: "HTTP sender plugin" as the plugin name, timestamp (ISO 8601), source_endpoint (URL), data_size (bytes), and payload (Base64 encoded binary). |
| Req-FR-25 | HSP shall then send the collected and aggregated data to the CollectorSender Core as decribed below. |
| Req-FR-25 | If gRPC transmission fails, HSP shall buffer collected data in memory (max 300 messages). |
| Req-FR-26 | If the buffer is full and new data is collected, HSP shall discard the oldest data. |
| Req-FR-26 | If gRPC transmission fails, HSP shall buffer collected data in memory (max 300 messages). |
| Req-FR-27 | If the buffer is full and new data is collected, HSP shall discard the oldest data. |
| Prose | This section describes the connection and mechanism used for the HSP to connect to the Collector Sender Core to transmit aggregated collected data |
| Req-FR-27 | The HSP shall communicate with the Collector Sender Core according to Interface IF2 |
| Req-FR-28 | HSP shall automatically establish a single bidirectional gRPC stream to the Collector Sender Core at startup and maintain it for the lifetime of the application. |
| Req-FR-29 | If the gRPC stream fails, HSP shall close the stream, wait 5 seconds, and try to establish a new stream. |
| Req-FR-30 | HSP shall send one TransferRequest message containing as many messages as fit into 4MB (transfer maximum) |
| Req-FR-31 | HSP shall send one TransferRequest message containing less then 4MB (transfer maximum) latest 1s after the last message. |
| Req-FR-32 | The receiver_id field shall be set to 99 for all requests. |
| Req-FR-28 | The HSP shall communicate with the Collector Sender Core according to Interface IF2 |
| Req-FR-29 | HSP shall automatically establish a single bidirectional gRPC stream to the Collector Sender Core at startup and maintain it for the lifetime of the application. |
| Req-FR-30 | If the gRPC stream fails, HSP shall close the stream, wait 5 seconds, and try to establish a new stream. |
| Req-FR-31 | HSP shall send one TransferRequest message containing as many messages as fit into 4MB (transfer maximum) |
| Req-FR-32 | HSP shall send one TransferRequest message containing less then 4MB (transfer maximum) latest 1s after the last message. |
| Req-FR-33 | The receiver_id field shall be set to 99 for all requests. |
## Non-Functional Requirements
@@ -111,21 +111,21 @@ The main task of the HSP is to connect the Collector to a large amount of endpoi
| Req-Norm-6 | The software shall be designed to be maintainable, with clear and concise code, and a modular architecture. |
## Testing Requirements
## Testing Requirements
| Unique ID | Requirement Description |
|---|---|
| Req-NFR-7 | Integration tests shall verify HTTP collection with a mock HTTP server. |
| Req-NFR-8 | Integration tests shall verify gRPC transmission with a mock gRPC server. |
| Req-NFR-9 | Tests shall use JUnit 5 and Mockito frameworks. |
| Req-NFR-10 | All tests shall be executable via 'mvn test' command. |
| Req-Test-1 | Integration tests shall verify HTTP collection with a mock HTTP server. |
| Req-Test-2 | Integration tests shall verify gRPC transmission with a mock gRPC server. |
| Req-Test-3 | Tests shall use JUnit 5 and Mockito frameworks. |
| Req-Test-4 | All tests shall be executable via 'mvn test' command. |
## User Stories
| Unique ID | Requirement Description |
| Unique ID | Requirement Description |
| --- | --- |
| Req-US-1 | As a system operator, I want HSP to automatically collect diagnostic data from configured HTTP endpoints every second, so that real-time device health can be monitored without manual intervention. |
| Req-US-1 | As a data analyst, I want all collected diagnostic data to be reliably transmitted to the Collector Sender Core via gRPC, so that I can analyze device behavior even if temporary network issues occur. |
| Req-US-1 | As a system administrator, I want to check HSP health status via HTTP endpoint, so that I can monitor the service without accessing logs. |
| Req-US-2 | As a data analyst, I want all collected diagnostic data to be reliably transmitted to the Collector Sender Core via gRPC, so that I can analyze device behavior even if temporary network issues occur. |
| Req-US-3 | As a system administrator, I want to check HSP health status via HTTP endpoint, so that I can monitor the service without accessing logs. |
### Assumptions and Dependencies
The Collector Core Sender gRPC server is always available.
requirements/HSP_Configuration_File_Specification.md
+1 -1
View File
@@ -28,7 +28,7 @@ The Configuration file shall be stored as JSON file.
"retry_interval_seconds": 5
},
"buffer": {
"max_messages": 300000
"max_messages": 300
},
"backoff": {
"http_start_seconds": 5,