refactor: update service layer exports and fix import paths

- Export service layer classes in aitbc/__init__.py lazy exports
- Add BlockchainService, RPCBlockchainService, BlockchainServiceFactory
- Add DatabaseService, SQLiteDatabaseService, DatabaseServiceFactory
- Remove obsolete AITBCHTTPClient export
- Fix import path in multichain_exchange_api.py (http_client -> network.http_client)
- Fix import path in agent-coordinator-wrapper.py (paths -> utils.paths)
- Update Learning Service port from 8011 to

.windsurf/skills/service-port-mapping.md

@@ -0,0 +1,305 @@
+---
+description: Comprehensive AITBC service-to-port mapping reference for all nodes and environments
+title: AITBC Service Port Mapping
+version: 1.0
+---
+
+# AITBC Service Port Mapping Skill
+
+## Purpose
+Provide comprehensive service-to-port mapping reference for AITBC blockchain platform across all nodes (localhost, aitbc1, gitea-runner) and environments.
+
+## Activation
+Trigger when user needs to know which service runs on which port, troubleshoot port conflicts, configure service endpoints, or understand service architecture.
+
+## Core AITBC Services
+
+### Blockchain Layer
+- **8006**: Blockchain RPC (aitbc_chain.app)
+  - Purpose: Main blockchain RPC endpoint for block queries, transactions, and chain operations
+  - Nodes: localhost, aitbc1, gitea-runner
+  - Service: aitbc-blockchain-rpc.service, aitbc-blockchain-node.service
+  - Wrapper: aitbc-blockchain-rpc-wrapper.py
+  - Config: RPC_BIND_PORT environment variable (default: 8006)
+
+- **7070**: P2P Mesh Network (aitbc_chain.p2p_network)
+  - Purpose: Peer-to-peer gossip protocol for block propagation and node discovery
+  - Nodes: localhost, aitbc1
+  - Service: aitbc-blockchain-p2p.service
+  - Wrapper: aitbc-blockchain-p2p-wrapper.py
+  - Config: P2P_BIND_PORT environment variable (default: 7070)
+
+- **8204**: Blockchain Event Bridge (blockchain_event_bridge.main)
+  - Purpose: Event streaming service for blockchain events to external systems
+  - Nodes: localhost, aitbc1
+  - Service: aitbc-blockchain-event-bridge.service
+  - Wrapper: aitbc-blockchain-event-bridge-wrapper.py
+  - Config: bind_port environment variable (default: 8204)
+
+### Coordinator Layer
+- **8011**: Coordinator API (app.main)
+  - Purpose: Main coordinator API for AI job submission, miner registration, marketplace operations
+  - Nodes: localhost, aitbc1
+  - Service: aitbc-coordinator-api.service
+  - Wrapper: aitbc-coordinator-api-wrapper.py
+  - Config: Hardcoded in wrapper (port 8011)
+
+- **8012**: Adaptive Learning Service (app.services.adaptive_learning_app)
+  - Purpose: AI model adaptive learning and optimization service
+  - Nodes: localhost, aitbc1
+  - Service: aitbc-learning.service
+  - Config: Hardcoded in systemd (port 8012)
+  - Note: Changed from 8011 to 8012 to avoid port conflict with coordinator API
+
+- **9001**: Agent Coordinator
+  - Purpose: Agent coordination, communication, and session management
+  - Nodes: localhost
+  - Service: aitbc-agent-coordinator.service
+  - Config: AITBC_COORDINATOR_PORT environment variable (default: 9001)
+  - Documentation: docs/agent-coordinator/ARCHITECTURE.md
+
+### Exchange & Trading
+- **8001**: Exchange API (simple_exchange_api.py)
+  - Purpose: Cross-chain exchange and trading platform
+  - Nodes: aitbc1
+  - Service: aitbc-exchange-api.service
+  - Wrapper: aitbc-exchange-api-wrapper.py
+  - Config: Hardcoded in wrapper (port 8001)
+
+### Wallet Services
+- **8003**: Wallet Daemon (simple_daemon.py)
+  - Purpose: Background wallet service for transaction signing and key management
+  - Nodes: localhost, aitbc1
+  - Service: aitbc-wallet.service
+  - Wrapper: aitbc-wallet-wrapper.py
+  - Config: Uses internal wallet RPC (no external port)
+
+### AI Services
+- **8005**: AI Service (src.ai_service.main)
+  - Purpose: AI model inference and computation service
+  - Nodes: localhost, aitbc1
+  - Service: aitbc-ai.service
+  - Config: Hardcoded in systemd (port 8005)
+
+- **8020**: Multimodal Service (src.app.services.multimodal_app)
+  - Purpose: Multimodal AI processing and integration
+  - Nodes: aitbc1
+  - Service: aitbc-multimodal.service
+  - Config: Hardcoded in systemd (port 8020)
+
+- **8021**: Modality Optimization Service (src.app.services.modality_optimization_app)
+  - Purpose: AI modality optimization and tuning
+  - Nodes: aitbc1
+  - Service: aitbc-modality-optimization.service
+  - Config: Hardcoded in systemd (port 8021)
+
+### Agent Services
+- **8014**: Hermes (aitbc-hermes-wrapper.py)
+  - Purpose: AI agent communication and coordination framework
+  - Nodes: localhost
+  - Service: aitbc-hermes.service
+  - Wrapper: aitbc-hermes-wrapper.py
+  - Config: Hardcoded in wrapper (port 8014)
+
+- **8016**: Plugin Registry (aitbc-plugin-wrapper.py)
+  - Purpose: Agent plugin management and registry service
+  - Nodes: aitbc1
+  - Service: aitbc-plugin.service
+  - Wrapper: aitbc-plugin-wrapper.py
+  - Config: Hardcoded in wrapper (port 8016)
+
+### Monitoring & Observability
+- **8002**: Monitoring Service
+  - Purpose: System monitoring, metrics collection, and health checks
+  - Nodes: aitbc1
+  - Service: aitbc-monitoring.service
+  - Wrapper: aitbc-monitoring-wrapper.py
+  - Config: Hardcoded in wrapper (port 8002)
+
+## Infrastructure Services
+
+### Database & Cache
+- **5432**: PostgreSQL
+  - Purpose: Relational database for coordinator, marketplace, and other services
+  - Nodes: localhost, aitbc1, gitea-runner
+  - Service: postgresql
+
+- **6379**: Redis
+  - Purpose: Cache, message queue, and session storage
+  - Nodes: localhost, aitbc1, gitea-runner
+  - Service: redis
+
+### Web & Proxy
+- **80**: Nginx
+  - Purpose: Reverse proxy and web server for HTTPS termination and load balancing
+  - Nodes: localhost
+  - Service: nginx
+
+- **443**: Nginx HTTPS
+  - Purpose: HTTPS endpoint for public API access
+  - Nodes: localhost
+  - Service: nginx
+
+### Communication
+- **22**: SSH
+  - Purpose: Secure shell access for remote management
+  - Nodes: localhost, aitbc1, gitea-runner
+  - Service: sshd
+
+- **25**: SMTP
+  - Purpose: Email delivery for notifications
+  - Nodes: localhost, aitbc1, gitea-runner
+  - Service: postfix
+
+### Real-time Communication
+- **3478**: TURN Server
+  - Purpose: WebRTC TURN relay for real-time communication
+  - Nodes: localhost
+  - Service: coturn
+
+### AI Infrastructure
+- **11434**: Ollama
+  - Purpose: Local LLM inference service for AI operations
+  - Nodes: localhost
+  - Service: ollama
+
+## Port Conflict Resolution
+
+### Known Conflicts & Resolutions
+- **8011 vs 8012**: Coordinator API (8011) conflicted with Adaptive Learning Service (8011)
+  - Resolution: Changed Adaptive Learning Service to port 8012 on all nodes
+  - Files modified: /etc/systemd/system/aitbc-learning.service
+
+### Port Allocation Guidelines
+- **8000-8099**: Core AITBC services (blockchain, coordinator, exchange, wallet)
+- **8100-8199**: AI and agent services (multimodal, optimization, plugins)
+- **8200-8299**: Event streaming and bridge services
+- **9000-9099**: Agent coordination and orchestration
+- **7000-7099**: P2P and networking services
+
+## Service Discovery Commands
+
+### Check Active Ports
+```bash
+# Localhost
+sudo lsof -i -P -n | grep LISTEN
+
+# Remote nodes
+ssh aitbc1 "sudo lsof -i -P -n | grep LISTEN"
+ssh gitea-runner "sudo lsof -i -P -n | grep LISTEN"
+```
+
+### Check Service Status
+```bash
+# All AITBC services
+systemctl status aitbc-*.service
+
+# Specific service
+systemctl status aitbc-coordinator-api.service
+```
+
+### Check Service Port Configuration
+```bash
+# Systemd service files
+grep -r "port" /etc/systemd/system/aitbc-*.service
+
+# Wrapper scripts
+grep -r "port" /opt/aitbc/scripts/wrappers/*.py
+```
+
+### Test Service Endpoints
+```bash
+# Coordinator API health
+curl http://localhost:8011/v1/health
+
+# Blockchain RPC head
+curl http://localhost:8006/rpc/head
+
+# Exchange API
+curl http://localhost:8001/v1/health
+
+# Agent Coordinator
+curl http://localhost:9001/v1/health
+```
+
+## Environment Variables
+
+### Port Configuration Variables
+- `RPC_BIND_PORT`: Blockchain RPC port (default: 8006)
+- `P2P_BIND_PORT`: P2P network port (default: 7070)
+- `AITBC_COORDINATOR_PORT`: Agent coordinator port (default: 9001)
+- `bind_port`: Event bridge port (default: 8204)
+
+### Node-Specific Configuration
+- `/etc/aitbc/.env`: Environment configuration
+- `/etc/aitbc/node.env`: Node-specific configuration
+- `/run/aitbc/secrets/.env`: Runtime secrets
+
+## Troubleshooting
+
+### Port Already in Use
+1. Identify process: `sudo lsof -i :<port>`
+2. Kill stale process: `sudo kill -9 <PID>`
+3. Restart service: `sudo systemctl restart <service>`
+
+### Service Not Listening
+1. Check service status: `systemctl status <service>`
+2. Check logs: `journalctl -u <service> -n 50`
+3. Verify port configuration in wrapper script
+4. Check firewall rules: `sudo iptables -L -n`
+
+### Port Conflicts
+1. Identify conflicting services using same port
+2. Update one service to use different port
+3. Update systemd service file and wrapper script
+4. Reload systemd: `sudo systemctl daemon-reload`
+5. Restart affected services
+
+## Node-Specific Service Distribution
+
+### Localhost (aitbc - Genesis Node)
+- Core: 8006, 7070, 8204, 8011, 8012
+- AI: 8005, 8014, 9001
+- Wallet: 8003
+- Infrastructure: 80, 443, 5432, 6379, 11434
+
+### aitbc1 (Follower Node)
+- Core: 8006, 7070, 8204, 8011, 8012
+- Exchange: 8001
+- AI: 8005, 8020, 8021, 8016
+- Monitoring: 8002
+- Wallet: 8003
+- Infrastructure: 5432, 6379
+
+### gitea-runner (CI/CD Node)
+- Infrastructure only: 5432, 6379, 22, 25
+- No AITBC services running (CI execution environment)
+
+## Best Practices
+
+### Port Configuration
+1. Use environment variables for port configuration where possible
+2. Document port changes in service files
+3. Update wrapper scripts when changing ports
+4. Test port availability before service deployment
+5. Use standard port ranges for service categories
+
+### Service Management
+1. Always reload systemd after service file changes
+2. Check service logs after port changes
+3. Verify service health after restart
+4. Monitor port conflicts during deployment
+5. Document custom port configurations
+
+### Security Considerations
+1. Bind sensitive services to localhost when possible
+2. Use firewall rules to restrict port access
+3. Avoid exposing internal services to public internet
+4. Use reverse proxy for public-facing services
+5. Monitor port usage for unauthorized access
+
+## Related Documentation
+- [Multi-Node Operations](/opt/aitbc/docs/skills/aitbc-multi-node-operations.md)
+- [Basic Operations](/opt/aitbc/docs/skills/aitbc-basic-operations.md)
+- [Agent Coordinator](/opt/aitbc/docs/agent-coordinator/ARCHITECTURE.md)
+- [Blockchain Troubleshooting](/opt/aitbc/docs/skills/aitbc-blockchain-troubleshooting.md)

