docs: add microservices architecture evaluation

- Evaluate current AITBC monolithic architecture
- Assess service independence, data ownership, deployment independence
- Analyze scaling requirements and team size
- Compare microservices pros and cons
- Recommend remaining monolithic with modular architecture
- Propose modular monolith as alternative approach
- Define migration path if microservices needed later
- Document evaluation criteria and decision rationale

docs/MICROSERVICES_ARCHITECTURE_EVALUATION.md

@@ -0,0 +1,197 @@
+# Microservices Architecture Evaluation
+
+**Date:** 2026-05-09  
+**Purpose:** Evaluate whether AITBC should evolve toward a microservices architecture
+
+---
+
+## Current Architecture Assessment
+
+### Current State
+AITBC currently uses a **monolithic architecture** with the following characteristics:
+
+**Components:**
+- Blockchain node (single service)
+- Agent daemon (single service)
+- API gateway (single service)
+- Wallet service (single service)
+- Marketplace service (single service)
+- Monitoring service (single service)
+
+**Data Layer:**
+- SQLite databases per service
+- Redis for caching
+- S3 for object storage
+
+**Communication:**
+- HTTP/REST APIs
+- Event bus for async communication
+- Direct blockchain RPC calls
+
+---
+
+## Evaluation Criteria
+
+### 1. Service Independence
+**Current Status:** Partial
+- Services share some code (aitbc package)
+- Some services have tight coupling (wallet + blockchain)
+- Event bus provides some decoupling
+
+**Assessment:** Medium service independence. Some refactoring needed for full independence.
+
+### 2. Data Ownership
+**Current Status:** Shared
+- Each service has its own SQLite database
+- Some cross-service data access required
+- No clear data ownership boundaries
+
+**Assessment:** Data ownership is not clearly defined. This would be a major challenge for microservices.
+
+### 3. Deployment Independence
+**Current Status:** Low
+- Services deployed together in most environments
+- Shared infrastructure dependencies
+- Coordinated deployments required
+
+**Assessment:** Low deployment independence. Significant infrastructure changes needed.
+
+### 4. Scaling Requirements
+**Current Status:** Low
+- Most services are not horizontally scalable
+- Blockchain node has specific scaling needs
+- Current load does not require independent scaling
+
+**Assessment:** Scaling requirements are minimal. Microservices would add complexity without clear benefit.
+
+### 5. Team Size
+**Current Status:** Small team
+- Development team is small
+- Clear ownership of components
+- Communication overhead is low
+
+**Assessment:** Small team size doesn't justify microservices complexity. Monolith is more suitable.
+
+### 6. Technology Diversity
+**Current Status:** Low
+- All services use Python
+- Shared libraries and dependencies
+- Consistent tech stack
+
+**Assessment:** Low technology diversity. No need for microservices to enable different tech stacks.
+
+---
+
+## Microservices Pros/Cons
+
+### Pros
+1. **Independent Scaling:** Each service can scale independently
+2. **Fault Isolation:** Failure in one service doesn't affect others
+3. **Technology Flexibility:** Different services can use different technologies
+4. **Faster Development:** Smaller teams can work independently
+5. **Easier Deployment:** Deploy individual services without full redeploy
+
+### Cons
+1. **Increased Complexity:** More moving parts to manage
+2. **Network Latency:** Inter-service communication adds latency
+3. **Data Consistency:** Distributed transactions are complex
+4. **Operational Overhead:** More infrastructure to monitor and maintain
+5. **Testing Complexity:** Integration testing becomes harder
+
+---
+
+## Recommendation
+
+### **Recommendation: Remain Monolithic with Modular Architecture**
+
+**Rationale:**
+1. **Team Size:** Small development team doesn't benefit from microservices complexity
+2. **Scaling Needs:** Current load doesn't require independent scaling
+3. **Data Complexity:** Shared data access patterns make microservices difficult
+4. **Operational Overhead:** Current team lacks DevOps capacity for microservices
+5. **Maturity:** Monolith is more mature and stable
+
+### **Alternative: Modular Monolith**
+
+Instead of full microservices, implement a **modular monolith**:
+
+**Benefits:**
+- Clear module boundaries (similar to microservices)
+- Single deployment unit (simpler operations)
+- Shared database (avoid distributed transactions)
+- Easier to evolve to microservices if needed later
+
+**Implementation:**
+1. Define clear module boundaries based on domain
+2. Implement service layer for each module
+3. Use event bus for inter-module communication
+4. Maintain shared database with clear ownership
+5. Implement feature flags for gradual feature rollout
+
+---
+
+## Migration Path (If Microservices Needed Later)
+
+If future requirements dictate microservices architecture, follow this path:
+
+### Phase 1: Modularization (Current)
+- Define clear module boundaries
+- Implement service layers
+- Add feature flags
+- Improve monitoring
+
+### Phase 2: Database Separation
+- Identify data ownership per module
+- Implement database per service
+- Add data migration scripts
+- Implement API-based data access
+
+### Phase 3: Service Extraction
+- Extract one service at a time
+- Start with low-risk services (monitoring)
+- Use feature flags for gradual rollout
+- Maintain dual-write during migration
+
+### Phase 4: Full Microservices
+- Complete service extraction
+- Implement service mesh (if needed)
+- Add distributed tracing
+- Implement circuit breakers
+
+---
+
+## Conclusion
+
+**AITBC should remain a monolithic application with modular architecture.**
+
+The current architecture is appropriate for the team size, scaling requirements, and operational capacity. Implementing a modular monolith provides most microservices benefits without the complexity overhead.
+
+Revisit this evaluation when:
+- Team size grows beyond 10 developers
+- Independent scaling becomes necessary
+- Different technology stacks are required
+- Service failure isolation becomes critical
+
+---
+
+## Next Steps
+
+1. **Implement Modular Monolith**
+   - Continue current modularization efforts
+   - Define clear module boundaries
+   - Implement service layers
+
+2. **Improve Monitoring**
+   - Add distributed tracing (completed)
+   - Improve metrics collection
+   - Add alerting
+
+3. **Enhance Deployment**
+   - Implement blue-green deployments (completed)
+   - Add feature flags (completed)
+   - Improve rollback capabilities
+
+4. **Prepare for Future**
+   - Document module boundaries
+   - Identify data ownership
+   - Plan for potential future migration