grm Technical Architecture

• Technical Sub-Spec: TDLib Client Architecture & RAII
  • Module Specification
• Technical Sub-Spec: File Uploader Engine Architecture
  • Architecture Overview
• Technical Sub-Spec: Forum Topics Engine Architecture
  • Architecture Overview
• Technical Architecture: Chat Folder Management Engine
  • Overview
  • TDLib Method Mappings
• [TECH-007] Universal Search Architecture Specification
  • Architecture Overview
  • TDLib API Endpoints
  • Data Structures
• Overview
• Architectural Weaknesses Identified
• Technical Refactoring Requirements
  • 1. Mandatory JSON String Escaping (Injection Protection)
  • 2. DRY Chat Item Resolver Helper Function
• Execution & Verification Protocol
  • Branch Strategy
• Unresolved Architectural Items & Future Optimization Roadmap
• Story & Status Subsystem Architecture Spec
  • Architectural Overview
  • Component Architecture
• Technical Architecture: Shell Autocompletion
  • Overview
  • C++23 Subcommand Help Dispatch
  • Bash Autocompletion Engine
• Technical Architecture: CLI Options & Logging
  • Overview
  • Data Structures
  • Subcommand Option Parsers
  • Logging Utility API
• Technical Architecture: Formatter & Output Distribution
  • Overview
  • Architecture & Domain Boundaries
  • Data Types & Enums
  • TTY Auto-Detection Logic
• Coding Standards
  • Requirement Mapping
  • Core Directives
• Threat Model
  • Requirement Mapping
  • STRIDE Analysis
• [TECH-010] Release Procedure & Versioning Playbook
  • Overview
  • Requirement Mapping
  • Multi-File Version Alignment Checklist
  • Step-by-Step Release Execution Playbook

Architectural Blueprint

The grm tool is implemented as a modern C++23 native application linking against Telegram’s official C++ engine TDLib (libtdjson.so) and json-c.

System Design Principles

1. Modern C++23: Enforces std::expected for error handling, smart pointers for RAII, and explicit type conversions.

2. Asynchronous Receiver Thread: Dedicated worker thread invoking td_receive to process incoming JSON events without blocking the main CLI.

3. Promise-Based Synchronization: Requests sent via td_send carry a unique @extra request ID mapped to a std::promise<JsonValue> for synchronous CLI commands.

4. Zero Peer Hash Bugs: Relies on TDLib’s internal state machine for automatic AccessHash resolution across all supergroups and channels.

Technical Traceability Matrix

Technical Spec ID	Component	Fulfills Requirement
[TECH-001]	grm::TdClient	[FUNC-001], [FUNC-002]
[TECH-002]	grm::JsonValue	[FUNC-003], [FUNC-004]
[TECH-003]	grm::App Controller	[FUNC-005], [FUNC-006]
[TECH-004]	File Uploader Engine	[FUNC-007]
[TECH-005]	Forum Topics Engine	[FUNC-008]
[TECH-006]	Chat Folder Engine	[FUNC-013]
[TECH-007]	Search Engine	[FUNC-014]
[TECH-008]	Search Hardening Engine	[FUNC-014]
[TECH-009]	Story & Status Engine	[FUNC-015]
[TECH-010]	Release Procedure Playbook	[FUNC-001]