aitbc/__init__.py

@@ -76,7 +76,12 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
     "get_nested_value": ("json_utils", "get_nested_value"),
     "set_nested_value": ("json_utils", "set_nested_value"),
     "flatten_json": ("json_utils", "flatten_json"),
-    "AITBCHTTPClient": ("http_client", "AITBCHTTPClient"),
+    "BlockchainService": ("blockchain_service", "BlockchainService"),
+    "RPCBlockchainService": ("blockchain_service", "RPCBlockchainService"),
+    "BlockchainServiceFactory": ("blockchain_service", "BlockchainServiceFactory"),
+    "DatabaseService": ("database_service", "DatabaseService"),
+    "SQLiteDatabaseService": ("database_service", "SQLiteDatabaseService"),
+    "DatabaseServiceFactory": ("database_service", "DatabaseServiceFactory"),
     "AsyncAITBCHTTPClient": ("http_client", "AsyncAITBCHTTPClient"),
     "BaseAITBCConfig": ("config", "BaseAITBCConfig"),
     "AITBCConfig": ("config", "AITBCConfig"),

apps/exchange/multichain_exchange_api.py

@@ -14,7 +14,7 @@ from pydantic import BaseModel, Field
 import uvicorn
 import os
 
-from aitbc.http_client import AsyncAITBCHTTPClient
+from aitbc.network.http_client import AsyncAITBCHTTPClient
 from aitbc.aitbc_logging import get_logger
 from aitbc.exceptions import NetworkError
 

docs/archive/completed/implementation/enhanced-services-implementation-complete.md

@@ -1,5 +1,10 @@
 # AITBC Enhanced Services (8000-8023) Implementation Complete - March 30, 2026
 
+> **NOTE**: This document describes the implementation as of March 30, 2026. Port allocations have since changed:
+> - Learning Service moved from port 8011 to 8012 (to avoid conflict with Coordinator API)
+> - Agent Coordinator moved from port 8012 to 9001
+> - Current port mappings are documented in `/opt/aitbc/.windsurf/skills/service-port-mapping.md`
+
 ## 🎯 Implementation Summary
 
 **✅ Status**: Enhanced Services successfully implemented and running

docs/reference/PORT_MAPPING_GUIDE.md

@@ -120,8 +120,8 @@ curl -s http://localhost:8007/  # Web UI
 ### AI/Agent/GPU Services
 ```bash
 curl -s http://localhost:8010/health  # GPU Service
-curl -s http://localhost:8011/health  # Learning Service
+curl -s http://localhost:8012/health  # Learning Service (updated from 8011)
-curl -s http://localhost:8012/health  # Agent Coordinator
+curl -s http://localhost:9001/health  # Agent Coordinator
 curl -s http://localhost:8013/health  # Agent Registry
 curl -s http://localhost:8014/health  # hermes Service
 curl -s http://localhost:8015/health  # AI Service

docs/testing/README.md

@@ -201,8 +201,8 @@ TEST_LOG_LEVEL=DEBUG
 TEST_LOG_FILE=/var/log/aitbc/test.log
 
 # Test API endpoints
-# Note: Port 8011 = Learning Service (updated port allocation)
+# Note: Port 8012 = Learning Service (updated from 8011 to avoid Coordinator API conflict)
-TEST_API_BASE_URL=http://localhost:8011
+TEST_API_BASE_URL=http://localhost:8012
 ```
 
 ## 🔄 **CI/CD Integration**

