From 3e915cf9041bb8341003b304de3ce7e387e9a18d Mon Sep 17 00:00:00 2001
From: Tyr Chen <tyr.chen@gmail.com>
Date: Sat, 31 May 2025 15:54:39 -0700
Subject: [PATCH] feature: add more rules for config and observability. Bump
 version to 0.1.2.

---
 .cursor/rules/rust/complex/workspace.mdc      | 224 ++---
 .cursor/rules/rust/core/dependencies.mdc      |  23 +
 .cursor/rules/rust/features/configuration.mdc | 557 +++++++++++++
 .cursor/rules/rust/features/observability.mdc | 772 ++++++++++++++++++
 .cursor/rules/rust/main.mdc                   |  42 +-
 LICENSE.md                                    |   7 +
 README.md                                     | 157 +++-
 specs/instructions.md                         |   4 +
 specs/rust-rules-improvement-plan.md          | 221 +++++
 9 files changed, 1891 insertions(+), 116 deletions(-)
 create mode 100644 .cursor/rules/rust/features/configuration.mdc
 create mode 100644 .cursor/rules/rust/features/observability.mdc
 create mode 100644 LICENSE.md
 create mode 100644 specs/rust-rules-improvement-plan.md

diff --git a/.cursor/rules/rust/complex/workspace.mdc b/.cursor/rules/rust/complex/workspace.mdc
index 7fc4a55..d30af31 100644
--- a/.cursor/rules/rust/complex/workspace.mdc
+++ b/.cursor/rules/rust/complex/workspace.mdc
@@ -40,66 +40,111 @@ graph TD
     style LayeredArch fill:#d94dbb,stroke:#a3378a,color:white
 ```
 
-## 🏗️ SUBSYSTEM-BASED WORKSPACE ARCHITECTURE
+## 🏗️ SERVICE-ORIENTED WORKSPACE ARCHITECTURE
 
 ```mermaid
 graph TD
-    Workspace["E-Commerce Platform Workspace"] --> Shared["Shared Infrastructure"]
-    Workspace --> UserMgmt["User Management<br/>Subsystem"]
-    Workspace --> ProductCatalog["Product Catalog<br/>Subsystem"]
-    Workspace --> OrderMgmt["Order Management<br/>Subsystem"]
-    Workspace --> Payment["Payment<br/>Subsystem"]
-    Workspace --> Notification["Notification<br/>Subsystem"]
-    Workspace --> Analytics["Analytics<br/>Subsystem"]
-    Workspace --> Gateway["API Gateway<br/>& Services"]
+    Workspace["Service Platform Workspace"] --> Shared["Shared Infrastructure"]
+    Workspace --> CoreServices["Core Services"]
+    Workspace --> BusinessServices["Business Services"]
+    Workspace --> PlatformServices["Platform Services"]
 
     Shared --> SharedTypes["shared-types<br/>(domain primitives)"]
-    Shared --> SharedDb["shared-db<br/>(database infrastructure)"]
     Shared --> SharedConfig["shared-config<br/>(configuration)"]
-    Shared --> SharedEvents["shared-events<br/>(event definitions)"]
+    Shared --> SharedObservability["shared-observability<br/>(metrics & tracing)"]
 
-    UserMgmt --> UserCore["user-core<br/>(business logic)"]
-    UserMgmt --> UserApi["user-api<br/>(HTTP handlers)"]
-    UserMgmt --> UserWorker["user-worker<br/>(background jobs)"]
+    CoreServices --> ServiceCore["service-core<br/>(business logic)"]
+    CoreServices --> ServiceApi["service-api<br/>(HTTP handlers)"]
+    CoreServices --> ServiceWorker["service-worker<br/>(background jobs)"]
 
-    ProductCatalog --> ProductCore["product-core<br/>(business logic)"]
-    ProductCatalog --> ProductApi["product-api<br/>(HTTP handlers)"]
-    ProductCatalog --> ProductSearch["product-search<br/>(search service)"]
+    BusinessServices --> BusinessCore["business-core<br/>(domain logic)"]
+    BusinessServices --> BusinessApi["business-api<br/>(API endpoints)"]
+    BusinessServices --> BusinessProcessor["business-processor<br/>(workflow engine)"]
 
-    OrderMgmt --> OrderCore["order-core<br/>(business logic)"]
-    OrderMgmt --> OrderApi["order-api<br/>(HTTP handlers)"]
-    OrderMgmt --> OrderProcessor["order-processor<br/>(workflow engine)"]
-
-    Payment --> PaymentCore["payment-core<br/>(business logic)"]
-    Payment --> PaymentApi["payment-api<br/>(HTTP handlers)"]
-    Payment --> PaymentGateway["payment-gateway<br/>(external integrations)"]
-
-    Notification --> NotificationCore["notification-core<br/>(business logic)"]
-    Notification --> NotificationService["notification-service<br/>(delivery engine)"]
-
-    Analytics --> AnalyticsCore["analytics-core<br/>(business logic)"]
-    Analytics --> AnalyticsCollector["analytics-collector<br/>(data collection)"]
-    Analytics --> AnalyticsReporter["analytics-reporter<br/>(reporting service)"]
-
-    Gateway --> ApiGateway["api-gateway<br/>(unified API)"]
-    Gateway --> AdminCli["admin-cli<br/>(administration tool)"]
-    Gateway --> MigrationTool["migration-tool<br/>(database migrations)"]
+    PlatformServices --> Gateway["gateway<br/>(API gateway)"]
+    PlatformServices --> AdminPanel["admin-panel<br/>(administration)"]
+    PlatformServices --> HealthMonitor["health-monitor<br/>(monitoring)"]
 
     style Workspace fill:#4da6ff,stroke:#0066cc,color:white
     style Shared fill:#4dbb5f,stroke:#36873f,color:white
-    style UserMgmt fill:#ffa64d,stroke:#cc7a30,color:white
-    style ProductCatalog fill:#d94dbb,stroke:#a3378a,color:white
-    style OrderMgmt fill:#4dbbbb,stroke:#368787,color:white
-    style Payment fill:#ff6b6b,stroke:#cc5555,color:white
-    style Notification fill:#9b59b6,stroke:#7d4796,color:white
-    style Analytics fill:#f39c12,stroke:#d68910,color:white
-    style Gateway fill:#2ecc71,stroke:#27ae60,color:white
+    style CoreServices fill:#ffa64d,stroke:#cc7a30,color:white
+    style BusinessServices fill:#d94dbb,stroke:#a3378a,color:white
+    style PlatformServices fill:#9b59b6,stroke:#7d4796,color:white
 ```
 
-## 📁 SUBSYSTEM-BASED DIRECTORY STRUCTURE
+## 🔄 SERVICE CONFIGURATION MANAGEMENT
+
+### Hot-Reloadable Service Architecture
+```rust
+use arc_swap::ArcSwap;
+use std::sync::Arc;
+use tokio::sync::broadcast;
+
+// ✅ Service-oriented architecture with shared state
+pub struct ServiceManager<T> {
+    config: Arc<ArcSwap<T>>,
+    components: Vec<Arc<dyn ServiceComponent>>,
+    config_tx: broadcast::Sender<Arc<T>>,
+}
+
+impl<T> ServiceManager<T>
+where
+    T: Clone + Send + Sync + 'static,
+{
+    pub fn new(initial_config: T) -> Self {
+        let (config_tx, _) = broadcast::channel(16);
+
+        Self {
+            config: Arc::new(ArcSwap::from_pointee(initial_config)),
+            components: Vec::new(),
+            config_tx,
+        }
+    }
+
+    pub fn add_component(&mut self, component: Arc<dyn ServiceComponent>) {
+        self.components.push(component);
+    }
+
+    pub fn update_config(&self, new_config: T) {
+        let new_config = Arc::new(new_config);
+        self.config.store(new_config.clone());
+
+        // Notify all components of config change
+        for component in &self.components {
+            component.on_config_update();
+        }
+
+        // Broadcast to subscribers
+        let _ = self.config_tx.send(new_config);
+    }
+
+    pub fn get_config(&self) -> Arc<T> {
+        self.config.load_full()
+    }
+
+    pub fn subscribe_to_config_changes(&self) -> broadcast::Receiver<Arc<T>> {
+        self.config_tx.subscribe()
+    }
+}
+
+pub trait ServiceComponent: Send + Sync {
+    fn on_config_update(&self);
+    fn service_name(&self) -> &str;
+    fn health_check(&self) -> ServiceHealth;
+}
+
+#[derive(Debug, Clone)]
+pub enum ServiceHealth {
+    Healthy,
+    Degraded { reason: String },
+    Unhealthy { reason: String },
+}
+```
+
+## 📁 SERVICE-ORIENTED DIRECTORY STRUCTURE
 
 ```
-ecommerce-platform/
+service-platform/
 ├── Cargo.toml                 # Workspace configuration
 ├── Cargo.lock                 # Locked dependencies
 ├── README.md                   # Platform overview
@@ -111,98 +156,81 @@ ecommerce-platform/
 │   │   ├── Cargo.toml
 │   │   └── src/
 │   │       ├── lib.rs
-│   │       ├── ids.rs         # UserId, ProductId, OrderId etc.
-│   │       ├── money.rs       # Money, Currency types
-│   │       ├── address.rs     # Address, Location types
-│   │       ├── time.rs        # Timestamp, DateRange types
-│   │       └── pagination.rs  # Pagination, Sorting types
-│   │
-│   ├── shared-db/             # Database infrastructure
-│   │   ├── Cargo.toml
-│   │   └── src/
-│   │       ├── lib.rs
-│   │       ├── connection.rs  # Connection pooling
-│   │       ├── transactions.rs # Transaction management
-│   │       ├── migrations.rs  # Migration framework
-│   │       └── repositories/  # Base repository traits
+│   │       ├── ids.rs         # EntityId, RequestId types
+│   │       ├── time.rs        # Timestamp, Duration types
+│   │       ├── pagination.rs  # Pagination, Sorting types
+│   │       └── validation.rs  # Common validation rules
 │   │
 │   ├── shared-config/         # Configuration management
 │   │   ├── Cargo.toml
 │   │   └── src/
 │   │       ├── lib.rs
+│   │       ├── service.rs     # Service configuration
 │   │       ├── database.rs    # Database configuration
