init projectmycelium
This commit is contained in:
mik-tf
222
docs/dev/design/archive/vision/parts/architectural-overview.md
Normal file
222
docs/dev/design/archive/vision/parts/architectural-overview.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# Project Mycelium - Architectural Overview
|
||||
|
||||
## Single Source of Truth for AI-Assisted Development
|
||||
|
||||
This document serves as the comprehensive architectural reference for the Project Mycelium, designed specifically to provide AI coders and developers with a unified understanding of the system's design principles, patterns, and implementation standards.
|
||||
|
||||
## Core Design Principles
|
||||
|
||||
### 1. **Log-Free Codebase**
|
||||
- **Policy**: Zero `log::` statements in main/development branches
|
||||
- **Rationale**: Clean code, production readiness, AI-friendly development
|
||||
- **Implementation**: 881+ log statements removed codebase-wide (2025-01-06)
|
||||
- **Reference**: [Log-Free Codebase Policy](./log-free-codebase-policy.md)
|
||||
|
||||
### 2. **Builder Pattern Architecture**
|
||||
- **Centralized Construction**: All complex objects use builder patterns
|
||||
- **Single Source of Truth**: Eliminates duplicate initialization code
|
||||
- **Key Builders**:
|
||||
- `SessionDataBuilder` (UserPersistentData)
|
||||
- `ConfigurationBuilder` (Environment variables)
|
||||
- `ResponseBuilder` (HTTP responses)
|
||||
- `ServiceFactory` (Service instantiation)
|
||||
- **Reference**: [Builder Pattern Architecture](./builder-pattern-architecture.md)
|
||||
|
||||
### 3. **Persistent Data Only**
|
||||
- **No Mock Data**: All MockDataService usage eliminated
|
||||
- **User Data Directory**: Single source of truth for user data
|
||||
- **Persistent Storage**: All data operations use `user_data/` directory
|
||||
- **Migration Complete**: 100% mock data removal achieved
|
||||
|
||||
### 4. **Centralized Response Handling**
|
||||
- **ResponseBuilder**: All HTTP responses use centralized builder
|
||||
- **Migration Status**: 78+ patterns migrated across 4 controllers
|
||||
- **Completed Controllers**: Auth (10), Wallet (49), Product (7), Currency (12)
|
||||
- **Reference**: [ResponseBuilder Migration Guide](./response-builder-migration.md)
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Controllers Layer
|
||||
```
|
||||
src/controllers/
|
||||
├── auth.rs ✅ ResponseBuilder migrated (10 patterns)
|
||||
├── wallet.rs ✅ ResponseBuilder migrated (49 patterns)
|
||||
├── product.rs ✅ ResponseBuilder migrated (7 patterns)
|
||||
├── currency.rs ✅ ResponseBuilder migrated (12 patterns)
|
||||
├── dashboard.rs 🔄 In progress (50+ patterns, log-free)
|
||||
├── marketplace.rs ⏳ Pending migration
|
||||
├── order.rs ⏳ Deferred (complex structure)
|
||||
└── rental.rs ⏳ Pending migration
|
||||
```
|
||||
|
||||
### Services Layer
|
||||
```
|
||||
src/services/
|
||||
├── farmer.rs ✅ ServiceFactory migrated
|
||||
├── currency.rs ✅ ServiceFactory migrated
|
||||
├── user_persistence.rs ✅ ServiceFactory migrated
|
||||
├── session_manager.rs ✅ ServiceFactory migrated
|
||||
├── node_rental.rs ✅ ServiceFactory migrated
|
||||
├── slice_rental.rs ✅ ServiceFactory migrated
|
||||
└── order.rs ✅ ServiceFactory migrated
|
||||
```
|
||||
|
||||
### Utilities Layer
|
||||
```
|
||||
src/utils/
|
||||
├── response_builder.rs ✅ Centralized HTTP response handling
|
||||
├── configuration.rs ✅ ConfigurationBuilder implementation
|
||||
└── data_cleanup.rs ✅ Log-free data utilities
|
||||
```
|
||||
|
||||
### Models Layer
|
||||
```
|
||||
src/models/
|
||||
└── builders.rs ✅ SessionDataBuilder and other builders
|
||||
```
|
||||
|
||||
## Migration Progress
|
||||
|
||||
### Completed Migrations ✅
|
||||
1. **ServiceFactory Migration**: 100% complete
|
||||
- All service instantiations use centralized factory
|
||||
- Mock data completely eliminated
|
||||
- Persistent data access throughout
|
||||
|
||||
2. **ConfigurationBuilder Migration**: 100% complete
|
||||
- All environment variable access centralized
|
||||
- Home and Auth controllers fully migrated
|
||||
- Consistent configuration handling
|
||||
|
||||
3. **SessionDataBuilder Migration**: 100% complete
|
||||
- All UserPersistentData initialization uses builder
|
||||
- Single source of truth for user data construction
|
||||
- Consistent field handling with `..Default::default()`
|
||||
|
||||
4. **Log-Free Codebase**: 100% complete
|
||||
- 881+ log statements removed codebase-wide
|
||||
- Clean compilation with zero errors
|
||||
- Production-ready code quality
|
||||
|
||||
5. **ResponseBuilder Migration**: 78 patterns complete
|
||||
- Auth Controller: 10/10 patterns ✅
|
||||
- Wallet Controller: 49/49 patterns ✅
|
||||
- Product Controller: 7/7 patterns ✅
|
||||
- Currency Controller: 12/12 patterns ✅
|
||||
|
||||
### In Progress 🔄
|
||||
1. **Dashboard Controller ResponseBuilder Migration**
|
||||
- 50+ HttpResponse patterns identified
|
||||
- Log cleanup completed (443 statements removed)
|
||||
- Ready for systematic migration
|
||||
|
||||
### Pending ⏳
|
||||
1. **Remaining Controllers**: marketplace, rental, pool, legal, docs, debug
|
||||
2. **Order Controller**: Deferred due to structural complexity
|
||||
3. **Final Documentation**: Consolidation and review
|
||||
|
||||
## Development Standards
|
||||
|
||||
### Code Quality
|
||||
- **Zero Compilation Errors**: All migrations maintain clean builds
|
||||
- **Minimal Warnings**: Only unused variable warnings acceptable
|
||||
- **Builder Pattern Usage**: Mandatory for complex object construction
|
||||
- **Persistent Data Only**: No mock data in production code
|
||||
|
||||
### Migration Approach
|
||||
- **Manual Systematic Migration**: Preferred over automated scripts
|
||||
- **Bulk All-at-Once Edits**: Efficient approach for simple controllers
|
||||
- **Section-by-Section**: For complex controllers (dashboard, order)
|
||||
- **Compilation Verification**: `cargo check` after each batch
|
||||
|
||||
### AI-Assisted Development
|
||||
- **Log-Free Code**: Simplified analysis and pattern recognition
|
||||
- **Centralized Patterns**: Consistent builder usage across codebase
|
||||
- **Single Source of Truth**: This document for architectural decisions
|
||||
- **Clean Abstractions**: Simplified code structure for AI tools
|
||||
|
||||
## Technical Specifications
|
||||
|
||||
### ResponseBuilder API
|
||||
```rust
|
||||
ResponseBuilder::ok()
|
||||
.json(data)
|
||||
.build()
|
||||
|
||||
ResponseBuilder::bad_request()
|
||||
.json(error_data)
|
||||
.build()
|
||||
|
||||
ResponseBuilder::unauthorized()
|
||||
.json(auth_error)
|
||||
.build()
|
||||
```
|
||||
|
||||
### ServiceFactory Usage
|
||||
```rust
|
||||
let service = ServiceFactory::create_farmer_service()
|
||||
.build()?;
|
||||
```
|
||||
|
||||
### ConfigurationBuilder Access
|
||||
```rust
|
||||
let config = ConfigurationBuilder::new()
|
||||
.jwt_secret()
|
||||
.gitea_client_id()
|
||||
.build();
|
||||
```
|
||||
|
||||
### SessionDataBuilder Pattern
|
||||
```rust
|
||||
let user_data = SessionDataBuilder::new_user(email);
|
||||
let existing_data = SessionDataBuilder::load_or_create(email);
|
||||
```
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
### Before Migration
|
||||
- 881+ log statements across 24 files
|
||||
- Multiple mock data services
|
||||
- Scattered configuration access
|
||||
- Direct HttpResponse usage
|
||||
|
||||
### After Migration
|
||||
- 0 log statements (100% reduction)
|
||||
- Single persistent data source
|
||||
- Centralized configuration management
|
||||
- Unified response handling
|
||||
- Clean compilation with minimal warnings
|
||||
|
||||
## Future Roadmap
|
||||
|
||||
### Phase 1: Complete ResponseBuilder Migration
|
||||
- Dashboard controller (in progress)
|
||||
- Marketplace controller
|
||||
- Rental controller
|
||||
- Remaining simple controllers
|
||||
|
||||
### Phase 2: Advanced Optimizations
|
||||
- Order controller migration (complex)
|
||||
- Performance optimizations
|
||||
- Additional builder patterns
|
||||
- Code consolidation opportunities
|
||||
|
||||
### Phase 3: Documentation and Maintenance
|
||||
- Complete architectural documentation
|
||||
- Developer onboarding guides
|
||||
- AI coding best practices
|
||||
- Maintenance procedures
|
||||
|
||||
## References
|
||||
|
||||
- [Log-Free Codebase Policy](./log-free-codebase-policy.md)
|
||||
- [Builder Pattern Architecture](./builder-pattern-architecture.md)
|
||||
- [ResponseBuilder Migration Guide](./response-builder-migration.md)
|
||||
- [Migration Progress Tracker](./builder-pattern-progress-tracker.md)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-06
|
||||
**Architecture Version**: 2.0
|
||||
**Status**: Active Development
|
||||
**Next Milestone**: Complete Dashboard Controller Migration
|
||||
Reference in New Issue
Block a user