scripts/wrappers/aitbc-agent-coordinator-wrapper.py

@@ -21,7 +21,7 @@ os.environ["DATA_DIR"] = str(DATA_DIR)
 os.environ["LOG_DIR"] = str(LOG_DIR)
 
 # Create required directories
-from aitbc.paths import ensure_dir
+from aitbc.utils.paths import ensure_dir
 ensure_dir(DATA_DIR / "agent-coordinator")
 ensure_dir(LOG_DIR / "agent-coordinator")
 

systemd/aitbc-learning.service

@@ -11,7 +11,7 @@ WorkingDirectory=/opt/aitbc/apps/coordinator-api/
 Environment=PYTHONPATH=/opt/aitbc:/opt/aitbc/apps/coordinator-api/src:/opt/aitbc/packages/py/aitbc-sdk/src:/opt/aitbc/packages/py/aitbc-crypto/src
 EnvironmentFile=/etc/aitbc/.env
 EnvironmentFile=/etc/aitbc/node.env
-ExecStart=/opt/aitbc/venv/bin/python -m uvicorn app.services.adaptive_learning_app:app --host 127.0.0.1 --port 8011
+ExecStart=/opt/aitbc/venv/bin/python -m uvicorn app.services.adaptive_learning_app:app --host 127.0.0.1 --port 8012
 ExecReload=/bin/kill -HUP $MAINPID
 KillMode=mixed
 TimeoutStopSec=5