Skip to content

[Task] docs: Create cross-system integration guide #329

Description

@kcenon

Summary

Create a comprehensive cross-system integration guide documenting how the 7 kcenon ecosystem systems work together, with dependency maps, initialization sequences, and integration patterns.

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (#325)

Background (Why)

The kcenon ecosystem consists of 7 C++ systems plus Rust ports, but there is no documentation explaining how to integrate multiple systems together. Each system's docs exist in isolation. A developer wanting to build an application using multiple systems (e.g., network + database + logging + monitoring) has no guide for:

  • Initialization order and dependency resolution
  • Service container setup with multiple systems
  • Adapter wiring between systems
  • Shared configuration management

Scope (What)

Create docs/INTEGRATION_GUIDE.md covering:

1. Ecosystem Dependency Map

common_system (Tier 0 - Foundation)
    ├── thread_system (Tier 1)
    │   ├── logger_system (Tier 2)
    │   │   └── database_system (Tier 3)
    │   └── monitoring_system (Tier 2, Rust)
    ├── container_system (Tier 1)
    └── network_system (Tier 2)

2. Integration Patterns

Using unified_bootstrapper

auto system = unified_bootstrapper::create()
    .add<thread_system>()
    .add<logger_system>()
    .add<database_system>()
    .add<network_system>()
    .configure(config)
    .bootstrap();

Manual Adapter Wiring

  • typed_adapter for cross-system connections
  • Service container registration
  • Lifecycle management

3. Common Integration Scenarios

Scenario Systems Key Config
Web API Server common + thread + logger + network HTTP facade + async logger
Data Pipeline common + thread + database + container Async DB + typed containers
Monitoring Stack common + thread + monitoring + logger Metrics + structured logging
Full Stack All 7 systems Complete bootstrapper setup

4. Configuration Across Systems

  • Unified config with per-system sections
  • Shared settings (thread pool sizes, log levels)
  • System-specific overrides

5. Error Handling Across Systems

  • Error code ranges by system
  • Cross-system error propagation
  • Result composition patterns

6. Initialization and Shutdown

  • Bootstrap order (respecting dependencies)
  • Graceful shutdown sequence (reverse order)
  • Timeout handling during shutdown
  • Resource cleanup guarantees

7. Complete Example Application

  • Full 100-line example using 4+ systems together
  • Build system (CMakeLists.txt) setup for multi-system

Acceptance Criteria

  • Dependency map with all 7 systems documented
  • Bootstrapper usage guide
  • At least 4 integration scenario examples
  • Error handling across systems explained
  • Initialization/shutdown sequence documented
  • Complete example application with build setup
  • Korean translation created

Metadata

Metadata

Assignees

Labels

architectureArchitectural changes and designdocumentationImprovements or additions to documentationpriority:highHigh priority issue

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions