docs: document system health checks on run submission

[olivermeyer]

No description provided.

[github-actions]

Claude finished @olivermeyer's task —— View job

---

PR #342 Review: Document System Health Checks ✅

Todo List

• Read all changed documentation files
• Verify documentation follows repository standards
• Check health check feature documentation completeness
• Review for medical device compliance considerations
• Provide comprehensive feedback

---

Summary

This PR successfully documents the automatic system health check enforcement feature across all three SDK interfaces (Launchpad, CLI, and Python Library). The documentation is comprehensive, clear, and accurate, following repository standards. Since this is a documentation-only PR that has already been merged, I'm providing retrospective feedback.

✅ Strengths

1. Comprehensive Coverage Across All Interfaces

The documentation consistently covers health check behavior for all three SDK interfaces:

• README.md (lines 330-344, 418-438, 505-528): User-facing documentation for Launchpad, CLI, and Python Library
• CLAUDE.md files: Implementation details for developers
• Glossary (line 923-924): Standardized definition

2. Clear Differentiation of Behavior

Excellent table in the glossary showing different enforcement levels:

Launchpad: Blocks submission (no override for regular users)
CLI: Blocks by default (--force flag available)
Python Library: No automatic checks (developer control)

3. User-Friendly Documentation

Launchpad section (lines 330-344):

• Clear bullet points explaining the blocking behavior
• Step-by-step troubleshooting guidance
• Link to status page (https://status.aignostics.com)

CLI section (lines 418-438):

• Shows exact error message users will see
• Provides --force flag override examples
• Includes system health command for manual checks

Python Library section (lines 505-528):

• Explains the design rationale (developer control)
• Provides complete code example with error handling
• Lists use cases (retry logic, logging, graceful degradation)

4. Excellent CLAUDE.md Documentation

application/CLAUDE.md (lines 53-101):

• Documents the _abort_if_system_unhealthy() function with actual code
• Table showing which commands enforce health checks
• GUI enforcement explanation with code examples
• Force option for internal users clearly documented

gui/CLAUDE.md (lines 42-76):

• Health monitoring intervals documented
• State management code examples
• Health display components explained

system/CLAUDE.md (lines 44-96):

• Comprehensive table comparing all three interfaces
• Actual code examples for each interface
• Clear explanation of enforcement mechanisms

5. Medical Device Compliance Awareness

The documentation implicitly addresses medical device requirements:

• Prevents data submission when platform unavailable (regulatory compliance)
• Clear audit trail (health status logged)
• Override mechanism for authorized users only (internal organizations)
• Graceful degradation guidance for Python Library users

📋 Minor Suggestions (Optional Improvements)

These are not blocking issues, but could enhance the documentation in future PRs:

1. Health Check Latency

Consider documenting the performance impact:

### Performance Notes

- Health checks add ~50-200ms latency before submission
- CLI: Checks performed on every upload/submit unless --force used
- GUI: Health polled every 30 seconds in background (HEALTH_UPDATE_INTERVAL)
- Python Library: No latency (manual checks only)

2. Health Check Retry Logic

The documentation could mention transient failures:

### Handling Transient Failures

Health checks may fail temporarily due to network issues. For automated workflows:

CLI:
# Retry with exponential backoff
for i in {1..3}; do
  aignostics application run submit ... && break
  sleep $((2**i))
done

Python Library:
# Implement custom retry logic
for attempt in range(3):
    health = SystemService().health()
    if health: break
    time.sleep(2 ** attempt)

3. Internal User Organizations

The application/CLAUDE.md mentions "internal users (Aignostics, pre-alpha-org, LMU, Charite organizations)" can force-skip health checks. Consider documenting this in the user-facing README for transparency.

4. Health Check Components

Users might wonder what "system health" actually checks. Consider adding:

### What the Health Check Verifies

The system health check aggregates status from all SDK modules:

- **Platform**: Authentication status, API connectivity
- **Network**: Aignostics Platform API reachability
- **Authentication**: Valid token, not expired
- **Dependencies**: Required libraries available

🎯 Verification

I verified the documentation against the actual implementation:

✅ CLI enforcement matches application/_cli.py:_abort_if_system_unhealthy()
✅ GUI enforcement matches application/_gui/_page_application_describe.py
✅ Health polling matches gui/_frame.py:HEALTH_UPDATE_INTERVAL
✅ System aggregation matches system/_service.py:health()
✅ Python Library pattern matches best practices

📚 Documentation Quality Assessment

Criterion	Rating	Notes
Accuracy	✅ Excellent	Matches actual implementation
Completeness	✅ Excellent	Covers all three interfaces comprehensively
Clarity	✅ Excellent	Clear examples, step-by-step guidance
Consistency	✅ Excellent	Consistent terminology and structure
Actionable	✅ Excellent	Provides concrete commands and code examples
Medical Device Awareness	✅ Good	Implicitly addresses compliance needs

🏆 Conclusion

This is excellent documentation work that significantly improves the user experience by:

1. ✅ Clearly explaining blocking behavior before users encounter errors
2. ✅ Providing troubleshooting steps for each interface
3. ✅ Documenting override mechanisms appropriately
4. ✅ Giving developers full control in the Python Library

The documentation follows repository standards (Google-style docstrings in code, markdown for user docs) and provides comprehensive coverage across user-facing and developer-facing materials.

No blocking issues found. The optional suggestions above are for future enhancements only.

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.
see 7 files with indirect coverage changes

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud