Docs/service documentation corrections (#117)

Author: torrejonv

.markdownlint.yml

@@ -29,6 +29,10 @@ MD032: true   # Lists should be surrounded by blank lines
 MD003:
   style: "atx"  # Use # for headers
 
+# Allow duplicate headings in different sections
+MD024:
+  siblings_only: true  # Only flag duplicate headings that are siblings
+
 # Trailing whitespace
 MD009: true
 

docs/topics/services/img/plantuml/rpc/RPC_Component.svg

@@ -28,29 +28,7 @@ title RPC Service - Component Diagram (Code-Verified Connections)
 
 Container_Boundary(rpc_service, "RPC Service") {
 
-Component(http_server, "HTTP Server", "Go HTTP", "JSON-RPC over HTTP endpoint")
-
-Component(json_rpc_handler, "JSON-RPC Handler", "Go", "Processes JSON-RPC requests and responses")
-
-Component(command_router, "Command Router", "Go", "Routes RPC commands to appropriate handlers")
-
-Component(blockchain_handlers, "Blockchain Handlers", "Go", "Block and chain operation handlers")
-
-Component(mining_handlers, "Mining Handlers", "Go", "Mining and block template handlers")
-
-Component(peer_handlers, "Peer Handlers", "Go", "Peer management handlers")
-
-Component(utxo_handlers, "UTXO Handlers", "Go", "UTXO query and management handlers")
-
-Component(admin_handlers, "Admin Handlers", "Go", "Administrative operation handlers")
-
-Component(transaction_handlers, "Transaction Handlers", "Go", "Transaction submission handlers")
-
-Component(help_cacher, "Help Cacher", "Go", "Caches RPC command help text")
-
-Component(metrics_collector, "Metrics Collector", "Prometheus", "Collects RPC performance metrics")
-
-Component(health_monitor, "Health Monitor", "Go", "Monitors service and dependency health")
+Component(rpc_server, "RPC Server", "Go", "HTTP server with JSON-RPC handler routing commands to handler functions")
 
 Component(blockchain_client, "Blockchain Client", "Go gRPC", "Interface to Blockchain service")
 
@@ -92,45 +70,25 @@ Person(admin, "Administrator", "Node operator")
 
 ' External API interactions
 
-Rel(external_user, http_server, "JSON-RPC requests", "HTTP")
-
-Rel(admin, http_server, "Administrative requests", "HTTP")
-
-' Request processing flow
-
-Rel(http_server, json_rpc_handler, "Parse JSON-RPC")
-
-Rel(json_rpc_handler, command_router, "Route commands")
-
-Rel(command_router, blockchain_handlers, "Blockchain commands")
+Rel(external_user, rpc_server, "JSON-RPC requests", "HTTP")
 
-Rel(command_router, mining_handlers, "Mining commands")
+Rel(admin, rpc_server, "Administrative requests", "HTTP")
 
-Rel(command_router, peer_handlers, "Peer commands")
+' RPC Server to service client interactions
 
-Rel(command_router, utxo_handlers, "UTXO commands")
+Rel(rpc_server, blockchain_client, "Blockchain and admin operations")
 
-Rel(command_router, admin_handlers, "Admin commands")
+Rel(rpc_server, block_assembly_client, "Mining operations")
 
-Rel(command_router, transaction_handlers, "Transaction commands")
+Rel(rpc_server, propagation_client, "Submit transactions")
 
-' Handler to client interactions
+Rel(rpc_server, p2p_client, "P2P operations")
 
-Rel(blockchain_handlers, blockchain_client, "Blockchain operations")
+Rel(rpc_server, legacy_peer_client, "Legacy peer operations")
 
-Rel(mining_handlers, block_assembly_client, "Mining operations")
+Rel(rpc_server, utxo_store_client, "UTXO queries and operations")
 
-Rel(transaction_handlers, propagation_client, "Submit transactions")
-
-Rel(peer_handlers, p2p_client, "P2P operations")
-
-Rel(peer_handlers, legacy_peer_client, "Legacy peer operations")
-
-Rel(utxo_handlers, utxo_store_client, "UTXO queries and operations")
-
-Rel(admin_handlers, blockchain_client, "Administrative operations")
-
-Rel(blockchain_handlers, asset_http_client, "Transaction hex data")
+Rel(rpc_server, asset_http_client, "Transaction hex data")
 
 ' Service client connections (CODE-VERIFIED)
 
@@ -148,27 +106,6 @@ Rel(utxo_store_client, utxo_store, "Database queries", "Direct")
 
 Rel(asset_http_client, asset_server, "HTTP requests", "HTTP")
 
-' Support components
-
-Rel(command_router, help_cacher, "Get command help")
-
-Rel(json_rpc_handler, metrics_collector, "Request metrics")
-
-Rel(health_monitor, blockchain_client, "Health checks")
-
-Rel(health_monitor, block_assembly_client, "Health checks")
-
-Rel(health_monitor, p2p_client, "Health checks")
-
-Rel(health_monitor, utxo_store_client, "Health checks")
-
-Rel(health_monitor, propagation_client, "Health checks")
-
-Rel(health_monitor, asset_http_client, "Health checks")
-
-' Administrative access
-
-Rel(admin, http_server, "Administrative operations", "HTTP")
 
 SHOW_LEGEND()
 

docs/topics/services/img/plantuml/rpc/rpc_detailed_component.puml

@@ -24,33 +24,29 @@ skinparam ArrowColor #666666
 
 !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
 
-title Subtree Validation Service - Component Diagram (Code-Verified Connections)
+title Subtree Validation Service - Component Diagram
 
 Container_Boundary(subtree_validation, "Subtree Validation Service") {
 
 Component(grpc_server, "gRPC Server", "Go gRPC", "Handles external subtree validation API requests")
 
-Component(kafka_consumer_subtrees, "Subtree Consumer", "Go Kafka", "Consumes subtree notifications from P2P service")
-
-Component(kafka_consumer_txmeta, "TxMeta Consumer", "Go Kafka", "Consumes transaction metadata updates")
+Component(subtree_handler, "Subtree Handler", "Go", "Handles subtree validation requests with file-based locking and transaction fetching")
 
-Component(kafka_producer_txmeta, "TxMeta Producer", "Go Kafka", "Publishes validated transaction metadata")
+Component(txmeta_handler, "TxMeta Handler", "Go", "Handles transaction metadata cache updates")
 
-Component(subtree_validator, "Subtree Validator", "Go", "Core subtree validation logic")
-
-Component(transaction_fetcher, "Transaction Fetcher", "Go", "Fetches missing transactions from remote sources")
+Component(kafka_consumer_subtrees, "Subtree Consumer", "Go Kafka", "Consumes subtree notifications from P2P service")
 
-Component(metadata_processor, "Metadata Processor", "Go", "Processes and caches transaction metadata")
+Component(kafka_consumer_txmeta, "TxMeta Consumer", "Go Kafka", "Consumes transaction metadata updates")
 
-Component(quorum_manager, "Quorum Manager", "Go", "Distributed locking for concurrent validation")
+Component(kafka_producer_invalid, "Invalid Subtree Producer", "Go Kafka", "Publishes invalid subtree notifications")
 
-Component(http_client, "HTTP Client", "Go HTTP", "HTTP client for asset server communication")
+Component(validator_client, "Validator Client", "Go", "Interface to Validator service for transaction validation")
 
-Component(validator_interface, "Validator Interface", "Go", "Local/remote validator integration")
+Component(blockchain_client, "Blockchain Client", "Go gRPC", "Interface to Blockchain service")
 
-Component(metrics_collector, "Metrics Collector", "Prometheus", "Collects validation performance metrics")
+Component(utxo_store_client, "UTXO Store Client", "Go", "Interface to UTXO store for metadata operations")
 
-Component(health_monitor, "Health Monitor", "Go", "Monitors service and dependency health")
+Component(blob_stores, "Blob Store Clients", "Go", "Subtree and transaction blob storage interfaces")
 
 }
 
@@ -60,9 +56,11 @@ Container(validator, "Validator Service", "Go", "Transaction validation")
 
 Container(blockchain, "Blockchain Service", "Go", "Blockchain state management")
 
-Container(subtree_store, "Subtree Store", "Blob Store", "Validated subtree storage")
+ContainerDb(subtree_store, "Subtree Store", "Blob Store", "Validated subtree storage")
+
+ContainerDb(tx_store, "Transaction Store", "Blob Store", "Transaction data storage")
 
-Container(utxo_store, "UTXO Store", "Database", "UTXO and transaction metadata")
+ContainerDb(utxo_store, "UTXO Store", "Database", "UTXO and transaction metadata")
 
 ContainerQueue(kafka, "Kafka", "Message Queue", "Message broker")
 
@@ -86,69 +84,47 @@ Rel(legacy_service, grpc_server, "Validate subtrees during sync", "gRPC")
 
 Rel(rpc_service, grpc_server, "External subtree validation requests", "gRPC")
 
-Rel(grpc_server, subtree_validator, "Process validation requests")
+Rel(grpc_server, subtree_handler, "Route validation requests")
 
-' CODE-VERIFIED Kafka message flow from P2P
+' Kafka message flow
 
 Rel(p2p_service, kafka, "Publish subtree notifications", "Kafka")
 
-Rel(kafka, kafka_consumer_subtrees, "Subtree notifications from P2P", "Kafka")
+Rel(kafka, kafka_consumer_subtrees, "Subtree notifications", "Kafka")
 
 Rel(kafka, kafka_consumer_txmeta, "Metadata updates", "Kafka")
 
-Rel(kafka_producer_txmeta, kafka, "Publish metadata", "Kafka")
+Rel(kafka_producer_invalid, kafka, "Publish invalid subtrees", "Kafka")
 
 ' Internal processing flow
 
-Rel(kafka_consumer_subtrees, quorum_manager, "Check/acquire locks")
-
-Rel(kafka_consumer_subtrees, subtree_validator, "Validate subtrees")
-
-Rel(subtree_validator, transaction_fetcher, "Fetch missing transactions")
-
-Rel(transaction_fetcher, http_client, "HTTP requests")
-
-Rel(subtree_validator, validator_interface, "Validate transactions")
-
-Rel(subtree_validator, metadata_processor, "Process metadata")
-
-' Metadata handling
-
-Rel(kafka_consumer_txmeta, metadata_processor, "Update metadata")
-
-Rel(metadata_processor, kafka_producer_txmeta, "Publish updates")
-
-' External service interactions
-
-Rel(http_client, asset_servers, "Fetch transactions", "HTTP")
-
-Rel(validator_interface, validator, "Transaction validation", "Interface/gRPC")
+Rel(kafka_consumer_subtrees, subtree_handler, "Process subtrees")
 
-Rel(subtree_validator, subtree_store, "Store validated subtrees", "gRPC")
+Rel(kafka_consumer_txmeta, txmeta_handler, "Process metadata")
 
-Rel(metadata_processor, utxo_store, "Cache metadata", "gRPC")
+Rel(subtree_handler, validator_client, "Validate transactions")
 
-Rel(quorum_manager, subtree_store, "Check existence", "gRPC")
+Rel(subtree_handler, blockchain_client, "Get block information")
 
-' State and health monitoring
+Rel(subtree_handler, blob_stores, "Read/write subtrees and transactions")
 
-Rel(blockchain, kafka_consumer_subtrees, "Block notifications", "Subscription")
+Rel(subtree_handler, asset_servers, "Fetch missing transactions", "HTTP")
 
-Rel(health_monitor, blockchain, "Health checks")
+Rel(subtree_handler, kafka_producer_invalid, "Report invalid subtrees")
 
-Rel(health_monitor, validator, "Health checks")
+Rel(txmeta_handler, utxo_store_client, "Cache metadata")
 
-Rel(health_monitor, subtree_store, "Health checks")
+' External service connections
 
-Rel(health_monitor, utxo_store, "Health checks")
+Rel(validator_client, validator, "Transaction validation", "gRPC/Interface")
 
-' Metrics collection
+Rel(blockchain_client, blockchain, "Blockchain queries", "gRPC")
 
-Rel(subtree_validator, metrics_collector, "Validation metrics")
+Rel(blob_stores, subtree_store, "Subtree operations", "Direct")
 
-Rel(transaction_fetcher, metrics_collector, "Fetch metrics")
+Rel(blob_stores, tx_store, "Transaction operations", "Direct")
 
-Rel(metadata_processor, metrics_collector, "Metadata metrics")
+Rel(utxo_store_client, utxo_store, "Metadata operations", "Direct")
 
 SHOW_LEGEND()
 

docs/topics/services/img/plantuml/subtreevalidation/Subtree_Validation_Component.svg

@@ -61,9 +61,6 @@ activate PodB
 PodB -> PodB: Check isPauseActive()
 activate PodB
 
-PodB -> PodB: Check local atomic flag (fast path)
-note right: Local flag = false
-
 PodB -> Storage: IsPauseActive() (distributed check)
 activate Storage
 Storage -> PauseLock: Check if lock exists and is fresh