docs: add comprehensive codebase analysis for planning

- Document 10 key improvement areas with specific recommendations
- Include implementation priorities (short-term, medium-term, long-term)
- Identify specific file recommendations (http_client.py, blockchain.py, agent.py)
- Save analysis for future reference and planning purposes

aitbc/config.py

@@ -41,14 +41,6 @@ class BaseAITBCConfig(BaseSettings):
         default="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
         description="Log format string"
     )
-    
-    def __init__(self, **kwargs):
-        """Initialize configuration with logging"""
-        super().__init__(**kwargs)
-        logger.info(f"Loading configuration for {self.app_name} v{self.app_version} in {self.environment} environment")
-        logger.debug(f"Data directory: {self.data_dir}")
-        logger.debug(f"Config directory: {self.config_dir}")
-        logger.debug(f"Log directory: {self.log_dir}")
 
 
 class AITBCConfig(BaseAITBCConfig):
@@ -80,3 +72,9 @@ class AITBCConfig(BaseAITBCConfig):
     # Performance settings
     request_timeout: int = Field(default=30, description="Request timeout in seconds")
     max_request_size: int = Field(default=10 * 1024 * 1024, description="Max request size in bytes")
+    
+    def __init__(self, **kwargs):
+        """Initialize AITBC configuration with extended logging"""
+        super().__init__(**kwargs)
+        logger.info(f"Server configured for {self.host}:{self.port}")
+        logger.debug(f"Workers: {self.workers}, Request timeout: {self.request_timeout}s")

cli/commands/blockchain.py

@@ -1071,7 +1071,18 @@ def send(ctx, chain_id, from_addr, to, data, nonce):
 @click.option('--all-chains', is_flag=True, help='Query balance across all available chains')
 @click.pass_context
 def balance(ctx, address, chain_id, all_chains):
-    """Get the balance of an address across chains"""
+    """
+    Get the balance of an address across chains.
+    
+    Retrieves the current balance for a specific wallet address including
+    token amount and nonce. Supports querying across multiple chains.
+    
+    Args:
+        ctx: Click context object
+        address: Wallet address to query
+        chain_id: Specific chain ID to query
+        all_chains: Flag to query balance across all available chains
+    """
     config = ctx.obj['config']
     try:
         import httpx

docs/CODEBASE_ANALYSIS_2026-05-09.md

