In a world where scientific simulations and complex applications drown in tangled object hierarchies, Samstraumr emerges as a breath of fresh air—a flowing river of clarity cutting through chaotic code landscapes. It liberates researchers and engineers from the tyranny of rigid, brittle systems that collapse under their own complexity, offering instead a living architecture that breathes, adapts, and heals like natural organisms. By weaving together composable units that communicate through elegant event flows rather than tight coupling, Samstraumr empowers scientists to focus on discovery rather than debugging, enabling simulations that evolve alongside insight and code that transforms as gracefully as the natural systems it often models.
Samstraumr (S8r) is an enterprise Java framework for building resilient, self-healing software systems with adaptive components and event-driven architecture. Inspired by natural systems' resilience, it enables applications that autonomously monitor, adapt, and recover from disruptions.
"Samstraumr (Old Norse: 'unified flow'): A framework where components intelligently collaborate like organisms in an ecosystem, evolving to meet changing demands while maintaining system integrity."
| What is S8r? | Why Use It? | Core Concepts | Getting Started | Documentation |
|---|---|---|---|---|
| CLI Reference | Project Structure | Contributing | License | Project Status |
Samstraumr is an enterprise-grade framework for building resilient, adaptive software systems using Clean Architecture principles and event-driven communication. It implements natural systems theory in software, bringing biological resilience patterns to enterprise applications.
The framework excels at managing complexity in distributed systems, service ecosystems, and high-reliability applications where traditional approaches fail to address constantly changing environments.
- 🔍 Self-monitor: Built-in observability with adaptive responses
- 🔄 Reconfigure: Dynamic component relationship adjustment
- 📊 Scale precisely: Targeted scaling without system-wide changes
- 🛠️ Recover automatically: Component-level failure recovery
- 🌱 Evolve continuously: Incremental adaptation without rewrites
- 🛡️ Validate comprehensively: Early error detection with clear feedback
Learn More: 📜 Origins and Vision • 🌿 Systems Theory Foundation • 🧩 Core Concepts
| Challenge | Samstraumr Solution |
|---|---|
| Fragile Systems | Self-monitoring components prevent cascading failures in production |
| Technical Debt | Clean Architecture with clear boundaries prevents debt accumulation |
| Complex Integrations | Event-driven patterns create loosely coupled system interactions |
| Operational Opacity | Comprehensive observability with built-in component monitoring |
| Inconsistent Recovery | Standardized lifecycle management with predictable recovery paths |
| Silent Failures | Comprehensive validation system with early failure detection |
🏛️ Enterprise Architects
- Reduced technical debt through strict boundaries
- Evolution-friendly architecture adapts without rewrites
- Built-in resilience for mission-critical systems
- Structured approach to distributed complexity
👩💻 Development Teams
- Well-defined component responsibilities
- Isolated components for parallel development
- Consistent patterns across system domains
- Self-documenting architecture with clear contracts
- Early failure detection with detailed validation errors
💼 Business Stakeholders
- Lower maintenance costs via self-healing
- Improved continuity with fault-tolerance
- Targeted scaling optimizes infrastructure costs
- Future-friendly evolution with business needs
Samstraumr implements a cohesive set of architectural concepts that work together to create resilient, adaptive systems:
- 🧩 Components: Self-contained processing units with state awareness
- 🔄 Composites: Coordinated component collections forming pipelines
- ⚙️ Machines: Orchestrated composites implementing subsystems
- ➡️ Flow-Oriented: Data and control along well-defined pathways
- 🏷️ Identity: Hierarchical addressing for all system elements
- 📢 Event-Driven: Loose coupling through publish-subscribe patterns
- 🛡️ Validation: Comprehensive checks at all system boundaries
📘 Learn more about core concepts
- Java: JDK 21 (recommended) or JDK 17
- Maven: 3.9 or higher
- Git: Latest version
# Clone the repository
git clone https://github.com/heymumford/Samstraumr.git
cd Samstraumr
# Build project
./s8r-build
# Run all tests
./s8r-test all
# Run tests with coverage analysis
./s8r-test all --coverageMaven dependency:
<dependency>
<groupId>org.samstraumr</groupId>
<artifactId>samstraumr-core</artifactId>
<version>3.0.5</version>
</dependency>// Create environment
Environment env = new Environment.Builder("validation-env")
.withParameter("strictMode", "true")
.build();
// Create component
Component validator = new EmailValidatorComponent(env);
// Process data
ValidationResult result = (ValidationResult)
validator.process("[email protected]");
// Check result
if (result.isValid()) {
System.out.println("Email is valid!");
}🚀 Complete Getting Started Guide
- Prerequisites
- Getting Started
- Model Visualization
- Composition Strategies
- Component Patterns
- Migration Guide
- Testing in the Age of AI - Eric C. Mumford
- AI-Enhanced Testing Integration - Eric C. Mumford
- QA Cognitive Transformation - Eric C. Mumford
- Cell Activity Simulation - Eric C. Mumford
- Architecture Overview
- Clean Architecture
- Event-Driven Design
- Integration Patterns
- Monitoring & Management
🧪 Current Development: We're using Test-Driven Development with BDD/Cucumber. Recently completed lifecycle test infrastructure enhancements with specialized test runners and improved script utilities. For current status and work in progress, see our KANBAN Board and Test Suite Implementation Report.
The project follows strict Maven and Cucumber configuration standards to ensure maintainable, reliable tests:
- Maven Configuration: Structured POM hierarchy with inheritance and proper dependency management
- Cucumber Configuration: Standardized properties files with parallel execution and proper reporting
- Test Organization: Well-defined directory structure with clear separation of concerns
- Configuration Documentation: Comprehensive documentation with absolute paths for all configuration files
Samstraumr provides a unified CLI for all operations:
# Main command format
./s8r <command> [options] [arguments]
# Example commands
./s8r init --package com.example.model # Initialize a new S8r model
./s8r list --format tree # Visualize model in tree format
./s8r build fast --ci # Fast build with local CI check
./s8r test unit --parallel # Run unit tests in parallel
./s8r version bump minor # Bump minor version
./s8r docs target/docs pdf # Generate PDF documentation| Command | Description |
|---|---|
./s8r init [options] |
Initialize a new S8r model repository |
./s8r list [options] |
Visualize S8r models in ASCII or tree format |
./s8r component <cmd> |
Manage components (create, list, info, delete) |
./s8r composite <cmd> |
Manage composites (create, add, connect, list) |
./s8r machine <cmd> |
Manage machines (create, add, connect, list) |
./s8r build [mode] |
Build project (fast, test, package, install, full) |
./s8r test <type> |
Run tests (unit, component, integration, all...) |
./s8r version <cmd> |
Manage versions (get, bump, set, fix) |
./s8r docs [dir] [fmt] |
Generate documentation with Docmosis |
./s8r-docs <cmd> |
Check documentation integrity (check, fix, report) |
./s8r-ci [options] |
Run GitHub Actions workflows locally using nektos/act |
./s8r docmosis <cmd> |
Manage Docmosis integration (setup, test, install) |
./s8r report <from> <to> |
Generate change management reports |
Samstraumr integrates with Docmosis for professional document generation:
# Set up Docmosis configuration
./s8r docmosis setup
# Generate documentation
./s8r docs target/docs pdf
# Generate a change report
./s8r report 1.7.2 1.7.3Document Generation Features:
- PDF, DOCX, and HTML output formats
- Change management reports
- Release notes generation
- Template-based documentation
- Centralized configuration
The Samstraumr repository follows a well-organized directory structure:
Samstraumr/ # Core implementation and Maven structure
docs/ # Documentation and reference materials
quality-tools/ # Code quality configurations
util/ # Utility scripts and tools
src/ # Example implementations
Organization Principles:
- 🔍 Clear Purpose: Each directory has a singular, well-defined responsibility
- 📊 Critical Mass: New folders require 5+ related files
- 📄 Documented: Every directory has a README explaining its purpose
- 🏷️ Naming Focus: Prefer file naming over deep nesting
📁 Directory Structure Overview • 🏛️ Architecture Mapping • 📋 Folder Management Guidelines
We welcome contributions from the community! Please read our Contribution Guidelines before submitting pull requests.
- 🍴 Fork repo
- 🌿 Create branch
- 👩💻 Make changes
- 🧪 Run tests
- 📤 Submit PR
📝 Development Standards • 🔄 Commit Guidelines • ✅ Quality Checks • 📋 TODO Guidelines
This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.
This project was developed with analytical assistance from:
- Claude 3.7 Sonnet LLM by Anthropic
- Claude Code executable
- Google Gemini Deep Research LLM
These AI tools were used as paid analytical services to assist in development. All intellectual property rights remain with Eric C. Mumford (@heymumford).
- Author: Eric C. Mumford
- GitHub: github.com/heymumford
- LinkedIn: linkedin.com/in/eric-mumford
Copyright © 2025 Eric C. Mumford. All rights reserved.
//: # (Description: Samstraumr (S8r): Enterprise-grade framework for resilient, self-healing software systems with adaptive components and event-driven architecture) //: # (Keywords: resilient systems, adaptive software, event-driven architecture, enterprise framework, self-healing systems, java framework, component-based architecture, systems theory, clean architecture) //: # (Author: Eric C. Mumford) //: # (Canonical: https://github.com/heymumford/Samstraumr)