{"id":31363852,"url":"https://github.com/kcenon/common_system","last_synced_at":"2025-09-27T05:26:25.033Z","repository":{"id":316563983,"uuid":"1063908428","full_name":"kcenon/common_system","owner":"kcenon","description":"🔧 Modern C++17 header-only library providing common interfaces and design patterns for modular system architecture","archived":false,"fork":false,"pushed_at":"2025-09-25T11:27:42.000Z","size":81,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-25T11:31:22.971Z","etag":null,"topics":["architecture","cpp17","dependency-injection","design-patterns","error-handling","executor-pattern","header-only","interface","modular-architecture","result-type"],"latest_commit_sha":null,"homepage":"https://github.com/kcenon/common_system/wiki","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kcenon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T09:25:25.000Z","updated_at":"2025-09-25T10:51:33.000Z","dependencies_parsed_at":"2025-09-25T11:31:26.115Z","dependency_job_id":"e3a22443-a480-43a1-bd89-1368823318ff","html_url":"https://github.com/kcenon/common_system","commit_stats":null,"previous_names":["kcenon/common_system"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kcenon/common_system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kcenon%2Fcommon_system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kcenon%2Fcommon_system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kcenon%2Fcommon_system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kcenon%2Fcommon_system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kcenon","download_url":"https://codeload.github.com/kcenon/common_system/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kcenon%2Fcommon_system/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277184148,"owners_count":25775286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-27T02:00:08.978Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","cpp17","dependency-injection","design-patterns","error-handling","executor-pattern","header-only","interface","modular-architecture","result-type"],"created_at":"2025-09-27T05:26:21.871Z","updated_at":"2025-09-27T05:26:25.027Z","avatar_url":"https://github.com/kcenon.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Ubuntu-GCC](https://github.com/kcenon/common_system/actions/workflows/build-ubuntu-gcc.yaml/badge.svg)](https://github.com/kcenon/common_system/actions/workflows/build-ubuntu-gcc.yaml)\n[![Ubuntu-Clang](https://github.com/kcenon/common_system/actions/workflows/build-ubuntu-clang.yaml/badge.svg)](https://github.com/kcenon/common_system/actions/workflows/build-ubuntu-clang.yaml)\n[![Windows-MSYS2](https://github.com/kcenon/common_system/actions/workflows/build-windows-msys2.yaml/badge.svg)](https://github.com/kcenon/common_system/actions/workflows/build-windows-msys2.yaml)\n[![Windows-VisualStudio](https://github.com/kcenon/common_system/actions/workflows/build-windows-vs.yaml/badge.svg)](https://github.com/kcenon/common_system/actions/workflows/build-windows-vs.yaml)\n[![License](https://img.shields.io/github/license/kcenon/common_system)](https://github.com/kcenon/common_system/blob/main/LICENSE)\n\n# Common System Project\n\n## Project Overview\n\nThe Common System Project is a foundational C++17 header-only library providing essential interfaces and design patterns for building modular, loosely-coupled system architectures. Designed as the cornerstone of the ecosystem, it enables seamless integration between system modules while maintaining zero runtime overhead through template-based abstractions and interface-driven design.\n\n\u003e **🏗️ Modular Architecture**: Pure header-only design with zero dependencies, providing universal interfaces for executor patterns, error handling, and event-driven communication.\n\n\u003e **✅ Latest Updates**: Complete separation from individual modules, comprehensive Result\u003cT\u003e pattern implementation, IExecutor interface standardization, and centralized build configuration. All interfaces production-ready with full ecosystem compatibility.\n\n## 🔗 Project Ecosystem \u0026 Inter-Dependencies\n\nThis common system serves as the foundational layer that all other system modules build upon, providing standardized interfaces and patterns:\n\n### Core Purpose\n- **Interface Standardization**: Universal abstractions for cross-module communication\n- **Pattern Library**: Reusable design patterns for error handling and event-driven architecture\n- **Build Configuration**: Centralized feature flags and build options for all modules\n- **Zero Coupling**: Pure interfaces with no implementation dependencies\n\n### Dependent Projects\n- **[thread_system](https://github.com/kcenon/thread_system)**: Core threading framework\n  - Uses: IExecutor interface for task abstraction\n  - Provides: Thread pool implementations of IExecutor\n  - Integration: Adapter pattern for seamless executor usage\n\n- **[network_system](https://github.com/kcenon/network_system)**: Asynchronous network library\n  - Uses: IExecutor for async operation scheduling\n  - Benefits: Threading backend independence\n  - Integration: Executor adapters for network operations\n\n- **[logger_system](https://github.com/kcenon/logger_system)**: High-performance logging\n  - Uses: Result\u003cT\u003e for error handling\n  - Benefits: Exception-free error propagation\n  - Integration: Optional event bus for log routing\n\n- **[monitoring_system](https://github.com/kcenon/monitoring_system)**: Metrics and monitoring\n  - Provides: Event bus implementation\n  - Uses: Common event types and interfaces\n  - Integration: Central hub for system events\n\n- **[container_system](https://github.com/kcenon/container_system)**: Data serialization\n  - Uses: Result\u003cT\u003e for operation results\n  - Benefits: Type-safe error handling\n  - Integration: Common error codes\n\n- **[database_system](https://github.com/kcenon/database_system)**: Database abstraction\n  - Uses: Result\u003cT\u003e for query results\n  - Benefits: Consistent error handling\n  - Integration: Async operations via IExecutor\n\n### Dependency Architecture\n```\n                    ┌──────────────────┐\n                    │  common_system   │ ◄── Foundation Layer\n                    │  (interfaces)    │\n                    └────────┬─────────┘\n                             │ provides interfaces\n       ┌─────────────────────┼─────────────────────┐\n       │                     │                     │\n┌──────▼───────┐    ┌────────▼────────┐   ┌───────▼────────┐\n│thread_system │    │network_system   │   │monitoring_sys. │\n│(implements   │    │(uses IExecutor) │   │(event bus)     │\n│ IExecutor)   │    └─────────────────┘   └────────────────┘\n└──────────────┘             │                     │\n       │                     │                     │\n       └─────────────────────┼─────────────────────┘\n                             │ all use\n                    ┌────────▼─────────┐\n                    │ Result\u003cT\u003e pattern│\n                    │ Error handling   │\n                    └──────────────────┘\n```\n\n### Integration Benefits\n- **Universal interfaces**: Single source of truth for cross-module contracts\n- **Zero-overhead abstractions**: Template-based design with compile-time resolution\n- **Incremental adoption**: Use only the patterns and interfaces you need\n- **Future-proof design**: Ready for C++23 std::expected migration\n- **Ecosystem consistency**: Unified error handling and event patterns\n\n\u003e 📖 **[Complete Architecture Guide](docs/ARCHITECTURE.md)**: Comprehensive documentation of interface contracts, integration patterns, and best practices.\n\n## Project Purpose \u0026 Mission\n\nThis project addresses the fundamental challenge in large-scale C++ development: **achieving true modularity without sacrificing performance**. Traditional approaches often lead to tight coupling, inconsistent interfaces, and fragmented error handling. Our mission is to provide:\n\n- **Eliminate tight coupling** through pure interface definitions and dependency inversion\n- **Standardize patterns** with consistent error handling and event-driven communication\n- **Enable testing** through interface-based design and mockable abstractions\n- **Simplify integration** with header-only distribution and zero dependencies\n- **Future-proof architecture** with modern C++ patterns ready for upcoming standards\n\n## Core Advantages \u0026 Benefits\n\n### 🚀 **Performance Excellence**\n- **Zero-overhead abstractions**: Template-based interfaces with compile-time resolution\n- **Header-only design**: No library linking, better optimization opportunities\n- **Cache-friendly patterns**: Minimal indirection and optimal memory layout\n- **Compile-time optimization**: Full inlining potential for hot paths\n\n### 🛡️ **Production-Grade Reliability**\n- **Type-safe interfaces**: Strong typing prevents runtime errors\n- **Result\u003cT\u003e pattern**: Explicit error handling without exceptions\n- **RAII compliance**: Resource management through standard patterns\n- **Thread-safe design**: All interfaces safe for concurrent use\n\n### 🔧 **Developer Productivity**\n- **Self-documenting interfaces**: Clear contracts with comprehensive documentation\n- **Minimal boilerplate**: Clean API design reduces code overhead\n- **Mockable abstractions**: Easy testing through interface injection\n- **IDE-friendly**: Full IntelliSense and autocomplete support\n\n### 🌐 **Universal Compatibility**\n- **C++17 baseline**: Works with all modern compilers\n- **Cross-platform**: Windows, Linux, macOS without modification\n- **Build system agnostic**: CMake, Bazel, Make - all supported\n- **Package manager ready**: vcpkg, Conan integration available\n\n### 📈 **Enterprise-Ready Features**\n- **Interface versioning**: Backward compatibility through careful design\n- **Centralized configuration**: Unified build flags across all modules\n- **Comprehensive testing**: Full test coverage with GTest integration\n- **Production examples**: Real-world usage patterns included\n\n## Getting Started\n\n### System Requirements\n\n- **Compiler**: C++17 compatible (GCC 7+, Clang 5+, MSVC 2017+)\n- **Build System**: CMake 3.16 or higher\n- **Optional**: vcpkg or Conan for dependency management\n- **Platform**: Windows, Linux, macOS (all architectures)\n\n### Quick Installation\n\n#### Option 1: Header-Only Usage (Simplest)\n```bash\ngit clone https://github.com/kcenon/common_system.git\n# Include headers directly - no build required!\n```\n\n```cpp\n// In your code\n#include \u003ckcenon/common/interfaces/executor_interface.h\u003e\n#include \u003ckcenon/common/patterns/result.h\u003e\n```\n\n#### Option 2: CMake Integration\n```cmake\n# Using FetchContent (recommended)\ninclude(FetchContent)\nFetchContent_Declare(\n    common_system\n    GIT_REPOSITORY https://github.com/kcenon/common_system.git\n    GIT_TAG main\n)\nFetchContent_MakeAvailable(common_system)\n\ntarget_link_libraries(your_target PRIVATE kcenon::common)\n```\n\n#### Option 3: System-wide Installation\n```bash\ngit clone https://github.com/kcenon/common_system.git\ncd common_system\n./build.sh --release --install-prefix=/usr/local\nsudo cmake --build build --target install\n```\n\n### Building from Source\n\n```bash\n# Clone repository\ngit clone https://github.com/kcenon/common_system.git\ncd common_system\n\n# Build with tests and examples\n./build.sh --release --tests --examples\n\n# Run tests\n./test.sh\n\n# Clean build artifacts\n./clean.sh\n```\n\n### Windows Build\n\n```batch\nREM Using Visual Studio 2022\nbuild.bat --vs2022 --release\n\nREM Run tests\ntest.bat --release\n\nREM Clean artifacts\nclean.bat\n```\n\n## Core Components\n\n### IExecutor Interface\n\nUniversal task execution abstraction for any threading backend:\n\n```cpp\n#include \u003ckcenon/common/interfaces/executor_interface.h\u003e\n\nclass MyService {\n    std::shared_ptr\u003ccommon::interfaces::IExecutor\u003e executor_;\n\npublic:\n    void process_async(const Data\u0026 data) {\n        auto future = executor_-\u003esubmit([data]() {\n            // Process data asynchronously\n            return process(data);\n        });\n\n        // Continue with other work...\n    }\n};\n```\n\n### Result\u003cT\u003e Pattern\n\nType-safe error handling without exceptions:\n\n```cpp\n#include \u003ckcenon/common/patterns/result.h\u003e\n\ncommon::Result\u003cConfig\u003e load_config(const std::string\u0026 path) {\n    if (!std::filesystem::exists(path)) {\n        return common::error\u003cConfig\u003e(\n            common::error_codes::NOT_FOUND,\n            \"Configuration file not found\",\n            \"config_loader\"\n        );\n    }\n\n    try {\n        auto config = parse_json_file(path);\n        return common::ok(config);\n    } catch (const std::exception\u0026 e) {\n        return common::error\u003cConfig\u003e(\n            common::error_codes::INVALID_ARGUMENT,\n            e.what(),\n            \"config_loader\"\n        );\n    }\n}\n\n// Usage with monadic operations\nauto result = load_config(\"app.conf\")\n    .and_then(validate_config)\n    .map(apply_defaults)\n    .or_else([](const auto\u0026 error) {\n        log_error(error);\n        return load_fallback_config();\n    });\n```\n\n### Event Bus Integration\n\nWhen used with monitoring_system:\n\n```cpp\n#include \u003ckcenon/common/patterns/event_bus.h\u003e\n\n// Publish events\nauto bus = common::get_event_bus();\nbus-\u003epublish(common::events::module_started_event(\"my_service\"));\n\n// Subscribe to events\nbus-\u003esubscribe\u003ccommon::events::error_event\u003e([](const auto\u0026 event) {\n    std::cerr \u003c\u003c \"Error in \" \u003c\u003c event.module_name\n              \u003c\u003c \": \" \u003c\u003c event.error_message \u003c\u003c std::endl;\n});\n```\n\n## Integration Examples\n\n### With thread_system\n\n```cpp\n#include \u003ckcenon/thread/core/thread_pool.h\u003e\n#include \u003ckcenon/thread/adapters/common_executor_adapter.h\u003e\n\n// Create thread pool\nauto thread_pool = std::make_shared\u003ckcenon::thread::thread_pool\u003e(4);\n\n// Adapt to common interface\nauto executor = kcenon::thread::adapters::make_common_executor(thread_pool);\n\n// Use with any IExecutor-based API\nprocess_with_executor(executor);\n```\n\n### With network_system\n\n```cpp\n#include \u003cnetwork_system/integration/executor_adapter.h\u003e\n\n// Use common executor with network system\nvoid setup_network(std::shared_ptr\u003ccommon::interfaces::IExecutor\u003e executor) {\n    auto adapted_pool = network_system::integration::make_thread_pool_adapter(executor);\n\n    network_system::server server(adapted_pool);\n    // Network operations now use the common executor\n}\n```\n\n## Testing\n\nThe project includes comprehensive unit tests:\n\n```bash\n# Run all tests\n./test.sh\n\n# Run with coverage\n./test.sh --coverage\n\n# Run specific tests\n./test.sh --filter \"Result*\"\n\n# Benchmark tests\n./test.sh --benchmark\n```\n\n## Documentation\n\n- [API Reference](docs/API.md)\n- [Architecture Guide](docs/ARCHITECTURE.md)\n- [Integration Guide](docs/INTEGRATION.md)\n- [Error Handling Guide](docs/ERRORS.md)\n- [Migration Guide](docs/MIGRATION.md)\n\n## Performance Benchmarks\n\n| Operation | Time (ns) | Allocations |\n|-----------|-----------|-------------|\n| Result\u003cT\u003e creation | 2.3 | 0 |\n| Result\u003cT\u003e error check | 0.8 | 0 |\n| IExecutor submit | 45.2 | 1 |\n| Event publish | 12.4 | 0 |\n\n*Benchmarked on Intel i7-9700K @ 3.6GHz with GCC 11.2 -O3*\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Code Style\n\n- Follow the existing code style (clang-format configuration provided)\n- Write comprehensive unit tests for new features\n- Update documentation as needed\n- Ensure all tests pass before submitting PR\n\n## Roadmap\n\n- [x] IExecutor interface standardization\n- [x] Result\u003cT\u003e pattern implementation\n- [x] Event bus forwarding\n- [x] Centralized build configuration\n- [ ] C++20 concepts for interface constraints\n- [ ] Coroutine support for async patterns\n- [ ] std::expected migration (C++23)\n- [ ] Additional design patterns (Observer, Command)\n- [ ] Package manager official support\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/kcenon/common_system/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/kcenon/common_system/discussions)\n- **Email**: kcenon@naver.com\n\n## License\n\nThis project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by Rust's Result\u003cT,E\u003e type and error handling\n- Interface design influenced by Java's ExecutorService\n- Event bus pattern from reactive programming frameworks\n- Build system patterns from modern C++ best practices\n\n## Citation\n\nIf you use this project in your research or commercial projects, please cite:\n\n```bibtex\n@software{common_system,\n  author = {Dongcheol Shin},\n  title = {Common System: Foundational Interfaces for Modular C++ Architecture},\n  year = {2024},\n  url = {https://github.com/kcenon/common_system}\n}\n```\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eBuilding Better C++ Systems Together\u003c/b\u003e\u003cbr\u003e\n  Made with ❤️ by the C++ Community\n\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkcenon%2Fcommon_system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkcenon%2Fcommon_system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkcenon%2Fcommon_system/lists"}