@@ -0,0 +1,178 @@
+# AITBC Codebase Analysis & Suggestions
+
+**Date:** 2026-05-09  
+**Purpose:** Comprehensive codebase analysis for documentation and planning
+
+---
+
+## Overall Structure Assessment
+
+The AITBC codebase appears to be a well-structured Python project with:
+- Clear separation of concerns (core library, CLI, apps, contracts)
+- Modern Python practices (type hints, async/await)
+- Good test coverage (mentioned in README)
+- Poetry for dependency management
+- Comprehensive documentation
+
+---
+
+## Key Areas for Improvement
+
+### 1. CLI Organization & Consistency
+
+**Observation:** The CLI has grown significantly with many command files in `/opt/aitbc/cli/commands/` (blockchain.py is 55k lines, agent.py is 26k lines).
+
+**Suggestions:**
+- Consider breaking large command files into smaller, more focused modules
+- Implement a plugin/discovery system for CLI commands to improve maintainability
+- Add command grouping/subcommand structure for better organization
+- Standardize error handling across CLI commands
+- Consider adding command aliases for frequently used operations
+
+### 2. Core Library Modularity
+
+**Observation:** The `/opt/aitbc/aitbc/` directory contains many utility modules that could benefit from better organization.
+
+**Suggestions:**
+- Group related utilities into subpackages (e.g., aitbc/utils/, aitbc/network/, aitbc/crypto/)
+- Consider implementing a proper service layer pattern for blockchain interactions
+- Add more interface definitions (abstract base classes) for better testability
+- Implement dependency injection for easier testing and configuration
+
+### 3. Testing Strategy Enhancement
+
+**Observation:** Testing is mentioned as comprehensive, but could be improved.
+
+**Suggestions:**
+- Add property-based testing for critical functions (using hypothesis)
+- Implement contract testing for blockchain interactions
+- Add chaos engineering tests for network resilience
+- Create benchmark tests for performance-critical paths
+- Consider implementing mutation testing to assess test quality
+
+### 4. Documentation & Code Examples
+
+**Observation:** Documentation is strong, but code examples could be improved.
+
+**Suggestions:**
+- Add more runnable code examples in docstrings
+- Implement doctest verification for examples
+- Create interactive tutorials/Jupyter notebooks for learning
+- Add API reference generation (using tools like Sphinx or MkDocs)
+- Include more architecture diagrams and sequence diagrams
+
+### 5. Configuration Management
+
+**Observation:** Configuration appears to be handled through environment variables and config files.
+
+**Suggestions:**
+- Implement a hierarchical configuration system (defaults → file → env → CLI args)
+- Add configuration validation with schema checking (using pydantic-settings)
+- Provide configuration templates for different environments (dev, test, prod)
+- Add secret management integration (HashiCorp Vault, AWS Secrets Manager, etc.)
+
+### 6. Error Handling & Logging
+
+**Observation:** Logging and error handling patterns exist but could be standardized.
+
+**Suggestions:**
+- Implement structured logging consistently throughout the codebase
+- Add correlation IDs for request tracing across services
+- Implement circuit breaker pattern for external dependencies
+- Add retry mechanisms with exponential backoff for transient failures
+- Create custom exception hierarchies for better error categorization
+
+### 7. Performance & Optimization
+
+**Observation:** Performance considerations are mentioned but could be systematic.
+
+**Suggestions:**
+- Add profiling hooks for performance bottleneck identification
+- Implement caching strategies for expensive operations
+- Add connection pooling for database and external service connections
+- Consider async optimization for I/O-bound operations
+- Add memory profiling for long-running processes
+
+### 8. Security Enhancements
+
+**Observation:** Security features are implemented but could be hardened.
+
+**Suggestions:**
+- Implement regular dependency vulnerability scanning
+- Add security headers and CORS policies for web services
+- Implement input validation and sanitization everywhere
+- Add rate limiting and DDoS protection
+- Consider implementing API versioning for backward compatibility
+- Add security audit logging for sensitive operations
+
+### 9. Deployment & DevOps
+
+**Observation:** Deployment processes exist but could be improved.
+
+**Suggestions:**
+- Implement infrastructure as code (Terraform/CDK) for environment provisioning
+- Add blue-green deployment capabilities
+- Implement feature flags for gradual rollouts
+- Add health check endpoints for all services
+- Implement distributed tracing (Jaeger/OpenTelemetry)
+- Add service mesh integration (Istio/Linkerd) for microservices communication
+
+### 10. Code Quality & Maintainability
+
+**Observation:** Code quality is good but could be enhanced.
+
+**Suggestions:**
+- Implement architectural decision records (ADRs)
+- Add more comprehensive type hints (aim for 100% coverage)
+- Implement automated code review checks in CI/CD
+- Add more examples of effective patterns in CONTRIBUTING.md
+- Consider implementing a design system for consistent APIs
+- Add code ownership mapping (CODEOWNERS file)
+
+---
+
+## Specific File/Module Recommendations
+
+### `/http_client.py` (732 lines - largest file)
+- Consider breaking into: HTTP client core, retry logic, authentication handlers, response processors
+- Add connection pooling and session management
+- Implement circuit breaker pattern
+
+### `/blockchain.py` (55k lines in CLI commands)
+- Definitely needs modularization
+- Consider separating: transaction handling, query operations, contract interactions, event processing
+- Add blockchain-specific utilities as separate module
+
+### `/agent.py` (26k lines in CLI commands)
+- Split into: agent lifecycle management, message handling, task execution, monitoring
+- Consider implementing agent plugins/extensions system
+
+---
+
+## Implementation Priorities
+
+### Short-term (1-2 weeks)
+- CLI command modularization
+- Improved error handling standardization
+- Enhanced testing strategies
+
+### Medium-term (1-3 months)
+- Core library reorganization
+- Configuration system improvement
+- Performance monitoring implementation
+
+### Long-term (3-6 months)
+- Advanced security hardening
+- DevOps/CD enhancements
+- Architectural evolution toward microservices (if needed)
+
+---
+
+## Conclusion
+
+The AITBC codebase shows strong foundational architecture with good practices already in place. The main opportunities for improvement involve:
+- Better modularization of large files
+- Enhanced standardization and consistency
+- Improved observability and monitoring
+- More advanced testing strategies
+- Evolving deployment and DevOps capabilities