-│   │       ├── redis.rs       # Redis configuration
-│   │       ├── auth.rs        # Auth configuration
-│   │       └── services.rs    # Service discovery
+│   │       ├── observability.rs # Metrics & tracing config
+│   │       └── environment.rs # Environment-specific settings
 │   │
-│   └── shared-events/         # Event definitions & messaging
+│   └── shared-observability/  # Metrics & tracing infrastructure
 │       ├── Cargo.toml
 │       └── src/
 │           ├── lib.rs
-│           ├── user_events.rs    # UserRegistered, UserUpdated
-│           ├── order_events.rs   # OrderPlaced, OrderFulfilled
-│           ├── payment_events.rs # PaymentProcessed, PaymentFailed
-│           └── event_bus.rs      # Event publishing infrastructure
+│           ├── metrics.rs     # Metrics collection patterns
+│           ├── tracing.rs     # Distributed tracing setup
+│           ├── health.rs      # Health check framework
+│           └── middleware.rs  # Observability middleware
 │
-├── subsystems/                # Business subsystems
-│   ├── user-management/       # User & Authentication subsystem
-│   │   ├── user-core/         # Business logic
+├── services/                  # Business services
+│   ├── core-services/         # Core business logic services
+│   │   ├── service-core/      # Core business logic
 │   │   │   ├── Cargo.toml
 │   │   │   └── src/
 │   │   │       ├── lib.rs
-│   │   │       ├── entities/    # User, Profile, Session
-│   │   │       ├── services/    # AuthService, ProfileService
-│   │   │       ├── repositories/ # UserRepository trait
+│   │   │       ├── entities/    # Core domain entities
+│   │   │       ├── services/    # Business service implementations
+│   │   │       ├── repositories/ # Repository trait definitions
 │   │   │       └── errors.rs
 │   │   │
-│   │   ├── user-api/          # HTTP API handlers
+│   │   ├── service-api/       # HTTP API handlers
 │   │   │   ├── Cargo.toml
 │   │   │   └── src/
 │   │   │       ├── lib.rs
-│   │   │       ├── handlers/    # Auth, profile endpoints
-│   │   │       ├── middleware/  # Auth middleware
+│   │   │       ├── handlers/    # HTTP endpoint handlers
+│   │   │       ├── middleware/  # API middleware
 │   │   │       ├── dto/        # Request/response DTOs
 │   │   │       └── validation.rs
 │   │   │
-│   │   └── user-worker/       # Background jobs
+│   │   └── service-worker/    # Background processing
 │   │       ├── Cargo.toml
 │   │       └── src/
 │   │           ├── main.rs
-│   │           ├── jobs/       # Email verification, cleanup
-│   │           └── handlers.rs
+│   │           ├── jobs/       # Background job definitions
+│   │           └── processors.rs
 │   │
-│   ├── product-catalog/       # Product management subsystem
-│   │   ├── product-core/      # Business logic
+│   ├── business-services/     # Business-specific services
+│   │   ├── business-core/     # Business domain logic
 │   │   │   ├── Cargo.toml
 │   │   │   └── src/
 │   │   │       ├── lib.rs
-│   │   │       ├── entities/    # Product, Category, Inventory
-│   │   │       ├── services/    # ProductService, InventoryService
-│   │   │       ├── repositories/
+│   │   │       ├── entities/    # Business domain entities
+│   │   │       ├── services/    # Business logic services
+│   │   │       ├── workflows/   # Business process workflows
 │   │   │       └── errors.rs
 │   │   │
-│   │   ├── product-api/       # HTTP API handlers
+│   │   ├── business-api/      # Business API endpoints
 │   │   │   ├── Cargo.toml
 │   │   │   └── src/
 │   │   │       ├── lib.rs
-│   │   │       ├── handlers/    # Product CRUD, search
-│   │   │       ├── dto/
-│   │   │       └── filters.rs
+│   │   │       ├── handlers/    # Business endpoint handlers
+│   │   │       ├── dto/        # Business DTOs
+│   │   │       └── validators.rs
 │   │   │
-│   │   └── product-search/    # Search engine service
+│   │   └── business-processor/ # Business workflow engine
 │   │       ├── Cargo.toml
 │   │       └── src/
 │   │           ├── lib.rs
-│   │           ├── indexing/    # ElasticSearch integration
-│   │           ├── queries/     # Search query builders
-│   │           └── ranking.rs   # Relevance scoring
-│   │
-│   ├── order-management/      # Order processing subsystem
-│   │   ├── order-core/        # Business logic
-│   │   │   ├── Cargo.toml
-│   │   │   └── src/
-│   │   │       ├── lib.rs
-│   │   │       ├── entities/    # Order, OrderItem, Cart
+│   │           ├── workflows/   # Workflow definitions
+│   │           ├── steps/       # Workflow step implementations
+│   │           └── executor.rs  # Workflow execution engine
 │   │   │       ├── services/    # OrderService, CartService
 │   │   │       ├── state_machine/ # Order state transitions
 │   │   │       ├── repositories/
diff --git a/.cursor/rules/rust/core/dependencies.mdc b/.cursor/rules/rust/core/dependencies.mdc
index f723648..44c78e3 100644
--- a/.cursor/rules/rust/core/dependencies.mdc
+++ b/.cursor/rules/rust/core/dependencies.mdc
@@ -143,6 +143,28 @@ colored = "2.0"                             # Terminal colors
 console = "0.15"                            # Terminal utilities
 ```
 
+### Configuration Management
+```toml
+figment = { version = "0.10", features = ["yaml", "toml", "env"] }
+notify = "6.0"                              # File watching
+arc-swap = "1.0"                            # Atomic configuration updates
+validator = { version = "0.18", features = ["derive"] }
+```
+
+### Observability
+```toml
+prometheus = "0.13"                         # Metrics collection
+opentelemetry = "0.23"                      # Distributed tracing
+tracing-opentelemetry = "0.23"              # Tracing integration
+dashmap = "6.0"                             # Lock-free concurrent maps
+```
+
+### Frontend Integration
+```toml
+rust-embed = "8.0"                          # Static asset embedding
+mime_guess = "2.0"                          # MIME type detection
+```
+
 ### gRPC/Protobuf
 ```toml
 tonic = { version = "0.13", features = ["transport", "codegen", "prost"] }
@@ -163,6 +185,7 @@ assert_cmd = "2.0"                          # CLI testing
 predicates = "3.0"                          # Test assertions
 axum-test = "15.0"                          # Axum testing
 tokio-test = "0.4"                          # Tokio testing utilities
