Skip to content

docs(core): expand ARCHITECTURE.md with detailed system design#464

Merged
kcenon merged 2 commits into
mainfrom
docs/issue-454-expand-architecture-md
Feb 9, 2026
Merged

docs(core): expand ARCHITECTURE.md with detailed system design#464
kcenon merged 2 commits into
mainfrom
docs/issue-454-expand-architecture-md

Conversation

@kcenon

@kcenon kcenon commented Feb 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Closes #454

Summary

  • Expanded docs/ARCHITECTURE.md from 60 lines to 686 lines with comprehensive system design documentation
  • All content derived from actual source code analysis of 80+ headers across 15+ modules
  • Added ASCII diagrams for module dependencies, data flow, threading model, and plugin architecture

Sections Added

  1. System Architecture Diagram - Module dependency graph, data flow from collection to export, event bus pub/sub topology
  2. Core Pipeline Architecture - thread_local_buffer → central_collector flow, event bus routing, safe event dispatcher, performance monitor orchestration, error handling flow
  3. Threading Model - Thread-local buffer design, thread context management, lock-free queue, fine-grained locking strategy, concurrency summary table
  4. Plugin Architecture - Plugin lifecycle, CRTP collector base pattern, core collectors table, plugin registry and loader
  5. Storage Layer - Backend abstraction (10 types), factory pattern, configuration examples
  6. Adapter & Interface Layer - Cross-system integration (thread/logger/common adapters), DI container, C++20 concepts reference (14 concepts)
  7. Design Decisions - Rationale for event bus, thread-local buffering, CRTP, plugin architecture, Result pattern, C++20 concepts

Test Plan

  • Document exceeds 300 lines (686 lines, up from 60)
  • Architecture diagram with all 15+ modules
  • Data flow diagram from collection to export
  • Threading model fully explained
  • Plugin architecture documented
  • Storage layer architecture covered
  • Design decisions documented with rationale
  • Verify all referenced headers exist in codebase (40/40 headers verified)
  • Review for consistency with existing documentation (terminology matches ARCHITECTURE_GUIDE.md, PROJECT_STRUCTURE.md)

Verification Notes

  • Header existence: All 40 explicitly referenced header paths verified against actual codebase
  • Header counts: Fixed inaccurate counts in Module Reference section (core 7→9, collectors 17→18, adapters 8→10, reliability 5→7, alert 6→7, utils 6→10)
  • Concept count: Fixed from 12→14, added missing ObserverLike concept to table
  • Consistency: Core terminology (Result, CRTP, event_bus, thread_local_buffer) consistent across all documentation

@kcenon
docs(core): expand ARCHITECTURE.md with detailed system design
8d45558 
Expand the main architecture document from 60 lines to 684 lines
covering all major system components based on actual source code
analysis.

New sections:
- System architecture diagram with module dependency graph
- Core pipeline architecture (thread_local_buffer → central_collector)
- Threading model (TLS buffers, lock-free queue, fine-grained locking)
- Plugin architecture (CRTP collector base, hardware/container plugins)
- Storage layer (10 backend types with factory pattern)
- Adapter & interface layer (cross-system integration, C++20 concepts)
- Design decisions with rationale (event bus, TLS buffering, CRTP,
  Result<T> pattern, plugin system, concepts)

Closes #454
@kcenon kcenon mentioned this pull request Feb 8, 2026
Closed
7 tasks
@kcenon
docs(core): fix header counts and concept count in ARCHITECTURE.md
d3e4b85 
Corrected module reference header counts verified against actual codebase:
- core/: 7→9, collectors/: 17→18, adapters/: 8→10
- reliability/: 5→7, alert/: 6→7, utils/: 6→10
- C++20 concepts: 12→14 (added missing ObserverLike to table)
@kcenon kcenon merged commit a8a7506 into main Feb 9, 2026
21 checks passed
@kcenon kcenon deleted the docs/issue-454-expand-architecture-md branch February 9, 2026 00:15
kcenon added a commit that referenced this pull request Apr 13, 2026
@kcenon
docs(core): expand ARCHITECTURE.md with detailed system design (#464)
ad363af 
* docs(core): expand ARCHITECTURE.md with detailed system design

Expand the main architecture document from 60 lines to 684 lines
covering all major system components based on actual source code
analysis.

New sections:
- System architecture diagram with module dependency graph
- Core pipeline architecture (thread_local_buffer → central_collector)
- Threading model (TLS buffers, lock-free queue, fine-grained locking)
- Plugin architecture (CRTP collector base, hardware/container plugins)
- Storage layer (10 backend types with factory pattern)
- Adapter & interface layer (cross-system integration, C++20 concepts)
- Design decisions with rationale (event bus, TLS buffering, CRTP,
  Result<T> pattern, plugin system, concepts)

Closes #454

* docs(core): fix header counts and concept count in ARCHITECTURE.md

Corrected module reference header counts verified against actual codebase:
- core/: 7→9, collectors/: 17→18, adapters/: 8→10
- reliability/: 5→7, alert/: 6→7, utils/: 6→10
- C++20 concepts: 12→14 (added missing ObserverLike to table)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Task] docs: Expand ARCHITECTURE.md with detailed system design

1 participant

@kcenon