+temp-env = "0.3"                            # Environment variable testing
 ```
 
 ## 🔧 FEATURE FLAG STRATEGY
diff --git a/.cursor/rules/rust/features/configuration.mdc b/.cursor/rules/rust/features/configuration.mdc
new file mode 100644
index 0000000..1154a58
--- /dev/null
+++ b/.cursor/rules/rust/features/configuration.mdc
@@ -0,0 +1,557 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# ⚙️ RUST CONFIGURATION MANAGEMENT
+
+> **TL;DR:** Comprehensive patterns for configuration management in Rust applications, including multi-format parsing, validation, hot-reloading, and environment-based overrides.
+
+## 🔍 CONFIGURATION STRATEGY
+
+```mermaid
+graph TD
+    Start["Configuration Needs"] --> Format{"Configuration<br>Format?"}
+
+    Format -->|Single| SingleFormat["Single Format Parsing"]
+    Format -->|Multiple| MultiFormat["Multi-Format Support"]
+
+    SingleFormat --> Validation["Configuration Validation"]
+    MultiFormat --> Validation
+
+    Validation --> Environment["Environment Overrides"]
+    Environment --> Runtime{"Runtime<br>Updates?"}
+
+    Runtime -->|Static| StaticConfig["Static Configuration"]
+    Runtime -->|Dynamic| HotReload["Hot Reloading"]
+
+    StaticConfig --> Testing["Configuration Testing"]
+    HotReload --> Watching["File System Watching"]
+    Watching --> AtomicUpdate["Atomic Updates"]
+    AtomicUpdate --> Testing
+
+    Testing --> Production["Production Configuration"]
+
+    style Start fill:#4da6ff,stroke:#0066cc,color:white
+    style MultiFormat fill:#4dbb5f,stroke:#36873f,color:white
+    style HotReload fill:#ffa64d,stroke:#cc7a30,color:white
+    style AtomicUpdate fill:#d94dbb,stroke:#a3378a,color:white
+```
+
+## 🎯 CONFIGURATION PRINCIPLES
+
+### Multi-Format Configuration Support
+```rust
+use figment::{Figment, providers::{Format, Yaml, Toml, Json, Env}};
+use serde::{Deserialize, Serialize};
+use validator::{Validate, ValidationError};
+
+// ✅ Configuration structure with validation
+#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
+#[serde(rename_all = "snake_case")]
+pub struct AppConfig {
+    #[validate(length(min = 1, max = 100))]
+    pub name: String,
+
+    #[validate(range(min = 1, max = 65535))]
+    pub port: u16,
+
+    #[serde(default = "default_host")]
+    #[validate(length(min = 1))]
+    pub host: String,
+
+    #[serde(default)]
+    pub features: Vec<String>,
+
+    #[validate(nested)]
+    pub database: DatabaseConfig,
+
+    #[serde(default)]
+    #[validate(nested)]
+    pub logging: LoggingConfig,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
+pub struct DatabaseConfig {
+    #[validate(url)]
+    pub url: String,
+
+    #[validate(range(min = 1, max = 1000))]
+    #[serde(default = "default_pool_size")]
+    pub pool_size: u32,
+
+    #[serde(default = "default_timeout")]
+    pub timeout_seconds: u64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
+pub struct LoggingConfig {
+    #[serde(default = "default_log_level")]
+    pub level: String,
+
+    #[serde(default)]
+    pub json_format: bool,
+}
+
+// Default value functions
+fn default_host() -> String { "0.0.0.0".to_string() }
+fn default_pool_size() -> u32 { 10 }
+fn default_timeout() -> u64 { 30 }
+fn default_log_level() -> String { "info".to_string() }
+
+impl AppConfig {
+    /// Load configuration from multiple sources with precedence:
+    /// 1. Environment variables (highest priority)
+    /// 2. config.yaml file
+    /// 3. config.toml file
+    /// 4. Default values (lowest priority)
+    pub fn load() -> Result<Self, ConfigError> {
+        let config = Figment::new()
+            .merge(Toml::file("config.toml"))
+            .merge(Yaml::file("config.yaml"))
+            .merge(Json::file("config.json"))
+            .merge(Env::prefixed("APP_"))
+            .extract()?;
+
+        // Validate the configuration
+        config.validate()
+            .map_err(ConfigError::Validation)?;
+
+        Ok(config)
+    }
+
+    /// Load from a specific file path
+    pub fn from_file<P: AsRef<std::path::Path>>(path: P) -> Result<Self, ConfigError> {
+        let path = path.as_ref();
+        let extension = path.extension()
+            .and_then(|ext| ext.to_str())
+            .ok_or_else(|| ConfigError::UnsupportedFormat("Unknown file extension".to_string()))?;
+
+        let figment = match extension.to_lowercase().as_str() {
+            "yaml" | "yml" => Figment::new().merge(Yaml::file(path)),
+            "toml" => Figment::new().merge(Toml::file(path)),
+            "json" => Figment::new().merge(Json::file(path)),
+            ext => return Err(ConfigError::UnsupportedFormat(ext.to_string())),
+        };
+
+        let config = figment
+            .merge(Env::prefixed("APP_"))
+            .extract()?;
+
+        config.validate()
+            .map_err(ConfigError::Validation)?;
+
+        Ok(config)
+    }
+}
+```
+
+## 🔄 HOT CONFIGURATION RELOADING
+
+### Atomic Configuration Updates
+```rust
+use arc_swap::ArcSwap;
+use notify::{RecommendedWatcher, RecursiveMode, Result as NotifyResult, Watcher};
+use std::sync::Arc;
+use tokio::sync::{broadcast, mpsc};
+
+// ✅ Configuration manager with hot reloading
+pub struct ConfigManager<T> {
+    current: Arc<ArcSwap<T>>,
+    reload_tx: broadcast::Sender<Arc<T>>,
+    config_path: std::path::PathBuf,
+}
+
+impl<T> ConfigManager<T>
+where
+    T: for<'de> Deserialize<'de> + Validate + Clone + Send + Sync + 'static,
+{
+    pub fn new(initial_config: T, config_path: impl Into<std::path::PathBuf>) -> Self {
+        let (reload_tx, _) = broadcast::channel(16);
+        let current = Arc::new(ArcSwap::from_pointee(initial_config));
+
+        Self {
+            current,
+            reload_tx,
+            config_path: config_path.into(),
+        }
+    }
+
+    /// Get current configuration
+    pub fn get(&self) -> Arc<T> {
+        self.current.load_full()
+    }
+
+    /// Subscribe to configuration updates
+    pub fn subscribe(&self) -> broadcast::Receiver<Arc<T>> {
+        self.reload_tx.subscribe()
+    }
+
+    /// Start watching for configuration file changes
+    pub async fn start_watching(&self) -> Result<(), ConfigError> {
+        let (tx, mut rx) = mpsc::channel(1);
+        let config_path = self.config_path.clone();
+
+        // File system watcher
+        let mut watcher = RecommendedWatcher::new(
+            move |res: NotifyResult<notify::Event>| {
+                if let Ok(event) = res {
+                    if event.kind.is_modify() {
+                        let _ = tx.try_send(());
+                    }
+                }
+            },
+            notify::Config::default(),
+        )?;
+
+        watcher.watch(&config_path, RecursiveMode::NonRecursive)?;
+
+        let current = self.current.clone();
+        let reload_tx = self.reload_tx.clone();
+        let config_path = self.config_path.clone();
+
+        // Spawn reload handler
+        tokio::spawn(async move {
+            while rx.recv().await.is_some() {
+                // Small delay to ensure file write is complete
+                tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
+
+                match Self::load_config_from_file(&config_path) {
+                    Ok(new_config) => {
+                        let new_config = Arc::new(new_config);
+                        current.store(new_config.clone());
+
+                        // Notify subscribers
+                        if let Err(e) = reload_tx.send(new_config) {
+                            tracing::warn!("Failed to notify config subscribers: {}", e);
+                        } else {
+                            tracing::info!("Configuration reloaded successfully");
+                        }
+                    }
+                    Err(e) => {
+                        tracing::error!("Failed to reload configuration: {}", e);
+                    }
+                }
+            }
+        });
+
+        // Keep watcher alive
+        std::mem::forget(watcher);
+        Ok(())
+    }
+
+    /// Manually reload configuration
+    pub async fn reload(&self) -> Result<(), ConfigError> {
+        let new_config = Self::load_config_from_file(&self.config_path)?;
+        let new_config = Arc::new(new_config);
+
+        self.current.store(new_config.clone());
+        self.reload_tx.send(new_config)
+            .map_err(|_| ConfigError::ReloadFailed)?;
+
+        Ok(())
+    }
+
+    fn load_config_from_file(path: &std::path::Path) -> Result<T, ConfigError> {
+        // Implementation depends on your config format
+        // This is a placeholder - use figment or similar
+        todo!("Implement config loading based on file type")
+    }
+}
+
+/// Service component that can react to configuration changes
+pub trait ConfigurableService: Send + Sync {
+    type Config;
+
+    fn on_config_update(&self, config: &Self::Config);
+}
+
+/// Helper for services that need configuration updates
+pub struct ServiceManager<T, S> {
+    config_manager: ConfigManager<T>,
+    services: Vec<Arc<S>>,
+}
+
+impl<T, S> ServiceManager<T, S>
+where
+    T: for<'de> Deserialize<'de> + Validate + Clone + Send + Sync + 'static,
+    S: ConfigurableService<Config = T>,
+{
+    pub fn new(config: T, config_path: impl Into<std::path::PathBuf>) -> Self {
+        Self {
+            config_manager: ConfigManager::new(config, config_path),
+            services: Vec::new(),
+        }
+    }
+
+    pub fn add_service(&mut self, service: Arc<S>) {
+        self.services.push(service);
+    }
+
+    pub async fn start(&self) -> Result<(), ConfigError> {
+        let mut config_updates = self.config_manager.subscribe();
+
+        // Start configuration watching
+        self.config_manager.start_watching().await?;
+
+        // Spawn task to handle config updates
+        let services = self.services.clone();
+        tokio::spawn(async move {
+            while let Ok(new_config) = config_updates.recv().await {
+                for service in &services {
+                    service.on_config_update(&new_config);
+                }
+            }
+        });
+
+        Ok(())
+    }
+
+    pub fn get_config(&self) -> Arc<T> {
+        self.config_manager.get()
+    }
+}
+```
+
+## 🌍 ENVIRONMENT-BASED CONFIGURATION
+
+### Environment Override Patterns
+```rust
+use std::env;
+
+// ✅ Environment-aware configuration
+impl AppConfig {
+    /// Create configuration for different environments
+    pub fn for_environment(env: Environment) -> Result<Self, ConfigError> {
+        let mut figment = Figment::new();
+
+        // Base configuration
+        figment = match env {
+            Environment::Development => figment
+                .merge(Toml::file("config/development.toml"))
+                .merge(Yaml::file("config/development.yaml")),
+            Environment::Testing => figment
+                .merge(Toml::file("config/testing.toml"))
+                .merge(Yaml::file("config/testing.yaml")),
+            Environment::Production => figment
+                .merge(Toml::file("config/production.toml"))
+                .merge(Yaml::file("config/production.yaml")),
+        };
+
+        // Always apply environment variables last
+        let config = figment
+            .merge(Env::prefixed("APP_"))
+            .extract()?;
+
+        config.validate()
+            .map_err(ConfigError::Validation)?;
+
+        Ok(config)
+    }
+
+    /// Detect environment from environment variable
+    pub fn detect_environment() -> Environment {
+        env::var("APP_ENV")
+            .or_else(|_| env::var("ENVIRONMENT"))
+            .unwrap_or_else(|_| "development".to_string())
+            .parse()
+            .unwrap_or(Environment::Development)
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+pub enum Environment {
+    Development,
+    Testing,
+    Production,
+}
+
+impl std::str::FromStr for Environment {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_lowercase().as_str() {
+            "development" | "dev" => Ok(Environment::Development),
+            "testing" | "test" => Ok(Environment::Testing),
+            "production" | "prod" => Ok(Environment::Production),
+            _ => Err(format!("Unknown environment: {}", s)),
+        }
+    }
+}
+```
+
+## 🧪 CONFIGURATION TESTING
+
+### Testing Configuration Patterns
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::NamedTempFile;
+    use std::io::Write;
+
+    #[test]
+    fn test_config_validation() {
+        // ✅ Test configuration validation
+        let config = AppConfig {
+            name: "".to_string(), // Invalid: empty name
+            port: 70000, // Invalid: port too high
+            host: "localhost".to_string(),
+            features: vec!["feature1".to_string()],
+            database: DatabaseConfig {
+                url: "invalid-url".to_string(), // Invalid: not a valid URL
+                pool_size: 10,
+                timeout_seconds: 30,
+            },
+            logging: LoggingConfig {
+                level: "info".to_string(),
+                json_format: false,
+            },
+        };
+
+        let validation_result = config.validate();
+        assert!(validation_result.is_err());
+    }
+
+    #[test]
+    fn test_yaml_config_loading() -> Result<(), Box<dyn std::error::Error>> {
+        // ✅ Test loading from YAML
+        let yaml_content = r#"
+name: "test-app"
+port: 8080
+host: "localhost"
+features:
+  - "feature1"
+  - "feature2"
+database:
+  url: "postgresql://localhost/test"
+  pool_size: 5
+  timeout_seconds: 60
+logging:
+  level: "debug"
+  json_format: true
+"#;
+
+        let mut temp_file = NamedTempFile::new()?;
+        write!(temp_file, "{}", yaml_content)?;
+
+        let config = AppConfig::from_file(temp_file.path())?;
+        assert_eq!(config.name, "test-app");
+        assert_eq!(config.port, 8080);
+        assert_eq!(config.features.len(), 2);
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_environment_override() {
+        // ✅ Test environment variable overrides
+        temp_env::with_vars([
+            ("APP_NAME", Some("env-override-app")),
+            ("APP_PORT", Some("9090")),
+        ], || {
+            // Test that environment variables override file values
+            // Implementation would use figment to merge env vars
+        });
+    }
+
+    #[tokio::test]
+    async fn test_hot_reload() -> Result<(), Box<dyn std::error::Error>> {
+        // ✅ Test hot reloading functionality
+        let initial_config = AppConfig {
+            name: "initial".to_string(),
+            port: 8080,
+            host: "localhost".to_string(),
+            features: vec![],
+            database: DatabaseConfig {
+                url: "postgresql://localhost/initial".to_string(),
+                pool_size: 10,
+                timeout_seconds: 30,
+            },
+            logging: LoggingConfig {
+                level: "info".to_string(),
+                json_format: false,
+            },
+        };
+
+        let temp_file = NamedTempFile::new()?;
+        let config_manager = ConfigManager::new(initial_config, temp_file.path());
+
+        // Test that we can get the initial config
+        let current = config_manager.get();
+        assert_eq!(current.name, "initial");
+
+        // Test subscription to updates
+        let mut updates = config_manager.subscribe();
+
+        // Simulate config file change and reload
+        // ... implementation details
+
+        Ok(())
+    }
+}
+```
+
+## 🚨 CONFIGURATION ERROR HANDLING
+
+### Comprehensive Error Types
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum ConfigError {
+    #[error("Configuration validation failed: {0}")]
+    Validation(#[from] validator::ValidationErrors),
+
+    #[error("Failed to parse configuration: {0}")]
+    Parse(#[from] figment::Error),
+
+    #[error("Unsupported configuration format: {0}")]
+    UnsupportedFormat(String),
+
+    #[error("Failed to watch configuration file: {0}")]
+    FileWatch(#[from] notify::Error),
+
+    #[error("Configuration reload failed")]
+    ReloadFailed,
+
+    #[error("Environment variable error: {0}")]
+    Environment(#[from] std::env::VarError),
+
+    #[error("I/O error: {0}")]
+    Io(#[from] std::io::Error),
+}
+
+impl ConfigError {
+    pub fn is_validation_error(&self) -> bool {
+        matches!(self, ConfigError::Validation(_))
+    }
+
+    pub fn is_file_error(&self) -> bool {
+        matches!(self, ConfigError::FileWatch(_) | ConfigError::Io(_))
+    }
+}
+
+pub type Result<T> = std::result::Result<T, ConfigError>;
+```
+
+## ✅ CONFIGURATION MANAGEMENT CHECKLIST
+
+```markdown
+### Configuration Implementation Verification
+- [ ] Support multiple configuration formats (YAML, TOML, JSON)
+- [ ] Implement comprehensive validation with validator
+- [ ] Environment variable overrides work correctly
+- [ ] Hot reloading implemented with atomic updates
+- [ ] File system watching for configuration changes
+- [ ] Environment-specific configuration files
+- [ ] Proper error handling with contextual information
+- [ ] Configuration testing with temporary files
+- [ ] Default values provided for optional fields
+- [ ] Configuration changes broadcast to subscribers
+- [ ] Graceful degradation on configuration errors
+- [ ] Documentation with examples for each format
+- [ ] Secrets handling (environment variables only)
+- [ ] Configuration validation on startup
+- [ ] Performance considerations for frequent access
+```
+
+This configuration management guide provides robust patterns for handling complex configuration requirements in modern Rust applications.
diff --git a/.cursor/rules/rust/features/observability.mdc b/.cursor/rules/rust/features/observability.mdc
new file mode 100644
index 0000000..82b9d64
--- /dev/null
+++ b/.cursor/rules/rust/features/observability.mdc
@@ -0,0 +1,772 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# 📊 RUST OBSERVABILITY PATTERNS
+
+> **TL;DR:** Comprehensive observability patterns for Rust applications, including lock-free metrics collection, distributed tracing, health checks, and monitoring integration.
+
+## 🔍 OBSERVABILITY STRATEGY
+
+```mermaid
+graph TD
+    Start["Observability Needs"] --> MetricsQ{"Metrics<br>Required?"}
+    Start --> TracingQ{"Distributed<br>Tracing?"}
+    Start --> HealthQ{"Health<br>Checks?"}
+
+    MetricsQ -->|Yes| MetricsType{"Metrics<br>Type?"}
+    MetricsType -->|Counters| Counters["Lock-free Counters"]
+    MetricsType -->|Histograms| Histograms["Response Time Tracking"]
+    MetricsType -->|Gauges| Gauges["Current State Metrics"]
+
+    TracingQ -->|Yes| TracingType{"Tracing<br>Scope?"}
+    TracingType -->|Application| AppTracing["Application Tracing"]
+    TracingType -->|Distributed| DistTracing["Distributed Tracing"]
+
+    HealthQ -->|Yes| HealthType{"Health Check<br>Type?"}
+    HealthType -->|Simple| SimpleHealth["Basic Health Checks"]
+    HealthType -->|Complex| ComplexHealth["Dependency Health Checks"]
+
+    Counters --> Collection["Metrics Collection"]
+    Histograms --> Collection
+    Gauges --> Collection
+
+    AppTracing --> TracingCollection["Trace Collection"]
+    DistTracing --> TracingCollection
+
+    SimpleHealth --> HealthCollection["Health Monitoring"]
+    ComplexHealth --> HealthCollection
+
+    Collection --> Export["Export & Integration"]
+    TracingCollection --> Export
+    HealthCollection --> Export
+
+    Export --> Production["Production Observability"]
+
+    style Start fill:#4da6ff,stroke:#0066cc,color:white
+    style Counters fill:#4dbb5f,stroke:#36873f,color:white
+    style AppTracing fill:#ffa64d,stroke:#cc7a30,color:white
+    style SimpleHealth fill:#d94dbb,stroke:#a3378a,color:white
+```
+
+## 🎯 METRICS COLLECTION PATTERNS
+
+### Lock-Free Metrics for High Performance
+```rust
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use dashmap::DashMap;
+use prometheus::{Counter, Histogram, Gauge, Registry, Opts, HistogramOpts};
+
+// ✅ Lock-free atomic counter for high-throughput scenarios
+#[derive(Debug)]
+pub struct AtomicCounter {
+    value: AtomicU64,
+}
+
+impl AtomicCounter {
+    pub fn new() -> Self {
+        Self {
+            value: AtomicU64::new(0),
+        }
+    }
+
+    pub fn increment(&self) -> u64 {
+        self.value.fetch_add(1, Ordering::Relaxed)
+    }
+
+    pub fn add(&self, value: u64) -> u64 {
+        self.value.fetch_add(value, Ordering::Relaxed)
+    }
+
+    pub fn get(&self) -> u64 {
+        self.value.load(Ordering::Relaxed)
+    }
+
+    pub fn reset(&self) -> u64 {
+        self.value.swap(0, Ordering::Relaxed)
+    }
+}
+
+impl Default for AtomicCounter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ✅ Comprehensive metrics collector
+pub struct MetricsCollector {
+    counters: DashMap<String, Arc<AtomicCounter>>,
+    prometheus_counters: DashMap<String, Counter>,
+    prometheus_histograms: DashMap<String, Histogram>,
+    prometheus_gauges: DashMap<String, Gauge>,
+    registry: Registry,
+}
+
+impl MetricsCollector {
+    pub fn new() -> Self {
+        Self {
+            counters: DashMap::new(),
+            prometheus_counters: DashMap::new(),
+            prometheus_histograms: DashMap::new(),
+            prometheus_gauges: DashMap::new(),
+            registry: Registry::new(),
+        }
+    }
+
+    /// Get or create a counter
+    pub fn counter(&self, name: &str) -> Arc<AtomicCounter> {
+        self.counters
+            .entry(name.to_string())
+            .or_insert_with(|| Arc::new(AtomicCounter::new()))
+            .clone()
+    }
+
+    /// Get or create a Prometheus counter
+    pub fn prometheus_counter(&self, name: &str, help: &str) -> Result<Counter, MetricsError> {
+        if let Some(counter) = self.prometheus_counters.get(name) {
+            return Ok(counter.clone());
+        }
+
+        let opts = Opts::new(name, help);
+        let counter = Counter::with_opts(opts)?;
+        self.registry.register(Box::new(counter.clone()))?;
+        self.prometheus_counters.insert(name.to_string(), counter.clone());
+
+        Ok(counter)
+    }
+
+    /// Get or create a Prometheus histogram
+    pub fn prometheus_histogram(&self, name: &str, help: &str, buckets: Vec<f64>) -> Result<Histogram, MetricsError> {
+        if let Some(histogram) = self.prometheus_histograms.get(name) {
+            return Ok(histogram.clone());
+        }
+
+        let opts = HistogramOpts::new(name, help).buckets(buckets);
+        let histogram = Histogram::with_opts(opts)?;
+        self.registry.register(Box::new(histogram.clone()))?;
+        self.prometheus_histograms.insert(name.to_string(), histogram.clone());
+
+        Ok(histogram)
+    }
+
+    /// Get or create a Prometheus gauge
+    pub fn prometheus_gauge(&self, name: &str, help: &str) -> Result<Gauge, MetricsError> {
+        if let Some(gauge) = self.prometheus_gauges.get(name) {
+            return Ok(gauge.clone());
+        }
+
+        let opts = Opts::new(name, help);
+        let gauge = Gauge::with_opts(opts)?;
+        self.registry.register(Box::new(gauge.clone()))?;
+        self.prometheus_gauges.insert(name.to_string(), gauge.clone());
+
+        Ok(gauge)
+    }
+
+    /// Export metrics in Prometheus format
+    pub fn export_prometheus(&self) -> Result<String, MetricsError> {
+        use prometheus::Encoder;
+        let encoder = prometheus::TextEncoder::new();
+        let metric_families = self.registry.gather();
+
+        let mut buffer = Vec::new();
+        encoder.encode(&metric_families, &mut buffer)?;
+
+        Ok(String::from_utf8(buffer)?)
+    }
+
+    /// Get all counter values as a snapshot
+    pub fn counter_snapshot(&self) -> std::collections::HashMap<String, u64> {
+        self.counters
+            .iter()
+            .map(|entry| (entry.key().clone(), entry.value().get()))
+            .collect()
+    }
+}
+
+impl Default for MetricsCollector {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+```
+
+### Application Metrics Patterns
+```rust
+use std::time::{Duration, Instant};
+
+// ✅ Request timing middleware pattern
+pub struct RequestTimer {
+    start_time: Instant,
+    metrics: Arc<MetricsCollector>,
+    operation: String,
+}
+
+impl RequestTimer {
+    pub fn start(metrics: Arc<MetricsCollector>, operation: impl Into<String>) -> Self {
+        let operation = operation.into();
+
+        // Increment request counter
+        metrics.counter(&format!("{}_requests_total", operation)).increment();
+
+        Self {
+            start_time: Instant::now(),
+            metrics,
+            operation,
+        }
+    }
+
+    pub fn finish(self) -> Duration {
+        let duration = self.start_time.elapsed();
+
+        // Record timing histogram
+        if let Ok(histogram) = self.metrics.prometheus_histogram(
+            &format!("{}_duration_seconds", self.operation),
+            &format!("Request duration for {}", self.operation),
+            vec![0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0],
+        ) {
+            histogram.observe(duration.as_secs_f64());
+        }
+
+        duration
+    }
+}
+
+// ✅ Metrics middleware for HTTP servers
+#[derive(Clone)]
+pub struct MetricsMiddleware {
+    metrics: Arc<MetricsCollector>,
+}
+
+impl MetricsMiddleware {
+    pub fn new(metrics: Arc<MetricsCollector>) -> Self {
+        Self { metrics }
+    }
+
+    pub async fn track_request<F, Fut, T>(&self, operation: &str, future: F) -> T
+    where
+        F: FnOnce() -> Fut,
+        Fut: std::future::Future<Output = T>,
+    {
+        let timer = RequestTimer::start(self.metrics.clone(), operation);
+        let result = future().await;
+        timer.finish();
+        result
+    }
+}
+
+// ✅ Business metrics collection
+pub trait BusinessMetrics {
+    fn record_user_registration(&self);
+    fn record_user_login(&self);
+    fn record_transaction(&self, amount: f64);
+    fn record_error(&self, error_type: &str);
+}
+
+impl BusinessMetrics for MetricsCollector {
+    fn record_user_registration(&self) {
+        self.counter("user_registrations_total").increment();
+    }
+
+    fn record_user_login(&self) {
+        self.counter("user_logins_total").increment();
+    }
+
+    fn record_transaction(&self, amount: f64) {
+        self.counter("transactions_total").increment();
+
+        if let Ok(histogram) = self.prometheus_histogram(
+            "transaction_amounts",
+            "Distribution of transaction amounts",
+            vec![1.0, 5.0, 10.0, 25.0, 50.0, 100.0, 250.0, 500.0, 1000.0],
+        ) {
+            histogram.observe(amount);
+        }
+    }
+
+    fn record_error(&self, error_type: &str) {
+        self.counter(&format!("errors_total_{}", error_type)).increment();
+    }
+}
+```
+
+## 🔍 DISTRIBUTED TRACING PATTERNS
+
+### OpenTelemetry Integration
+```rust
+use opentelemetry::global;
+use opentelemetry::trace::{TraceId, SpanId, TraceContextExt, Tracer};
+use opentelemetry::Context;
+use tracing::{info_span, Span};
+use tracing_opentelemetry::OpenTelemetrySpanExt;
+
+// ✅ Tracing configuration
+pub struct TracingConfig {
+    pub service_name: String,
+    pub service_version: String,
+    pub environment: String,
+    pub jaeger_endpoint: Option<String>,
+}
+
+pub fn setup_tracing(config: TracingConfig) -> Result<(), TracingError> {
+    use opentelemetry::sdk::trace;
+    use opentelemetry::sdk::Resource;
+    use opentelemetry::KeyValue;
+
+    // Create resource with service information
+    let resource = Resource::new(vec![
+        KeyValue::new("service.name", config.service_name),
+        KeyValue::new("service.version", config.service_version),
+        KeyValue::new("environment", config.environment),
+    ]);
+
+    // Initialize tracer
+    let tracer = if let Some(endpoint) = config.jaeger_endpoint {
+        opentelemetry_jaeger::new_agent_pipeline()
+            .with_endpoint(endpoint)
+            .with_service_name("my-service")
+            .install_simple()?
+    } else {
+        opentelemetry::sdk::trace::TracerProvider::builder()
+            .with_config(trace::config().with_resource(resource))
+            .build()
+            .tracer("my-service")
+    };
+
+    // Initialize tracing subscriber
+    let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);
+
+    use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
+    tracing_subscriber::registry()
+        .with(telemetry)
+        .with(tracing_subscriber::fmt::layer())
+        .with(tracing_subscriber::EnvFilter::from_default_env())
+        .init();
+
+    Ok(())
+}
+
+// ✅ Tracing helper macros and functions
+pub fn trace_async_fn<F, Fut, T>(span_name: &str, future: F) -> impl std::future::Future<Output = T>
+where
+    F: FnOnce() -> Fut,
+    Fut: std::future::Future<Output = T>,
+{
+    async move {
+        let span = info_span!("async_operation", operation = span_name);
+        let _enter = span.enter();
+        future().await
+    }
+}
+
+// ✅ Distributed tracing context propagation
+pub struct TraceContext {
+    pub trace_id: TraceId,
+    pub span_id: SpanId,
+    pub span_context: opentelemetry::trace::SpanContext,
+}
+
+impl TraceContext {
+    pub fn current() -> Option<Self> {
+        let context = Context::current();
+        let span_context = context.span().span_context();
+
+        if span_context.is_valid() {
+            Some(Self {
+                trace_id: span_context.trace_id(),
+                span_id: span_context.span_id(),
+                span_context: span_context.clone(),
+            })
+        } else {
+            None
+        }
+    }
+
+    pub fn to_headers(&self) -> std::collections::HashMap<String, String> {
+        use opentelemetry::propagation::{Injector, TextMapPropagator};
+
+        let mut headers = std::collections::HashMap::new();
+        let propagator = opentelemetry_jaeger::Propagator::new();
+        let context = Context::current_with_span(
+            opentelemetry::trace::TraceContextExt::span(&Context::current())
+        );
+
+        propagator.inject_context(&context, &mut headers);
+        headers
+    }
+
+    pub fn from_headers(headers: &std::collections::HashMap<String, String>) -> Context {
+        use opentelemetry::propagation::{Extractor, TextMapPropagator};
+
+        let propagator = opentelemetry_jaeger::Propagator::new();
+        let context = propagator.extract(headers);
+        context
+    }
+}
+
+// ✅ Custom span attributes
+pub trait SpanExtensions {
+    fn with_user_id(self, user_id: &str) -> Self;
+    fn with_request_id(self, request_id: &str) -> Self;
+    fn with_operation_result(self, success: bool) -> Self;
+}
+
+impl SpanExtensions for Span {
+    fn with_user_id(self, user_id: &str) -> Self {
+        self.record("user.id", user_id);
+        self
+    }
+
+    fn with_request_id(self, request_id: &str) -> Self {
+        self.record("request.id", request_id);
+        self
+    }
+
+    fn with_operation_result(self, success: bool) -> Self {
+        self.record("operation.success", success);
+        if !success {
+            self.record("error", true);
+        }
+        self
+    }
+}
+```
+
+## 🏥 HEALTH CHECK PATTERNS
+
+### Comprehensive Health Monitoring
+```rust
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::time::Duration;
+
+// ✅ Health check status
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub enum HealthStatus {
+    Healthy,
+    Degraded,
+    Unhealthy,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct HealthCheckResult {
+    pub status: HealthStatus,
+    pub message: String,
+    pub details: HashMap<String, serde_json::Value>,
+    pub duration: Duration,
+    pub timestamp: chrono::DateTime<chrono::Utc>,
+}
+
+impl HealthCheckResult {
+    pub fn healthy(message: impl Into<String>) -> Self {
+        Self {
+            status: HealthStatus::Healthy,
+            message: message.into(),
+            details: HashMap::new(),
+            duration: Duration::from_millis(0),
+            timestamp: chrono::Utc::now(),
+        }
+    }
+
+    pub fn degraded(message: impl Into<String>) -> Self {
+        Self {
+            status: HealthStatus::Degraded,
+            message: message.into(),
+            details: HashMap::new(),
+            duration: Duration::from_millis(0),
+            timestamp: chrono::Utc::now(),
+        }
+    }
+
+    pub fn unhealthy(message: impl Into<String>) -> Self {
+        Self {
+            status: HealthStatus::Unhealthy,
+            message: message.into(),
+            details: HashMap::new(),
+            duration: Duration::from_millis(0),
+            timestamp: chrono::Utc::now(),
+        }
+    }
+
+    pub fn with_detail(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
+        self.details.insert(key.into(), value);
+        self
+    }
+
+    pub fn with_duration(mut self, duration: Duration) -> Self {
+        self.duration = duration;
+        self
+    }
+}
+
+// ✅ Health check trait
+#[async_trait::async_trait]
+pub trait HealthCheck: Send + Sync {
+    async fn check(&self) -> HealthCheckResult;
+    fn name(&self) -> &str;
+    fn timeout(&self) -> Duration {
+        Duration::from_secs(5)
+    }
+}
+
+// ✅ Database health check implementation
+pub struct DatabaseHealthCheck {
+    pool: sqlx::PgPool,
+    name: String,
+}
+
+impl DatabaseHealthCheck {
+    pub fn new(pool: sqlx::PgPool, name: impl Into<String>) -> Self {
+        Self {
+            pool,
+            name: name.into(),
+        }
+    }
+}
+
+#[async_trait::async_trait]
+impl HealthCheck for DatabaseHealthCheck {
+    async fn check(&self) -> HealthCheckResult {
+        let start = std::time::Instant::now();
+
+        match sqlx::query("SELECT 1").fetch_one(&self.pool).await {
+            Ok(_) => {
+                let duration = start.elapsed();
+                HealthCheckResult::healthy("Database connection successful")
+                    .with_duration(duration)
+                    .with_detail("query_time_ms", (duration.as_millis() as f64).into())
+            }
+            Err(e) => {
+                let duration = start.elapsed();
+                HealthCheckResult::unhealthy(format!("Database connection failed: {}", e))
+                    .with_duration(duration)
+                    .with_detail("error", e.to_string().into())
+            }
+        }
+    }
+
+    fn name(&self) -> &str {
+        &self.name
+    }
+
+    fn timeout(&self) -> Duration {
+        Duration::from_secs(10)
+    }
+}
+
+// ✅ Health check manager
+pub struct HealthManager {
+    checks: HashMap<String, Box<dyn HealthCheck>>,
+}
+
+impl HealthManager {
+    pub fn new() -> Self {
+        Self {
+            checks: HashMap::new(),
+        }
+    }
+
+    pub fn add_check(&mut self, check: Box<dyn HealthCheck>) {
+        let name = check.name().to_string();
+        self.checks.insert(name, check);
+    }
+
+    pub async fn check_all(&self) -> HashMap<String, HealthCheckResult> {
+        let mut results = HashMap::new();
+
+        for (name, check) in &self.checks {
+            let timeout = check.timeout();
+
+            let result = match tokio::time::timeout(timeout, check.check()).await {
+                Ok(result) => result,
+                Err(_) => HealthCheckResult::unhealthy(format!("Health check timed out after {:?}", timeout))
+                    .with_detail("timeout", timeout.as_secs().into()),
+            };
+
+            results.insert(name.clone(), result);
+        }
+
+        results
+    }
+
+    pub async fn overall_status(&self) -> HealthStatus {
+        let results = self.check_all().await;
+
+        let mut has_degraded = false;
+
+        for result in results.values() {
+            match result.status {
+                HealthStatus::Unhealthy => return HealthStatus::Unhealthy,
+                HealthStatus::Degraded => has_degraded = true,
+                HealthStatus::Healthy => {}
+            }
+        }
+
+        if has_degraded {
+            HealthStatus::Degraded
+        } else {
+            HealthStatus::Healthy
+        }
+    }
+}
+
+impl Default for HealthManager {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+```
+
+## 🚨 ERROR HANDLING FOR OBSERVABILITY
+
+### Observability Error Types
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum MetricsError {
+    #[error("Prometheus error: {0}")]
+    Prometheus(#[from] prometheus::Error),
+
+    #[error("UTF-8 encoding error: {0}")]
+    Utf8(#[from] std::string::FromUtf8Error),
+
+    #[error("Metrics collection failed: {0}")]
+    Collection(String),
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum TracingError {
+    #[error("OpenTelemetry error: {0}")]
+    OpenTelemetry(#[from] opentelemetry::trace::TraceError),
+
+    #[error("Jaeger error: {0}")]
+    Jaeger(String),
+
+    #[error("Tracing setup failed: {0}")]
+    Setup(String),
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum HealthError {
+    #[error("Health check failed: {0}")]
+    CheckFailed(String),
+
+    #[error("Health check timeout: {0}")]
+    Timeout(String),
+
+    #[error("Health manager error: {0}")]
+    Manager(String),
+}
+```
+
+## 🧪 OBSERVABILITY TESTING
+
+### Testing Patterns
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::time::Duration;
+
+    #[test]
+    fn test_atomic_counter() {
+        let counter = AtomicCounter::new();
+        assert_eq!(counter.get(), 0);
+
+        counter.increment();
+        assert_eq!(counter.get(), 1);
+
+        counter.add(5);
+        assert_eq!(counter.get(), 6);
+
+        let old_value = counter.reset();
+        assert_eq!(old_value, 6);
+        assert_eq!(counter.get(), 0);
+    }
+
+    #[tokio::test]
+    async fn test_metrics_collector() {
+        let collector = MetricsCollector::new();
+
+        // Test counter creation and increment
+        let counter = collector.counter("test_requests");
+        counter.increment();
+        counter.add(5);
+
+        let snapshot = collector.counter_snapshot();
+        assert_eq!(snapshot.get("test_requests"), Some(&6));
+    }
+
+    #[tokio::test]
+    async fn test_request_timer() {
+        let metrics = Arc::new(MetricsCollector::new());
+        let timer = RequestTimer::start(metrics.clone(), "test_operation");
+
+        // Simulate some work
+        tokio::time::sleep(Duration::from_millis(10)).await;
+
+        let duration = timer.finish();
+        assert!(duration >= Duration::from_millis(10));
+
+        // Check that counter was incremented
+        let snapshot = metrics.counter_snapshot();
+        assert_eq!(snapshot.get("test_operation_requests_total"), Some(&1));
+    }
+
+    #[tokio::test]
+    async fn test_health_check() {
+        struct MockHealthCheck {
+            should_pass: bool,
+        }
+
+        #[async_trait::async_trait]
+        impl HealthCheck for MockHealthCheck {
+            async fn check(&self) -> HealthCheckResult {
+                if self.should_pass {
+                    HealthCheckResult::healthy("Mock check passed")
+                } else {
+                    HealthCheckResult::unhealthy("Mock check failed")
+                }
+            }
+
+            fn name(&self) -> &str {
+                "mock_check"
+            }
+        }
+
+        let mut manager = HealthManager::new();
+        manager.add_check(Box::new(MockHealthCheck { should_pass: true }));
+
+        let results = manager.check_all().await;
+        assert_eq!(results.len(), 1);
+        assert_eq!(results["mock_check"].status, HealthStatus::Healthy);
+
+        let overall = manager.overall_status().await;
+        assert_eq!(overall, HealthStatus::Healthy);
+    }
+}
+```
+
+## ✅ OBSERVABILITY CHECKLIST
+
+```markdown
+### Observability Implementation Verification
+- [ ] Lock-free metrics collection implemented
+- [ ] Prometheus metrics integration working
+- [ ] Request timing and duration tracking
+- [ ] Business metrics collection in place
+- [ ] Distributed tracing configured
+- [ ] Trace context propagation working
+- [ ] Custom span attributes defined
+- [ ] Health checks for all dependencies
+- [ ] Health check timeout handling
+- [ ] Overall health status aggregation
+- [ ] Metrics export endpoints exposed
+- [ ] Error metrics collection
+- [ ] Performance impact minimized
+- [ ] Testing coverage for all components
+- [ ] Documentation for metrics and traces
+```
+
+This observability guide provides comprehensive patterns for monitoring, tracing, and health checking in production Rust applications.
diff --git a/.cursor/rules/rust/main.mdc b/.cursor/rules/rust/main.mdc
index 538f497..be2cd94 100644
--- a/.cursor/rules/rust/main.mdc
+++ b/.cursor/rules/rust/main.mdc
@@ -38,6 +38,8 @@ graph TD
     Features --> GRPC{"gRPC/Protobuf<br>needed?"}
     Features --> Concurrent{"Heavy<br>concurrency?"}
     Features --> Config{"Complex config<br>or templating?"}
+    Features --> Observability{"Metrics & tracing<br>needed?"}
+    Features --> ConfigMgmt{"Dynamic config<br>management?"}
 
     Web -->|Yes| WebRules["Load Axum Rules"]
     DB -->|Yes| DBRules["Load Database Rules"]
@@ -45,6 +47,8 @@ graph TD
     GRPC -->|Yes| GRPCRules["Load Protobuf & gRPC Rules"]
     Concurrent -->|Yes| ConcurrencyRules["Load Concurrency Rules"]
     Config -->|Yes| ToolsRules["Load Tools & Config Rules"]
+    Observability -->|Yes| ObservabilityRules["Load Observability Rules"]
+    ConfigMgmt -->|Yes| ConfigMgmtRules["Load Configuration Rules"]
 
     style Start fill:#4da6ff,stroke:#0066cc,color:white
     style Complex fill:#d94dbb,stroke:#a3378a,color:white
@@ -100,6 +104,8 @@ graph TD
     FeatureDetection --> GRPCFeature{"gRPC/Protobuf?"}
     FeatureDetection --> SerdeFeature{"Serialization?"}
     FeatureDetection --> BuilderFeature{"Complex Types?"}
+    FeatureDetection --> ObservabilityFeature{"Metrics & Tracing?"}
+    FeatureDetection --> ConfigFeature{"Dynamic Config?"}
 
     WebFeature -->|Yes| AxumRules["Axum Framework Rules"]
     DBFeature -->|Yes| SQLxRules["SQLx Database Rules"]
@@ -107,6 +113,8 @@ graph TD
     GRPCFeature -->|Yes| GRPCRules["Protobuf & gRPC Rules"]
     SerdeFeature -->|Yes| SerdeRules["Serde Best Practices"]
     BuilderFeature -->|Yes| TypedBuilderRules["TypedBuilder Rules"]
+    ObservabilityFeature -->|Yes| ObservabilityRules["Observability Rules"]
+    ConfigFeature -->|Yes| ConfigurationRules["Configuration Rules"]
 
     style Main fill:#4da6ff,stroke:#0066cc,color:white
     style Core fill:#ffa64d,stroke:#cc7a30,color:white
@@ -183,6 +191,22 @@ sequenceDiagram
 - [ ] Background task processing
 - [ ] → Load Concurrency rules if YES to any
 
+### Configuration Management Requirements
+- [ ] Dynamic configuration reloading needed
+- [ ] Multi-format config support (YAML/TOML/JSON)
+- [ ] Configuration validation required
+- [ ] Environment-based configuration overrides
+- [ ] File system watching for config changes
+- [ ] → Load Configuration rules if YES to any
+
+### Observability Requirements
+- [ ] Metrics collection needed
+- [ ] Performance monitoring required
+- [ ] Distributed tracing needed
+- [ ] Health checks for dependencies
+- [ ] Prometheus integration required
+- [ ] → Load Observability rules if YES to any
+
 ### Tools & Configuration Requirements
 - [ ] Complex configuration files
 - [ ] Template rendering needed
@@ -253,6 +277,8 @@ Based on project analysis, load specific rule sets:
 # Database: core + sqlx + utilities (error handling)
 # CLI: core + cli + utilities (enum_dispatch + error handling)
 # gRPC: core + protobuf-grpc + utilities (typed_builder + sanitization)
+# Config Management: core + configuration + observability (metrics)
+# Service Applications: core + configuration + observability + utilities
 # Auth: core + utilities (JWT + validation)
 ```
 
@@ -274,6 +300,8 @@ Based on project analysis, load specific rule sets:
 | **CLI** | `features/cli.mdc` | Clap 4.0+ patterns, subcommands, enum_dispatch |
 | **Protobuf & gRPC** | `features/protobuf-grpc.mdc` | Prost/Tonic 0.13+, Inner types, MessageSanitizer, reflection |
 | **Concurrency** | `features/concurrency.mdc` | Tokio, DashMap, async patterns |
+| **Configuration** | `features/configuration.mdc` | Multi-format config, hot-reloading, validation patterns |
+| **Observability** | `features/observability.mdc` | Metrics collection, distributed tracing, health checks |
 | **Tools & Config** | `features/tools-and-config.mdc` | Tracing, YAML config, MiniJinja templates |
 | **Utilities** | `features/utilities.mdc` | JWT auth, CLI tools, builders, enhanced derives |
 | **HTTP Client** | `features/http-client.mdc` | reqwest patterns, error handling, retry logic |
@@ -295,6 +323,8 @@ Based on project analysis, load specific rule sets:
 - **Enterprise applications** (multiple domains)
 - **Database systems** with multiple engines
 - **Distributed systems** with event processing
+- **Production services** (requiring metrics, health checks, config reloading)
+- **High-availability applications** (with observability and dynamic configuration)
 
 ## 🚀 MODERN RUST STACK PREFERENCES
 
@@ -323,7 +353,17 @@ Based on real-world experience, these are the recommended tools:
 - **Templates**: `minijinja` (never `handlebars`)
 - **Data Extraction**: `jsonpath-rust`
 
-### Observability
+### Configuration Management
+- **Multi-format Config**: `figment` with YAML/TOML/JSON support
+- **Configuration Validation**: `validator` for compile-time guarantees
+- **Hot Reloading**: `arc-swap` + `notify` for atomic updates
+- **Environment Overrides**: Always use environment variable precedence
+
+### Observability & Monitoring
+- **Metrics Collection**: `prometheus` + lock-free atomic counters
+- **Distributed Tracing**: `opentelemetry` + `tracing-opentelemetry`
+- **Health Checks**: Custom health check frameworks with timeout handling
+- **Concurrent Metrics**: `dashmap` for lock-free metrics storage
 - **Logging**: `tracing` + `tracing-subscriber` (never `env_logger`)
 - **Structured Logging**: Always use `#[instrument]` and context
 - **Log Rotation**: `tracing-appender` for production
diff --git a/LICENSE.md b/LICENSE.md
new file mode 100644
index 0000000..fe03378
--- /dev/null
+++ b/LICENSE.md
@@ -0,0 +1,7 @@
+Copyright <2025> <Tyr Chen>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
index 5521a61..35fdf7a 100644
--- a/README.md
+++ b/README.md
@@ -6,12 +6,14 @@ A comprehensive collection of Rust development rules designed for use with Curso
 
 ## ✨ Features
 
-- 🏗️ **Modern Architecture Patterns** - Domain-driven design, subsystem organization, and clean architecture
+- 🏗️ **Modern Architecture Patterns** - Domain-driven design, service-oriented architecture, and clean architecture
 - 🌐 **Web Development Standards** - Axum web framework, OpenAPI integration, authentication patterns
 - 🗄️ **Database Best Practices** - SQLx patterns, migrations, connection pooling, and repository patterns
 - ⚡ **Async & Concurrency** - Tokio patterns, async/await best practices, and concurrent data structures
+- ⚙️ **Configuration Management** - Multi-format config support, hot-reloading, validation, and environment overrides
+- 📊 **Observability & Monitoring** - Metrics collection, distributed tracing, health checks, and performance monitoring
 - 🛠️ **Utility Libraries** - JWT authentication, CLI development, HTTP clients, and more
-- 📦 **Workspace Organization** - Multi-crate workspace structure with clear subsystem boundaries
+- 📦 **Workspace Organization** - Multi-crate workspace structure with clear service boundaries
 - 🔍 **Code Quality** - Comprehensive linting, error handling, testing, and documentation standards
 
 ## 🚀 Quick Start
@@ -47,6 +49,8 @@ rules:
   - "@rust/database"      # Database patterns with SQLx
   - "@rust/cli"           # CLI applications with clap
   - "@rust/concurrency"   # Async and concurrency patterns
+  - "@rust/configuration" # Configuration management patterns
+  - "@rust/observability" # Metrics, tracing, and health checks
   - "@rust/utilities"     # Utility libraries and CLI tools
   - "@rust/workspace"     # Multi-crate workspace organization
 ```
@@ -59,6 +63,14 @@ rules:
   - "@rust/core/code-quality"
   - "@rust/features/axum"
   - "@rust/features/database"
+  - "@rust/features/observability"  # For production monitoring
+
+# .cursorrules - Service with dynamic configuration
+rules:
+  - "@rust/core/code-quality"
+  - "@rust/features/configuration"
+  - "@rust/features/observability"
+  - "@rust/features/utilities"
 ```
 
 ## 📁 Project Structure
@@ -74,6 +86,8 @@ cursor-rust-rules/
 │   │   ├── database.mdc        # Database patterns
 │   │   ├── cli.mdc             # CLI application patterns
 │   │   ├── concurrency.mdc     # Async/concurrency patterns
+│   │   ├── configuration.mdc   # Configuration management patterns
+│   │   ├── observability.mdc   # Metrics, tracing, health checks
 │   │   ├── utilities.mdc       # Utility libraries
 │   │   ├── http-client.mdc     # HTTP client patterns
 │   │   └── tools-and-config.mdc # Development tools
@@ -94,6 +108,8 @@ cursor-rust-rules/
 - **Database** (`@rust/features/database`) - SQLx patterns, migrations, connection pooling
 - **CLI Applications** (`@rust/features/cli`) - Clap 4.0+, subcommands, enum_dispatch, modern CLI patterns
 - **Concurrency** (`@rust/features/concurrency`) - Tokio, async patterns, concurrent data structures
+- **Configuration** (`@rust/features/configuration`) - Multi-format config, hot-reloading, validation patterns
+- **Observability** (`@rust/features/observability`) - Metrics collection, distributed tracing, health checks
 - **Utilities** (`@rust/features/utilities`) - JWT, CLI tools, builder patterns, validation
 - **HTTP Client** (`@rust/features/http-client`) - Reqwest patterns, retry logic, authentication
 - **Tools & Config** (`@rust/features/tools-and-config`) - Development tooling and configuration
@@ -115,17 +131,30 @@ axum = { version = "0.8", features = ["macros", "multipart", "ws"] }
 utoipa = { version = "5.0", features = ["axum_extras", "chrono", "uuid"] }
 sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres"] }
 tokio = { version = "1.45", features = ["macros", "rt-multi-thread"] }
+
+# Configuration management
+figment = { version = "0.10", features = ["yaml", "toml", "env"] }
+arc-swap = "1.0"
+validator = { version = "0.18", features = ["derive"] }
+
+# Observability
+prometheus = "0.13"
+opentelemetry = "0.23"
+tracing-opentelemetry = "0.23"
+dashmap = "6.0"
 ```
 
 Your project follows patterns like:
 
 ```rust
-// AppState with hot-reloadable config
+// AppState with hot-reloadable config and observability
 #[derive(Clone)]
 pub struct AppState {
     pub config: Arc<ArcSwap<AppConfig>>,
     pub db: PgPool,
     pub http_client: reqwest::Client,
+    pub metrics: Arc<MetricsCollector>,
+    pub health_manager: Arc<HealthManager>,
 }
 
 // Route handlers with OpenAPI documentation
@@ -172,6 +201,85 @@ pub async fn setup_database(config: &DatabaseConfig) -> Result<PgPool, DatabaseE
 }
 ```
 
+### Configuration Management
+
+For dynamic configuration with hot-reloading:
+
+```rust
+// Multi-format configuration with validation
+#[derive(Debug, Clone, Deserialize, Validate)]
+pub struct AppConfig {
+    #[validate(length(min = 1, max = 100))]
+    pub name: String,
+
+    #[validate(range(min = 1, max = 65535))]
+    pub port: u16,
+
+    #[validate(nested)]
+    pub database: DatabaseConfig,
+
+    #[serde(default)]
+    #[validate(nested)]
+    pub observability: ObservabilityConfig,
+}
+
+// Hot-reloadable configuration manager
+pub struct ConfigManager<T> {
+    current: Arc<ArcSwap<T>>,
+    reload_tx: broadcast::Sender<Arc<T>>,
+}
+
+impl<T> ConfigManager<T>
+where
+    T: for<'de> Deserialize<'de> + Validate + Clone + Send + Sync + 'static,
+{
+    pub async fn start_watching(&self) -> Result<(), ConfigError> {
+        // File system watching with atomic configuration updates
+        // Supports YAML, TOML, JSON with environment variable overrides
+    }
+}
+```
+
+### Observability & Monitoring
+
+For production-ready metrics and health checks:
+
+```rust
+// Lock-free metrics collection
+pub struct MetricsCollector {
+    counters: DashMap<String, Arc<AtomicCounter>>,
+    prometheus_registry: Registry,
+}
+
+// Request timing middleware
+pub struct RequestTimer {
+    start_time: Instant,
+    metrics: Arc<MetricsCollector>,
+    operation: String,
+}
+
+// Health check framework
+#[async_trait]
+pub trait HealthCheck: Send + Sync {
+    async fn check(&self) -> HealthCheckResult;
+    fn name(&self) -> &str;
+}
+
+// Distributed tracing setup
+pub fn setup_tracing(config: TracingConfig) -> Result<(), TracingError> {
+    let tracer = opentelemetry_jaeger::new_agent_pipeline()
+        .with_service_name(&config.service_name)
+        .install_simple()?;
+
+    tracing_subscriber::registry()
+        .with(tracing_opentelemetry::layer().with_tracer(tracer))
+        .with(tracing_subscriber::fmt::layer())
+        .init();
+
+    Ok(())
+}
+```
+
 ### CLI Application Development
 
 For building powerful command-line tools:
@@ -220,22 +328,27 @@ impl CommandExecutor for DatabaseCommand {
 
 ### Multi-Crate Workspace
 
-For complex applications, organize as subsystems:
+For complex applications, organize as services:
 
 ```
-my-ecommerce-platform/
+my-service-platform/
 ├── shared/                      # Cross-cutting infrastructure
 │   ├── shared-types/           # Domain primitives
-│   ├── shared-db/              # Database infrastructure
-│   └── shared-events/          # Event definitions
-├── subsystems/                 # Business subsystems
-│   ├── user-management/        # User & auth subsystem
-│   ├── product-catalog/        # Product management
-│   ├── order-management/       # Order processing
-│   └── payment/                # Payment processing
-└── services/                   # Infrastructure services
-    ├── api-gateway/            # Unified API
-    └── admin-cli/              # Admin tools
+│   ├── shared-config/          # Configuration management
+│   └── shared-observability/   # Metrics & tracing
+├── services/                   # Business services
+│   ├── core-services/          # Core business logic
+│   │   ├── service-core/       # Domain logic
+│   │   ├── service-api/        # HTTP endpoints
+│   │   └── service-worker/     # Background processing
+│   └── business-services/      # Business-specific services
+│       ├── business-core/      # Business logic
+│       ├── business-api/       # API endpoints
+│       └── business-processor/ # Workflow engine
+└── platform/                  # Platform services
+    ├── gateway/                # API gateway
+    ├── admin-panel/            # Administration
+    └── health-monitor/         # Health monitoring
 ```
 
 ## 🎮 Interactive Features
@@ -255,6 +368,15 @@ async fn my_function() -> Result<(), Error> {
 // Using database patterns triggers SQLx suggestions
 sqlx::query!("SELECT * FROM users")
     // Cursor suggests: Add sqlx with postgres features
+
+// Using configuration patterns triggers config dependencies
+#[derive(Deserialize, Validate)]
+struct Config { /* ... */ }
+    // Cursor suggests: Add figment, validator, arc-swap
+
+// Using metrics patterns triggers observability dependencies
+let counter = metrics.counter("requests_total");
+    // Cursor suggests: Add prometheus, dashmap, opentelemetry
 ```
 
 ### Smart Code Generation
@@ -271,8 +393,9 @@ Rules include templates for common patterns:
 Rules are loaded based on project complexity:
 
 1. **Simple Projects** - Core quality standards only
-2. **Web APIs** - Core + Axum + Database rules
-3. **Complex Systems** - All rules including workspace organization
+2. **Web APIs** - Core + Axum + Database + Observability rules
+3. **Service Applications** - Core + Configuration + Observability + Utilities
+4. **Complex Systems** - All rules including workspace organization
 
 ## 🔧 Customization
 
diff --git a/specs/instructions.md b/specs/instructions.md
index c173b14..e344003 100644
--- a/specs/instructions.md
+++ b/specs/instructions.md
@@ -179,3 +179,7 @@ async pub fn say_hello(
 5. @/features 规则是合理的，且利于产生高质量且简洁的代码
 6. 这些 rules 无论对新项目还是老项目都能够产生高质量且简洁的代码
 如果你发现需要任何修改，请在 ./spec/ 下生成一个详细的修改计划
+
+请仔细阅读 @/rust  rule sets， 然根据下面列出的 prompt，找出 common best practice，在 specs 目录下生成一个你想如何更新 rust rules 的详细计划。注意，如果你要添加新的代码示例，请确保它是足够 common 的。如果根据以下内容你觉得需要新建一个 pingora 的 rules，请也在新的计划文件中详细说明。
+
+请更新 @rust-rules-improvement-plan.md 里的代码足够 common，不要包含特定的内容，而且内容需要保持正交（hot-reloading 出现一次就可以了）。之后，请按照计划更新或者生成新的 rules。不必更新 performance.mdc，不必更新 api-design.mdc，也不必添加 pingora.mdc
diff --git a/specs/rust-rules-improvement-plan.md b/specs/rust-rules-improvement-plan.md
new file mode 100644
index 0000000..1b88942
--- /dev/null
+++ b/specs/rust-rules-improvement-plan.md
@@ -0,0 +1,221 @@
+# Rust Rules Improvement Plan
+
+## Executive Summary
+
+After analyzing the existing Rust rule sets and extensive real-world usage patterns, I've identified several common patterns and gaps that warrant updates to our Rust coding standards. This plan outlines specific improvements to existing rules and proposes new rule sets for configuration management and observability.
+
+## Current Rule Analysis
+
+### Strengths of Existing Rules
+
+- **Comprehensive coverage**: Core areas (code quality, dependencies, design patterns, performance) are well-covered
+- **Practical examples**: Good balance of theoretical guidance and concrete code examples
+- **Workspace architecture**: Excellent multi-crate organization guidance
+- **Modern Rust idioms**: Rules emphasize Rust 2024 edition and best practices
+
+### Identified Gaps from Real-World Usage
+
+From analyzing common patterns in modern Rust applications, several areas need better coverage:
+
+1. **Configuration Management** - Multi-format config parsing, validation, and runtime updates
+2. **Observability Patterns** - Real-time metrics collection and distributed tracing
+3. **Service Architecture** - Async service orchestration and middleware patterns
+4. **Frontend Integration** - Embedded web assets and API integration patterns
+
+## Proposed Rule Updates
+
+### 1. Enhanced Workspace Architecture Rules
+
+**File**: `.cursor/rules/rust/complex/workspace.mdc`
+
+**Changes**:
+
+- Add **service-oriented architecture** patterns
+- Include **plugin architecture** examples for extensible systems
+- Add **configuration hot-reloading** patterns
+
+**New Example Pattern**:
+
+```rust
+// Service-oriented architecture with shared state
+pub struct ServiceManager<T> {
+    config: Arc<ArcSwap<T>>,
+    components: Vec<Arc<dyn ServiceComponent>>,
+}
+
+impl<T> ServiceManager<T> {
+    pub fn update_config(&self, new_config: T) {
+        self.config.store(Arc::new(new_config));
+        // Notify components of config change
+        for component in &self.components {
+            component.on_config_update();
+        }
+    }
+}
+
+pub trait ServiceComponent: Send + Sync {
+    fn on_config_update(&self);
+}
+```
+
+### 2. New Configuration Management Rules
+
+**New File**: `.cursor/rules/rust/features/configuration.mdc`
+
+**Purpose**: Comprehensive configuration management patterns
+
+**Key Sections**:
+
+- **Multi-format parsing** (YAML, TOML, JSON)
+- **Configuration validation** with compile-time guarantees
+- **Environment-based overrides**
+- **Configuration watching** with filesystem events
+
+**Example Pattern**:
+
+```rust
+#[derive(Debug, Clone, Deserialize, Validate)]
+pub struct AppConfig {
+    #[validate(length(min = 1))]
+    pub name: String,
+
+    #[validate(range(min = 1, max = 65535))]
+    pub port: u16,
+
+    #[serde(default)]
+    pub features: Vec<String>,
+}
+
+pub struct ConfigManager<T> {
+    current: Arc<ArcSwap<T>>,
+    reload_tx: mpsc::Sender<ConfigReload>,
+}
+```
+
+### 3. New Observability Rules
+
+**New File**: `.cursor/rules/rust/features/observability.mdc`
+
+**Purpose**: Real-time metrics collection and observability patterns
+
+**Key Patterns**:
+
+- **Lock-free counter implementation** for high-throughput scenarios
+- **Metrics collection** with proper aggregation
+- **Distributed tracing** patterns
+- **Health check implementations**
+
+**Example**:
+
+```rust
+// Lock-free metrics for high-performance scenarios
+pub struct AtomicCounter {
+    value: AtomicU64,
+}
+
+impl AtomicCounter {
+    pub fn increment(&self) -> u64 {
+        self.value.fetch_add(1, Ordering::Relaxed)
+    }
+
+    pub fn get(&self) -> u64 {
+        self.value.load(Ordering::Relaxed)
+    }
+}
+
+// Metrics collection pattern
+pub struct MetricsCollector {
+    counters: DashMap<String, AtomicCounter>,
+    histograms: DashMap<String, Histogram>,
+}
+```
+
+### 4. Updated Dependency Management Rules
+
+**File**: `.cursor/rules/rust/core/dependencies.mdc`
+
+**Additions**:
+
+- **Configuration management** dependencies
+- **Observability** dependency patterns
+- **Frontend integration** dependencies
+
+**New Section**: Common Service Dependencies
+
+```toml
+# Configuration management
+figment = { version = "0.10", features = ["yaml", "toml", "env"] }
+notify = "6.0"  # File watching
+arc-swap = "1.0"  # Atomic updates
+validator = { version = "0.18", features = ["derive"] }
+
+# Observability
+prometheus = "0.13"
+opentelemetry = "0.23"
+tracing-opentelemetry = "0.23"
+dashmap = "6.0"  # Concurrent collections
+
+# Frontend integration
+rust-embed = "8.0"  # Static asset embedding
+mime_guess = "2.0"  # MIME type detection
+```
+
+## Implementation Priority
+
+### Phase 1: Critical Updates (High Impact, Common Patterns)
+
+1. **Configuration Management Rules** - Most frequently used pattern
+2. **Observability Rules** - Essential for production systems
+3. **Enhanced Workspace Architecture** - Service-oriented patterns
+
+### Phase 2: Refinements (Medium Impact)
+
+1. **Updated Dependency Management** - New common dependencies
+2. **Documentation Updates** - Ensure all examples are current
+
+## Common Best Practices Identified
+
+From analyzing real-world usage, these patterns appear frequently and should be emphasized:
+
+### 1. Configuration Management
+
+- **Multi-format support** with validation
+- **Environment-based overrides**
+- **Atomic configuration updates** using `arc-swap`
+
+### 2. Observability
+
+- **Lock-free data structures** for metrics
+- **Structured logging** with context
+- **Health check patterns** for services
+
+### 3. Service Architecture
+
+- **Trait-based components** for extensibility
+- **Shared state management** with atomic updates
+- **Graceful shutdown** with signal handling
+
+### 4. Error Handling
+
+- **Contextual errors** with detailed information
+- **Error propagation** patterns
+- **Retry patterns** with exponential backoff
+
+### 5. Testing Strategies
+
+- **Integration testing** with real services
+- **Configuration testing** with multiple formats
+- **Metrics testing** with mock collectors
+
+## Success Metrics
+
+To measure the effectiveness of these rule updates:
+
+1. **Developer Velocity**: Faster onboarding for Rust projects
+2. **Code Quality**: Reduced bugs in configuration and observability code
+3. **Consistency**: More uniform patterns across projects
+4. **Maintainability**: Better separation of concerns and testability
+
+## Conclusion
+
+These rule updates codify common patterns that have emerged from real-world Rust development, particularly in service-oriented applications. The focus on configuration management and observability addresses critical needs in modern applications while maintaining the high standards of the existing rule set.